Push API V2.0实时归因事件报告

概览: 通过API实时推送归因事件数据,以供在您的IT系统中使用。

4409_Push_API_V2-01.png

Push API V2.0

Push API新闻

  • Push API V2.0 与AppsFlyer中其他数据传递工具使用的AppsFlyer原始数据V5.0规范保持一致。
    • 其他字段:已添加40多个归因字段。随着新字段添加到AppsFlyer平台,它们将在Push API V2.0中迅速提供。
    • 字段选择:选择要发送的字段-减少Push API消息的大小。
  • Push API V1.0 不推荐使用并将于2020年8月31日停用。
  • 开发人员:Push API V1.0到Push API V2.0迁移指南

通过使用Push API实时获取归因数据,您可以将内部用户数据与来自AppsFlyer的实时归因数据结合起来。使用数据来跟踪用户路径,并执行实时分析和分化用户。

Push API示例 JSON格式输出文件:

Push API功能

Push API支持的事件类型
✓=可用, - 不适用)

广告活动类型

事件类型

(转化类型)

value of is_
retargeting

value of retargeting_

conversion_

类型

非自然 自然 再营销
用户获取 安装 False    -
用户获取 激活应用内事件 False    -

再营销

再互动Re-engagement   - -
再营销 再互动Re-engagement应用内事件 再互动 - -
再营销 再归因Re-attribution 再归因 - -
再营销 再归因Re-attribution应用内事件 再归因 -

 

数据新鲜度

Push API消息是实时发送的。

 

技术

    • 支持RESTful API,POST和GET方法
    • POST消息响应包含在JSON中

注意

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

配置Push API

设置Push API

先决条件清单

  • IP列入白名单 :将AppsFlyer IP列入白名单,以便它们可以与URL中定义的端点进行通信。AppsFlyer的列表 IP地址
  • TLS支持:
  • 端口: 80,443
  • 端点:
    • 是有效的域名
    • 配置为返回HTTP状态代码200,指示成功完成。 :不允许其他状态代码。这包括其他2XX代码。
    • 每个应用程序可以使用同一端点一次。
    • 使用GET方法时,如果端点由第三方提供程序托管,则不要向URL添加查询参数。
    • 不支持API密钥参数。
  • Facebook广告系列 :如果您想接收归因于Facebook的数据,则需要接受Facebook服务条款。否则,Facebook数据不会 被Push API发送的。
  • 最多可以定义六个端点。
  • 帐户管理员需要执行Push API配置(添加,删除,更改)。团队成员仅可以查看设置。

添加Push API端点:

  1. 转到 对接 > API访问
    向下滚动到Push API部分。
    显示“Push API”部分。
  2. 单击 添加端点。 最多可以定义六个端点。

    PusAPIConfig_us-en.png

  3. 选择Push API版本:[默认] 2.0
  4. 选择HTTP方法: POST GET
  5. 输入端点 URL
  6. 选择一种或多种事件类型以发送到端点URL。
  7. 选择要在Push API消息中发送的字段。注意事项:
    • 必须字段始终会被发送。它们是:应用程序ID,事件名称,事件时间,IDFA(iOS)或Advertising ID(Android)
    • 其他字段是可选的,可以在用户界面中选择。请使用下图中所示的控件。

      PushAPIFieldSelect_us-en.jpg 

      • 默认情况下,已选择最常用的可选字段。
      • 请根据自身需要清除选择字段。
      • 选择您需要的其他字段。
      • 使用清除 选择全部,清除所有可选字段。
  8. 单击 保存
    Push API现在处于活动状态
    转换数据已发送到端点。
  9. 使用以下过程测试端点。
  10. 如果您想通过Push API接收归因于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_broadcast_referrer": "",
  "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"
}

 

移除回传

删除回传

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

Push API消息结构

Push API响应取决于HTTP方法:

  • GET:数据参数附加到URL字符串
  • POST:数据参数以JSON格式包含在消息正文中

Push API 字段

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。±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  

故障排除,局限性&特质

重复再营销应用内事件

当一个购买事件来自再营销用户,并且发生在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媒体源将恢复为主要媒体源。

缺少Facebook数据

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

缺少推送消息和CloudFront

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

局限性&特征

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