通过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。使用场景示例:就表示在东京时间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(再互动) re-engagement retargeting(再营销) re-engagement re-attribution
再营销  再互动应用内事件 re-engagement retargeting(再营销) 广告主侧定义的事件名称 re-engagement-in-app-event
再营销  再归因(reattribution)  reinstall retargeting(再营销) re-attribution re-attribution
用户获取  Reinstall(重装激活) 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_type字段。
    注意:event_type字段也可以用于判断event_name字段和skad_redownload字段。
  • 各消息类型所对应的字段值请下表

举例来说,

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

  • event_type: skad-re-download

由此可以确定:

  • 这是一个重新下载事件。
  • event_name: install
  • skad_redownload: true
数据时效性
  • 激活、重装和应用内事件:
    • 按天进行数据处理
    • AppsFlyer收到iOS回传后的第二天发送到您设置的端点
    • 您会在UTC时间的08:00–11:00接收到事件消息(具体时间可能会有所波动)
    • 举例来说,周一接收到的回传数据会在周二UTC时间的05:00开始发送
  • 来自iOS的回传和回传副本:AppsFlyer收到消息后将很快发送。
消息示例 请见表格。示例的文件格式为JSON。 SKAN示例消息

SKAN归因的消息类型

消息类型  event_name字段 skad_redownload字段 event_type字段
激活假量  install
  • 可能出现的值:false、空白值、null。 
  • 若该字段未出现在消息中,则视对应值为false。 
skad-installs
重新下载(redownloads)  install True skad-re-download
应用内事件  广告主侧设置的事件名称 广告主侧设置的事件名称 skad-in-app-event
来自iOS的回传 本消息中不可用 本消息中有时可用 skad-postback
回传备份 本消息中不可用 本消息中有时可用 skad-postback-copy

 

设置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个端点
    • SKAdNetwork3个端点
端点返回码 收到消息后,您的端点必须返回HTTP 200状态代码。
AppsFlyer服务器加白 在您的防火墙和安全系统中对AppsFlyer服务器的IP地址加白,以确保AF服务器与端点之间的数据传输保持畅通。
TLS版本
端口   端口:80, 443

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

针对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秒的计时机制,如果在这4秒内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就开始生效,将数据发送到端点。  

配置身份验证令牌

通过使用Push API身份验证令牌,客户可以无缝接入并保护其Push API消息安全,只需为请求的令牌添加一个可自定义的授权header即可。
您可以通过为每个App ID定义令牌名称和值,自定义随Push API消息一同发送的授权 header。这样不仅可确保消息的安全性,也能满足您的特定需求。

其他操作 — 端点管理

修改端点设置

请注意:只有AppsFlyer账户所有者才能更改Push API设置。其他类型的用户只能查看该设置。

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

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

删除端点

请注意:只有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设置,但不能对其进行更改。

测试消息中的身份验证令牌 测试消息的header不包含身份验证令牌。

我可以在Push API请求中添加自定义header吗?

不可以。Push API仅支持使用header传递身份验证令牌。不支持额外的自定义header(如consumer-key)。

如果需要传递额外参数,请将其包含在URL中。使用场景示例:

https://your.server.com?consumer_key=abc456