Push API V2.0实时回传原始数据

概览:实时推送归因的激活和应用内事件数据到服务器端端点。支持在您的IT系统中使用数据。

Push API V2.0

Push API新闻

  • Push API V2.0将与AppsFlyer原始数据第5.0版本规范对齐。
    • 额外字段:与Push API V1.0相比,V2.0新增40多个字段;
    • 字段选择 :选择要发送的字段,以减小Push API消息的大小。
    • 空值将不会被发送 :未来,我们计划停止发送null/空值字段,以及其中的参数。
    • 应用内事件过滤 :选择要发送的应用内事件,以减少处理。
  • Push API V1.0 已过时,并将于2020年8月31日停用。
  • 开发人员:Push API V1.0到Push API V2.0迁移指南

关于Push API

Push API将归因的激活和应用内事件消息,实时发送到您的服务器端端点。这样做可以使您可以通过多个环境和接触点来跟踪用户的路径。

可以通过限制以下内容来减少发送到端点的数据量:

  • 选定的消息和应用内事件类型。
  • 选定的字段。

您可能感兴趣的其他AppsFlyer数据传输解决方案:

事件消息类型

事件消息类型
✓=适用, - 不适用)

广告活动类型

转化类型

value of is_
retargeting

value of retargeting_

conversion_

类型

非自然 自然 再营销
用户获取 激活(*) False    -
用户获取 激活应用内事件 False    -

再营销

再互动Re-engagement   - -
再营销 再互动Re-engagement应用内事件 再互动 - -
再营销 再归因Re-attribution 再归因 - -
再营销 再归因Re-attribution应用内事件 再归因 -
*激活归因是限制媒体平台(restricted)的,Push API将不会发送其后续事件。

消息结构和唯一字段

Push API消息取决于HTTP方法:

  • GET:数据参数附加到URL字符串
  • POST:数据参数以JSON格式包含在消息正文中
  • 以下示例仍包含null/空值字段,但在未来,我们的计划是停发所有null/空值字段。

可用字段

  • Push API推送消息包含此处所述的字段。
  • 如有其他新增字段被添加到AppsFlyer平台,会陆续添加进Push API推送信息中。您的导入/解析机制应考虑到这一点。

时间戳字段的格式

  • 对于UTC中的时间戳字段:格式 yyyy-mm-dd hh:mm:ss.sss 。例如,显示为 2019-09-17 00:09:25.123 。一个事件在东京时间14:00发生。事件时间将转换为UTC,即05:00。记录的时间是UTC时间。
  • 对于选定时区中的时间戳字段:格式  yyyy-mm-dd hh:mm:ss.sss±th:tm 。例如  2019-01-20 04:51:16.000+0000 。一个事件在东京时间14:00发生。显示的活动时间记录为14:00+09:00。09:00是东京时区。 
Push API特有字段
显示名称 V2.0 名称 备注
所选货币 selected_currency 这是在发送API消息时生效的应用程序级别设置。
选定货币的收入 revenue_in_selected_
currency
 
选定货币的费用 cost_in_selected_
currency
 
设备下载时间(根据选择的时区) device_download_time_selected_
timezone
 
归因的点击或展示时间(根据选择的时区) attributed_touch_time_
selected_timezone
 
激活时间(根据选择的时区) install_time_selected_
timezone
 
事件事件(根据选择的时区) event_time_selected_
timezone
 
选择的时区 selected_timezone 这是在发送API消息时生效的应用程序级别设置。

Push API可用字段

Push API V2.0名称 Push API显示名称 注释
advertising_id 广告 ID  
af_ad 广告  
af_ad_id 广告ID  
af_ad_type 广告类型  
af_adset 广告组  
af_adset_id 广告组ID  
af_attribution_lookback 归因回溯窗口  
af_c_id 广告系列活动ID  
af_channel 渠道  
af_cost_currency 成本货币  
af_cost_model 成本模式  
af_cost_value 成本值  
af_keywords 关键词  
af_prt 合作伙伴  
af_reengagement_window 再互动窗口  
af_siteid 子渠道 ID  
af_sub_siteid 次级子渠道ID  
af_sub1 子参数 1  
af_sub2 子参数 2  
af_sub3 子参数 3  
af_sub4 子参数 4  
af_sub5 子参数 5  
amazon_aid Amazon Fire ID  
android_id 安卓ID  
api_version API版本  
app_id App ID  
app_name 应用名称  
app_version 应用版本  
appsflyer_id AppsFlyer ID  
attributed_touch_time 已归因的触达时间  
attributed_touch_time_selected_timezone 归因的点击或展示时间(根据选择的时区) 特定于Push API。
attributed_touch_type 已归因的触达类型  
bundle_id 捆绑ID  
广告系列 广告系列活动  
carrier carrier  
城市 城市  
contributor_1_af_prt 贡献者 1 合作伙伴  
contributor_1_campaign 贡献者 1 广告系列  
contributor_1_match_type 贡献者 1 匹配类型  
contributor_1_media_source 贡献者 1 媒体来源  
contributor_1_touch_time 贡献者 1 触达时间  
contributor_1_touch_type 贡献者 1 触达类型  
contributor_2_af_prt 贡献者 2 合作伙伴  
contributor_2_campaign 贡献者 2 广告系列  
contributor_2_match_type 贡献者 2 匹配类型  
contributor_2_media_source 贡献者 2 媒体来源  
contributor_2_touch_time 贡献者 2 触达时间  
contributor_2_touch_type 贡献者 2 触达类型  
contributor_3_af_prt 贡献者 3 合作伙伴  
contributor_3_campaign 贡献者 3 广告系列  
contributor_3_match_type 贡献者 3 匹配类型  
contributor_3_media_source 贡献者 3 媒体来源  
contributor_3_touch_time 贡献者 3 触达时间  
contributor_3_touch_type 贡献者 3 触达类型  
cost_in_selected_currency 选定货币的费用 特定于Push API。
country_code 国家代码  
custom_data 自定义数据  
CUSTOMER_USER_ID 客户用户ID  
deeplink_url 深度链接URL 从2020年第一季度开始
device_category 设备类别  

device_download_time 

设备下载时间 直到2020年2月3日,还提供了一个附加字段download_time。 
device_type 设备型号  
dma DMA  
device_download_time_selected_timezone 设备下载时间(根据选择的时区)

特定于Push API。

直到2020年2月3日,还提供了一个附加字段,即download_time_selected时区。

event_name 事件名称  
event_revenue 事件收入  
event_revenue_currency* 事件收入货币  
event_revenue_usd 时间收入 USD  
event_source 事件来源  
event_time 事件时间  
event_time_selected_timezone 事件事件(根据选择的时区) 特定于Push API。
event_value 事件值  
gp_broadcast_referrer GP 广播 Referrer  
gp_click_time Google Play 点击时间  
gp_install_begin Google Play 安装开始时间  
gp_referrer Google Play Referrer  
http_referrer HTTP Referrer  
idfa IDFA  
idfv IDFV  
imei IMEI  
install_app_store 安装应用商店  
install_time 安装时间  
install_time_selected_timezone 激活时间(根据选择的时区) 特定于Push API。
ip IP  
is_LAT 是LAT 从2019年第四季度开始启用
is_primary_attribution 是否是主要归因源  
is_receipt_validated 是否验证收据  
is_retargeting 是否再营销  
keyword_id Keyword ID  
keyword_match_type 关键词匹配类型  
语言 language  
match_type 匹配类型  
media_source 媒体渠道  
network_account_id 媒体网络账号 ID  
oaid OAID  
operator operator  
original_url 原始 URL  
os_version OS 版本  
平台 平台  
postal_code 邮政编码  
地区 地区  
retargeting_conversion_type 重定向转化类型  
revenue_in_selected_currency 选定货币的收入 特定于Push API。
sdk_version SDK版本  
selected_currency 所选货币 特定于Push API。
selected_timezone 选择的时区 特定于Push API。
州/县 州/县  
store_reinstall (False=Download, True=Redownload) Store Reinstall  
user_agent User Agent  
wifi WIFI  

设置Push API

注意

某些媒体源限制了如何提供他们的用户级数据,并与第三方使用、共享数据。确保您遵守媒体来源的使用条款。
例如, Facebook, Twitter, Snapchat, Pinterest。

要设置Push API,请完成下方操作列表。

Push API操作列表
操作编号 设置新端点
1

完成服务器端要求清单

2

使用规划清单,规划端点设置

3

配置端点

服务器端要求清单(您的服务器)

确保您的服务器符合此处列出的要求。

服务器端要求
端点网址
  • 有效域名
  • 每个应用程序可以使用同一端点一次。
  • 每个应用程序的最大端点数:6
端点返回码 收到消息后,端点必须返回HTTP 200状态代码。
将AppsFlyer服务器列入白名单

将AppsFlyer服务器 IP地址列入白名单,以确保与端点进行数据传输。

TLS版本
Ports端口 

端口: 80,443

Push API规划清单

  • 使用下面的清单来规划端点设置。图中的数字与下面清单中的行号匹配。

Endpoint端点 

PushAPI_us-en.png

Endpoint端点规划表

并不是。

设置

细节 您的设定
1

方法

POST 或者 GET  

2

端点网址

-  
3 事件消息类型
  • 选择至少一种事件消息类型。
  • 要选择应用内事件消息,您需要记录到一个应用内事件。否则您无法选择应用内事件消息。

InappSelectionDisabled_us-en.png

 

4

字段 

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

选择所需的字段。

  • 最常用的字段是默认预先选择的。
  • 未来,我们计划停发null/空字段。此处包含相关值(key)当您进行字段解析/字段入库的时候,烦请注意此处。
 
5

应用内事件类型

 

按应用内事件过滤,以减少发送到您的端点的流量。

  • 选择一个或多个或所有应用内事件。注意!如果事件未显示在列表中,请直接搜索该事件。
  • 如果选择全部,所有后续新的应用内事件都会自动添加。
  • 您只可以选择到至少已经记录一次的应用内事件。
  • mceclip1.png
 
Facebook 您是否打算发送归因于Facebook的用户的数据?
  • 要接收Facebook数据,请确保您已接受Facebook服务条款。

 

设置和管理端点

  • 本节包含添加,测试,修改和删除端点的流程。
  • 仅管理员有权限编辑API设定团队成员仅能查看API设定
AppsFlyerAdmin_us-en.png添加Push API端点:
  1. 转到 对接 > API数据接口向下滚动到Push API部分。
    显示“Push API”部分。
  2. 单击 添加端点。
  3. 选择HTTP方法: POST GET
  4. 输入端点 URL
  5. 选择一种或多种事件类型。注意 !如果应用内事件端口无法勾选,说明到目前为止尚未成功上报任何应用内事件。
  6. 选择字段以填充Push API消息。注意:
    • 始终发送必填字段:应用ID,事件名称,事件时间,IDFA(iOS)或广告ID(Android)
    • 使用下图所示的控件来选择可选字段。

      PushAPIFieldSelect1.jpg

      • 最常用的字段已经被预选。可以清除选择它们。
      • 根据需要选择可选字段。
      • 点击清除全部可清除所有可选字段。
      • 在不久的将来,我们计划停止发送null /空值字段,以及其中的参数。在数据入库BI和解析过程中,请留意此处。
  7. 选择一个或多个(最多52个事件)或“ 所有应用内事件”。
    • 该列表由已记录的事件类型填充。如果缺少事件,请使用测试设备发送此类事件。
  8. 单击 保存
    Push API现在处于活动状态
    转换数据已发送到端点。
  9. 使用以下过程测试端点。
  10. 如果要接收归因于Facebook的事件,则必须首先接受 Facebook服务条款。

测试端点:

  1. 单击 发送测试。
    发送测试 按钮下方显示测试结果消息。
    测试消息发送到端点。
  2. 检查端点是否收到测试消息。
    发送的消息副本如下。

测试POST和GET API消息

以下POST消息作为测试消息发送

{                  
  "idfv": "123456789",
  "device_category": "phone",
  "af_sub1": "sub1-12345",
  "customer_user_id": "Customer User ID",
  "is_lat": null,
  "contributor_2_af_prt": "attributionagency",
  "bundle_id": "bundleIdentifier_test",
  "gp_broadcastreferrer": "",
  "contributor_2_touch_time": "2019-12-31 00:05:42.805",
  "contributor_3_touch_type": "click",
  "event_source": "SDK",
  "af_cost_value": "10",
  "contributor_1_match_type": "id_matching",
  "app_version": "app_version",
  "contributor_3_af_prt": "attributionagency",
  "custom_data": null,
  "contributor_2_touch_type": "click",
  "gp_install_begin": "2019-12-31 00:07:14.000",
  "city": "Redmond",
  "amazon_aid": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "gp_referrer": "af_tranid=000712-31122019254604&pid=pdsagency_int&c=pushapi_v2",
  "af_cost_model": "CPI",
  "af_c_id": "cid12345",
  "attributed_touch_time_selected_timezone": "2019-12-31 00:06:32.891+0000",
  "selected_currency": "EUR",
  "app_name": "com.pds.pushapi2.v2.transparent.com",
  "install_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "postal_code": "98052",
  "wifi": false,
  "install_time": "2019-12-31 00:07:14.961",
  "operator": "ORANGE",
  "attributed_touch_type": "click",
  "af_attribution_lookback": "25d",
  "keyword_match_type": null,
  "af_adset_id": "adset12345",
  "device_download_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "contributor_2_media_source": "contrib2",
  "contributor_2_match_type": "id_matching",
  "api_version": "2.0",
  "attributed_touch_time": "2019-12-31 00:06:32.891",
  "revenue_in_selected_currency": null,
  "is_retargeting": false,
  "country_code": "US",
  "gp_click_time": "2019-12-31 00:07:12.000",
  "contributor_1_af_prt": "attributionagency",
  "match_type": "id_matching",
  "appsflyer_id": "e126a3b3-3406-4196-a964-563c9ae44ff8",
  "dma": "819",
  "http_referrer": "https://www.amazon.com/gp/bestsellers/gift-cards/ref=sv_gc_0",
  "af_sub5": "sub5-12345",
  "af_prt": "attributionagency",
  "event_revenue_currency": null,
  "store_reinstall": null,
  "install_app_store": null,
  "media_source": "pdsagency_int",
  "deeplink_url": null,
  "campaign": "pushapi_v2",
  "af_keywords": "keywords12345",
  "region": "NA",
  "cost_in_selected_currency": "1000",
  "event_value": null,
  "ip": "20.168.174.166",
  "oaid": null,
  "event_time": "2019-12-31 00:07:14.961",
  "is_receipt_validated": null,
  "contributor_1_campaign": "camp1",
  "af_sub4": "sub4-12345",
  "imei": null,
  "contributor_3_campaign": "camp3",
  "event_revenue_usd": null,
  "af_sub2": "sub2-12345",
  "original_url": "https://app.appsflyer.com/com.pds.pushapi2.v2.transparent.com?c=pushapi_v2&pid=pdsagency_int&clickid=click12345&af_ref=000632-31122019&advertiserId=9173fe74-0578-4658-a461-ebb0b4fce6d6&android_id=3e06b4caebc19356&sha1_android_id=sha12345&af_siteid=136396&af_sub_siteid=sub_siteid12345&af_c_id=cid12345&af_adset=adset12345&af_adset_id=adset12345&af_ad=ad12345&af_ad_id=adid12345&af_ad_type=adtype12345&af_channel=channel12345&af_keywords=keywords12345&is_retargeting=False&af_dp=ebay%3A%2F%2Fshoppingcart&af_web_dp=www.dp.com&af_sub1=sub1-12345&af_sub2=sub2-12345&af_sub3=sub3-12345&af_sub4=sub4-12345&af_sub5=sub5-12345&af_cost_model=CPI&af_cost_value=10&af_cost_currency=EUR&sha1_advertising_id=sha12345&sha1_el=sha12345&af_installpostback=false&af_force_dp=true&af_chrome_lp=true&af_ec=1&af_click_lookback=25d&af_viewthrough_lookback=1h&af_reengagement_window=2d&af_prt=attributionagency",
  "contributor_2_campaign": "camp2",
  "android_id": "3e06b4caebc19356",
  "contributor_3_media_source": "contrib3",
  "af_adset": "adset12345",
  "af_ad": "ad12345",
  "state": "WA",
  "network_account_id": null,
  "device_type": "Samsung::SH-220",
  "idfa": null,
  "retargeting_conversion_type": null,
  "af_channel": "channel12345",
  "af_cost_currency": "EUR",
  "contributor_1_media_source": "contrib1",
  "keyword_id": null,
  "device_download_time": "2019-12-31 00:07:14.961",
  "contributor_1_touch_type": "click",
  "af_reengagement_window": "2d",
  "af_siteid": "136396",
  "language": "English",
  "app_id": "com.pds.pushapi2.v2.transparent.com",
  "contributor_1_touch_time": "2019-12-31 00:06:07.847",
  "event_revenue": null,
  "af_ad_type": "adtype12345",
  "carrier": "carrier",
  "event_name": "install",
  "af_sub_siteid": "sub_siteid12345",
  "advertising_id": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "os_version": "6.0",
  "platform": "android",
  "af_sub3": "sub3-12345",
  "contributor_3_match_type": "id_matching",
  "selected_timezone": "UTC",
  "af_ad_id": "adid12345",
  "contributor_3_touch_time": "2019-12-31 00:05:17.757",
  "user_agent": "Dalvik/1.6.0 (Linux; U; Android 6.0; Redmi Note 4 Build/KOT49I.F320S22g",
  "is_primary_attribution": null,
  "sdk_version": "v4.8.0",
  "event_time_selected_timezone": "2019-12-31 00:07:14.961+0000"
}

更改端点

AppsFlyerAdmin_us-en.png修改端点设置:

  1. 转到 对接 > API访问
    向下滚动到Push API部分。
    显示“Push API”部分。
  2. 找到要修改的端点。
  3. 进行修改。
  4. 点击保存

删除端点

AppsFlyerAdmin_us-en.png删除端点

  1. 转到 对接 > API访问
    向下滚动到Push API访问部分。
  2. 单击 删除端点
  3. 点击保存。端点被删除。

将端点从V1.0迁移到V2.0

AppsFlyerAdmin_us-en.png将端点从V1.0迁移到V2.0:

  1. 转到 对接 > API数据接口向下滚动到Push API部分。
    显示“Push API”部分。
  2. 确定要迁移的端点。
  3. 选择Push API需要包含的字段。
    • 始终发送必填字段:应用ID,事件名称,事件时间,IDFA(iOS)或广告ID(Android)
    • 使用下图所示的控件来选择可选字段。

      PushAPIFieldSelect1.jpg

      • 最常用的字段已经被预选。可以清除选择它们。
      • 根据需要选择可选字段。
      • 点击清除全部可清除所有可选字段。
      • 在不久的将来,我们计划停止发送null /空值字段,以及其中的参数。在数据入库BI和解析过程中,请留意此处。
  4. 选择一个或多个(最多52个事件)或“ 所有应用内事件”。
    • 该列表由已记录的事件类型填充。如果缺少事件,请使用测试设备发送此类事件。
  5. 点击保存
    • Push API已迁移。
    • 归因数据会持续发送至端点。

故障排除,局限性

重复再营销应用内事件

当一个购买事件来自再营销用户,并且发生在re-engegement再互动窗口期内,再营销事件会重复记录。这样做是为了将收入分配给UA媒体源和再营销媒体源。

如果同时启用了以下两项,则会得到重复事件:

  • 激活应用内事件
  • 再营销应用内事件

作为再营销广告系列的一部分,归因于UA媒体源的应用内事件(激活应用内事件)的字段 is_primary_attribtuion = false。

 示例

  • 用户安装example_app,这归因于 ua_network
  • 之后,用户在 retar_network 上重新参与example_app的再营销广告系列并进行购买。

应用内购买事件发送两次,详细信息如下:

再营销应用内事件字段
事件类型 媒体渠道 is_retargeting 再营销转化类型 is_primary_
attribution 
激活应用内安装 ua_network 再互动或再归因 False
重定向应用内事件 retar_network 再互动或再归因


如何识别重复的再营销事件?

is_primary_attribution 字段标识重定向广告系列中的主要和次要媒体来源:

  • False:标识原始UA媒体源。 :这是唯一一个值为false的场景。
  • 正确:确定再互动归因的媒体来源

这样做的原因如下:如果用户由于再营销广告系列而与广告系列互动,则会打开“再互动”窗口。当再互动窗口打开,再互动媒体源被视为主要媒体源,UA源为次要媒体源。当窗口关闭后,原始UA媒体源将恢复为主要媒体源。

应用内事件消息选择被禁用

InappSelectionDisabled_us-en.png

  • 只有记录到了一次应用内事件后,才能选择传输这个应用内事件消息。
  • 使用测试设备生成应用内事件,或使用 S2S API 手动生成事件。

缺少Facebook数据

默认情况下,Facebook不会发布原始的用户级别数据,直到您接受Facebook服务条款为止。
接受条款后,来自Facebook和其他原始数据源的用户级数据将通过Push API发送。

缺少推送消息和CloudFront

您是否将Amazon CloudFront用作终端节点?如果是这样,请检查CloudFront是否正在使用拒绝代码421拒绝该消息。如果是这种情况,请参阅 选择CloudFront如何处理HTTPS请求

局限性&特征

特征:
特征 备注
广告网络 不适用于广告平台。
代理商 不供代理商使用
应用设定的时区 支持
应用设定的货币 支持
大小限制 不适用
自然量
非自然
数据新鲜度 实时
历史数据 不支持。在配置Push API之后发送事件数据。如果您需要历史原始数据,请使用Pull API。
团队成员访问 团队成员可以查看Push API设置,但无法进行更改。
这篇文章有帮助吗?