通过Push API获取原始数据

高阶付费
推荐用于
营销人员 开发商
最近更新：

概要：本文重点解释如何将已归因事件的原始数据实时发送到您的服务器端点。

6970_Push_API_image.png

Push API

使用AppsFlyer或SKAN归因，生成原始数据后，您可以通过Push API将这些数据以推送消息的形式传输到您的服务器，并自行选择消息类型、消息内容，同时设置目标端点。

可用的消息类型、字段以及数据时效性取决于您使用的归因框架（AppsFlyer或SKAN），这在以下几个章节中会有详细说明。

AppsFlyer归因消息

消息特征

主要特点 具体内容
消息类型区分
  • 您可以按端点来区分消息（每个应用最多可对应6个端点），也可以通过下列字段的值来判断消息类型。
    • event_name
    • conversion_type
    • campaign_type 
  • 各消息类型所对应的字段值请见下表。

示例：

如果一个消息中包含以下字段：

  • conversion_type=install
  • campaign_type=organic
  • event_name=install

对照下表可判断出该事件是一个自然量的激活事件。
数据时效性

AppsFlyer平台记录到事件后会立即发出消息。发送过程一般需要几分钟。 
消息内容（字段）
  • 消息结构为key:value。
  • 请参考AppsFlyer归因Push API的可用字段。
  • 每个键值对代表一个原始数据字段。详情请见AppsFlyer的原始数据字段说明。 
  • 若键值为空或null，则不会出现在消息中。
  • 以下所附示例中同时包含了null和空白字段，但实际回传中不会出现这两种字段。示例的文件格式为JSON。
时间戳字段的格式：
  • UTC时间戳：yyyy-mm-dd hh:mm:ss.sss。 举例来说，如果时间戳显示为2019-09-17 00:09:00.123，就表示在东京时间18:00发生了一个事件，系统会自动将事件时间将转换为UTC时间，即09:00。请注意该字段记录的时间是UTC时间。
  • 指定时区（针对具体应用）的时间戳：yyyy-mm-dd hh:mm:ss.sss±th:tm。举例来说，如果时间戳显示为2019-09-17 18:00:16.000+0900，就表示在东京时间18:00发生了一个事件，时间戳以18:00+09:00的格式记录该事件的时间，其中的09:00是指东京时区。 

可用的消息类型

归因场景 消息类型 conversion_type字段 campaign_type字段 event_name字段 event_type字段
用户获取 激活* install

非自然量显示为：UA

自然量显示为：organic

install

  • install

  • organic-install
用户获取 UA应用内事件 install

非自然量显示为：UA

自然量显示为：organic

广告主侧定义的事件名称

  • install-in-app-event

  • organic-install-in-app-event

再营销

 再互动 re-engagement retargeting re-engagement

re-engagement
再营销 再互动应用内事件 re-engagement retargeting 广告主侧定义的事件名称

re-engagement-in-app-event
再营销 再归因 reinstall retargeting re-attribution

re-attribution
用户获取 重装 reinstall

非自然量显示为：UA

自然量显示为：organic

reinstall

  • reinstall

  • organic-reinstall
再营销 再归因应用内事件 reinstall retargeting 广告主侧定义的事件名称

re-attribution-in-app-event
*一部分浏览型激活会被归因到restricted media source（受限媒体渠道）。

专属字段

显示名称 Push API名称
Selected currency*
（指定货币）		 selected_currency
Revenue in selected currency
（按指定货币显示的收入数据）		 revenue_in_selected_
currency
Cost in selected currency
（以指定货币为单位的成本数据）		 cost_in_selected_
currency
Device download time selected timezone
（按指定时区显示的设备层级下载时间）		 device_download_time_selected_timezone
Attributed touch time selected timezone
（按指定时区显示归因到的触达时间）		 attributed_touch_time_selected_timezone
Install time selected timezone
（按指定时区显示的激活时间）		 install_time_selected_
timezone
Event time selected timezone
（按指定时区显示的事件时间）		 event_time_selected_
timezone

Selected timezone(*)
（指定时区）

 selected_timezone
*视API消息发送时的有效应用层级设置而定。

SKAN归因消息

本章节重点说明SKAN框架中的可用消息（报告类型），以及如何判断消息类型。请先通读本章，然后参考SKAN归因端点设置指南。

您还可参考SKAN原始数据字段，因为Push API消息的结构和字段与其对应。

消息特征：

主要特点 具体内容
消息类型区分
  • 所有消息都会发送到您设置的1个端点。
  • 请根据下列字段判断消息类型：
    • event_name
    • skad_redownload
  • 各消息类型所对应的字段值请见下表。

示例：

如果一个消息中包含以下字段：

  • event_name: install
  • skad_redownload: true

由于skad_redownload: true，因此可以判断这是一个重装事件。 
数据时效性
  • 激活、重装和应用内事件：
    • 按天进行数据处理
    • AppsFlyer收到iOS回传后的第二天发送到您设置的端点
    • 您会在UTC时间的05:00–08:00接收到事件消息（具体时间可能会有所波动）
    • 举例说明：周一接收到的回传数据会在周二UTC时间的05:00开始发送
  • 来自iOS和Postbacks Copy的回传：数据到达AppsFlyer服务器后立即发出
消息示例 请见SKAN消息示例，示例的文件格式为JSON。

SKAN归因的消息类型

消息类型 

event_name字段

skad_redownload字段

event_type字段
激活  install
  • 可能出现的值：false、空白值、null。
  • 若该字段未出现在消息中，则视对应值为false。

skad-installs
重装 install True

skad-re-downloads
应用内事件

广告主侧设置的事件名称

 广告主侧设置的事件名称

skad-in-app-events
来自iOS的回传

本消息中不可用

 本消息中有时可用

skad-postbacks
回传备份

本消息中不可用

 本消息中有时可用

skad-postbacks-copy


判断SKAN归因中的消息类型

请注意：该方式不可用于iOS直接发送的回传备份消息。

PushAPI-2_en-us.png

设置Push API端点

 注意

出于下列原因，请不要使用Push API将AppsFlyer归因产生的数据发送给第三方：

  • 如果用户拒绝将其数据发送给第三方，这种做法就违反了有关的隐私条例（如CCPA等）
  • 某些媒体渠道所提供的用户级数据会在使用方式和/或共享方式方面有所限制。请务必遵守这些媒体渠道的使用条款。
    如X Ads、Snapchat、Pinterest。

请注意：该事项不适用于SKAN数据，您可以使用Push API将SKAN数据发送到第三方端点。

请按下表所列的步骤设置Push API。

Push API设置流程

步骤顺序 AppsFlyer归因 SKAdNetwork归因 
1

如果您已经有正在使用中的Push API端点，请跳过这一步。

请确保您的服务器符合相关要求。
2

若要使用AppsFlyer归因，请按照Push API设置规划表来规划端点的设置。

不适用
3

设置AppsFlyer归因端点

设置SKAdNetwork归因端点

服务器端须符合的要求（广告主侧）

请确保您的服务器符合以下要求：

服务器端要求

端点URL
  • 域名有效
  • 每个应用所对应的独立端点数上限如下：
    • AppsFlyer：6个端点
    • SKAdNetwork：3个端点
端点返回码 收到消息后，您的端点必须返回HTTP 200状态代码。
AppsFlyer服务器加白

在您的防火墙和安全系统中对AppsFlyer服务器的IP地址加白，以确保AF服务器与端点之间的数据传输保持畅通。
TLS版本
端口 

80和443端口

请注意！这里会使用一个为时2秒的计时机制，如果在这2秒内AppsFlyer的服务器没有接收到发送成功的消息，那么系统就会认为该消息发送失败。

针对AppsFlyer归因的Push API设置规划表

  • 请参照下表说明，规划您的AppsFlyer归因端点设置，下图中的数字与下表中的行数相对应。
  • 本节内容不涉及SKAdNetwork，有关SKAN归因的说明请参见SKAdNetwork归因设置。 

端点 

PushAPI_us-en.png

端点规划表

序号

设置

 具体内容 在本栏中记录您的设置规划
1

方法

POST 或者 GET

  

2

端点URL

 -  
3 事件消息类型
  • 选择至少一种事件消息类型。
  • 必须要先记录到至少一个应用内事件后，您才能勾选对应的应用内事件消息，否则该选项将显示为不可用。

InappSelectionDisabled_us-en.png

 

4
  • 字段 
  • 字段列表是所有消息类型共有的

 重要提示

如果您勾选了全选，所有新添加的字段都会自动选中。这时，请确保您能够支持所有自动添加的新增字段，以免出现问题。

选择所需的字段。

  • 最常用的字段是默认勾选的
  • 空/null的字段不会被发送
  
5

应用内事件类型

 

您可以按应用内事件进行筛选，以控制发送到端点的流量。

  • 您可以选择一个、多个或所有应用内事件。请注意：如果事件未显示在列表中，请直接搜索该事件。
  • 如果点击全选，系统会自动添加新的应用内事件
  • 应用内事件必须至少被记录到一次，相应的消息选项才会显示为可选。必要情况下可使用S2S来发送事件。
  • mceclip1.png
  

设置AppsFlyer归因端点

注意：只有AppsFlyer账户的管理员才能更改Push API的设置。其他类型的用户只能查看该设置。

请按以下步骤添加AppsFlyer归因端点：
  1. 从AF后台进入报告 > API数据接口，向下滚动到Push API部分。
  2. 单击添加端点。
  3. 选择HTTP方式：POST或GET
  4. 输入端点URL。 如果收到this URL is not safe（该URL不安全）的消息，请联系AppsFlyer技术支持。
  5. 选择一种或多种事件类型。请注意：如果应用内事件消息显示为不可用，说明尚未记录到任何应用内事件。 
  6. 选择Push API消息中需要包含的字段。请注意：
    • 消息中始终包含必填字段：应用ID、事件名称、事件时间、IDFA（iOS）或Advertising ID（安卓）
    • 您可使用下图所示的控件来选择可选字段。

      PushAPIFieldSelect1.jpg

      • 最常用的字段是默认勾选的，您可以手动取消这些选项。
      • 根据需要选择可选字段。
      • 点击清除全部，清除所有可选字段。
      • AF系统不会发送null/空的字段及其对应的键，这在数据入库BI和解析过程中需特别留意。
  7. 选择一个或多个事件（最多52个），也可选择“所有应用内事件”。
    • 该列表中只包含已经记录到的事件类型。如果其中没有显示您想要的事件类型，请先使用测试设备发送这类事件。
  8. 点击保存后，该Push API就开始生效，将转化数据发送到端点。
  9. 请按以下步骤测试端点。

测试端点：

  1. 点击发送测试
    发送测试按钮下方会显示测试结果。
    测试消息发送到端点后，如果显示测试失败，请确保您已对AppsFlyer服务器的IP地址加白。
    请注意：这里使用了一个为时2秒的计时机制，如果在这3秒内AF的服务器没有接收到发送成功的消息，那么系统就会认为该消息发送失败。
  2. 您可以查看测试消息的副本，以此来确认您的端点是否接收到了测试消息。

设置SKAdNetwork归因端点

注意：只有AppsFlyer账户的管理员才能更改Push API的设置。其他类型的用户只能查看该设置。

请按以下步骤添加SKAdNetwork Push API端点：
  1. 从AF后台进入报告 > API数据接口，向下滚动到Push API部分。
  2. 选择SKAdNetwork作为归因实体。  
  3. 点击添加端点。 
    请注意    ：您可以为每个应用定义1-3个SKAdNetwork端点。 
  4. 选择HTTP方式：POST或GET
  5. 输入端点URL。 如果收到this URL is not safe（该URL不安全）的消息，请联系AppsFlyer技术支持。
  6. AF系统不会发送null/空的字段及其对应的键，这在数据入库BI和解析过程中需特别留意。
  7. 点击保存后，该Push API就开始生效，将数据发送到端点。 

其他操作 — 端点管理

修改端点设置

注意：只有AppsFlyer账户的管理员才能更改Push API的设置。其他类型的用户只能查看该设置。

请按以下步骤修改端点设置：

  1. 进入报告 > API数据接口。向下滚动到Push API部分。
  2. 找到要修改的端点。
  3. 进行修改。
  4. 点击保存。

删除端点

注意：只有AppsFlyer账户的管理员才能更改Push API的设置。其他类型的用户只能查看该设置。

删除端点 ：

  1. 从AF后台进入报告 > API数据接口，向下滚动到Push API部分。
  2. 单击删除端点 。
  3. 点击保存后，端点就会被删除。

故障排查、特点和限制

未收到测试消息

如果您的服务器通过IP地址来限制访问，在这种情况下没有接收到测试消息可能是因为没有对所有的AppsFlyer IP地址加白。 

再营销应用内事件的重复

如果用户点击了再营销广告并产生了付费事件，而该事件又发生在UA再互动窗口期内，这时再营销应用内事件就会发生重复。这一机制背后的逻辑是要将收入同时归因到UA渠道和再营销渠道。

如果您同时启用了以下两项，就会发生事件重复：

  • UA应用内事件
  • 再营销应用内事件

事件重复的判断及去重

 

应用内事件消息不可用

InappSelectionDisabled_us-en.png

  • 应用内事件必须至少被记录到一次，相应的消息选项才会显示为可选。
  • 您可以使用测试设备生成应用内事件，也可以使用S2S API手动生成事件。

推送消息缺失和CloudFront

如果您使用Amazon CloudFront作为端点，请检查您的CloudFront是否通过421拒绝码拒绝接收消息。如果发生上述情况，请参考如何选择CloudFront对HTTPS请求的响应方式。

端点错误消息

具体问题：设置端点URL时显示“this URL is not safe“（此URL不安全）的消息。

应对办法：联系AppsFlyer技术支持，在问题描述中包含应用ID、端点URL，以及错误消息截屏。

特点与局限性

维度 备注
广告平台 不可用
代理商 不支持
应用设定的时区 支持
应用设定的货币 支持
大小限制 不适用
自然量 是
非自然 是
数据时效性 持续滚动
历史数据 不支持。如果出现数据缺失，请使用Pull API来拉取数据。在SKAN归因的场景下，您可以通过Data Locker获取部分历史数据（具体取决于Data Locker的数据可用性窗口）。

账户所有者/用户权限

只有AppsFlyer账户所有者才能更改Push API设置。

  • 每个AppsFlyer账户下只能有一个账户所有者。账户所有者是相关AppsFlyer账户中的首个用户（即开户时创建的用户）。

其他类型的用户可以查看Push API设置，但不能对其进行更改。

另请参见