概要:本文重点解释如何将已归因事件的原始数据实时发送到您的服务器端点。
Push API
使用AppsFlyer或SKAN归因,生成原始数据后,您可以通过Push API将这些数据以推送消息的形式传输到您的服务器,并自行选择消息类型、消息内容,同时设置目标端点。
可用的消息类型、字段以及数据时效性取决于您使用的归因框架(AppsFlyer或SKAN),这在以下几个章节中会有详细说明。
AppsFlyer归因消息
消息特征
主要特点 | 说明 |
---|---|
消息类型区分 |
举例来说, 如果一个消息中包含以下字段:
对照下表可判断出该事件是一个自然量的激活事件。 |
数据时效性 | AppsFlyer平台记录到事件后会立即发出消息。发送过程一般需要几分钟。 |
消息内容(字段) |
|
时间戳字段的格式: |
|
可用的消息类型
归因场景 | 消息类型 | conversion_type字段 | campaign_type字段 | event_name字段 | event_type字段 |
---|---|---|---|---|---|
用户获取 | 激活* | install |
非自然量UA(用户获取) 自然:organic |
install |
|
用户获取 | UA应用内事件 | install |
非自然量UA(用户获取) 自然:organic |
广告主侧定义的事件名称 |
|
再营销 | 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 | 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消息的结构和字段与其对应。
消息特征:
主要特点 | 说明 |
---|---|
消息类型区分 |
举例来说, 如果一个消息中包含以下字段:
由此可以确定:
|
数据时效性 |
|
消息示例 | 请见表格。示例的文件格式为JSON。 SKAN示例消息。 |
SKAN归因的消息类型
消息类型 | event_name字段 | skad_redownload字段 | event_type字段 |
---|---|---|---|
激活假量 | install |
|
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 |
|
端点返回码 | 收到消息后,您的端点必须返回HTTP 200状态代码。 |
AppsFlyer服务器加白 | 在您的防火墙和安全系统中对AppsFlyer服务器的IP地址加白,以确保AF服务器与端点之间的数据传输保持畅通。 |
TLS版本 |
|
端口 | 端口:80, 443 |
请注意:这里使用了一个为时4秒的计时机制,如果在这4秒内AF的服务器没有接收到发送成功的消息,那么系统就会认为该消息发送失败。
针对AppsFlyer归因的Push API设置规划表
- 请参照下表说明,规划您的AppsFlyer归因端点设置,图中的数字与下面清单中的行号匹配。
- 本节内容不涉及SKAdNetwork,有关SKAN归因的说明请参见SKAdNetwork归因设置。
端点
端点规划表
不可以。 | 配置 | 说明 | 在本栏中记录您的设置规划 |
---|---|---|---|
1 | 方法 | POST 或者 GET | |
2 | 端点URL | - | |
3 | 事件消息类型 |
|
|
4 |
|
警告如果您勾选了全选,所有新添加的字段都会自动选中。这时,请确保您能够支持所有自动添加的新增字段,以免出现问题。
|
|
5 |
应用内事件类型
|
您可以按应用内事件进行筛选,以控制发送到端点的流量。
|
设置AppsFlyer归因端点
请注意:只有AppsFlyer账户所有者才能更改Push API设置。其他类型的用户只能查看该设置。
请按以下步骤添加AppsFlyer归因端点:
- 从AF后台进入报告 > API数据接口,向下滚动到Push API部分。
- 单击添加端点。
- 选择HTTP方法: POST或者GET
- 输入端点URL。 如果收到this URL is not safe(该URL不安全)的消息,请联系AppsFlyer技术支持。
- 选择一种或多种事件类型。请注意:如果应用内事件消息显示为不可用,说明尚未记录到任何应用内事件。
- 选择Push API消息中需要包含的字段。请注意:
- 选择一个或多个(最多52个事件)或“ 所有应用内事件”。
- 该列表中只包含已经记录到的事件类型。如果其中没有显示您想要的事件类型,请先使用测试设备发送这类事件。
- 点击保存。
该Push API就开始生效,将转化数据发送到端点。 - 请按以下步骤测试端点。
测试端点:
- 点击发送测试。
发送测试按钮下方会显示测试结果。
测试消息将被发送到端点。如果显示测试失败,请确保您已对AppsFlyer服务器的IP地址加白。
请注意:这里使用了一个为时2秒的计时机制,如果在这4秒内AF的服务器没有接收到发送成功的消息,那么系统就会认为该消息发送失败。 - 为确认您的端点是否接收到了测试消息,
您可以查看测试消息的副本。
设置SKAdNetwork归因端点
请注意:只有AppsFlyer账户所有者才能更改Push API设置。其他类型的用户只能查看该设置。
请按以下步骤添加SKAdNetwork Push API端点:
- 从AF后台进入报告 > API数据接口,向下滚动到Push API部分。
- 选择SKAdNetwork作为归因实体。
- 单击添加端点。
请注意:您可以为每个应用定义1-3个SKAdNetwork端点。 - 选择HTTP方法: POST或者GET
- 输入端点URL。 如果收到this URL is not safe(该URL不安全)的消息,请联系AppsFlyer技术支持。
- AF系统不会发送null/空的字段及其对应的键,在数据入库BI和解析过程中,请留意此处。
- 点击保存。
该Push API就开始生效,将数据发送到端点。
配置身份验证令牌
通过使用Push API身份验证令牌,客户可以无缝接入并保护其Push API消息安全,只需为请求的令牌添加一个可自定义的授权header即可。
您可以通过为每个App ID定义令牌名称和值,自定义随Push API消息一同发送的授权 header。这样不仅可确保消息的安全性,也能满足您的特定需求。
其他操作 — 端点管理
修改端点设置
请注意:只有AppsFlyer账户所有者才能更改Push API设置。其他类型的用户只能查看该设置。
请按以下步骤修改端点设置:
- 报告> API数据接口向下滚动到Push API部分。
- 找到要修改的端点。
- 进行修改。
- 点击Save。
删除端点
请注意:只有AppsFlyer账户所有者才能更改Push API设置。其他类型的用户只能查看该设置。
删除端点 :
- 从AF后台进入报告 > API数据接口,向下滚动到Push API部分。
- 单击删除端点 。
- 点击保存。
端点被删除。
问题排查、特点和局限性
未收到测试消息
如果您的服务器通过IP地址来限制访问,在这种情况下没有接收到测试消息可能是因为没有对所有的AppsFlyer IP地址加白。
再营销应用内事件的重复
如果用户点击了再营销广告并产生了付费事件,而该事件又发生在UA再互动窗口期内,这时再营销应用内事件就会发生重复。这一机制背后的逻辑是要将收入同时归因到UA渠道和再营销渠道。
如果您同时启用了以下两项,就会发生事件重复:
- UA应用内事件
- 再营销应用内事件
应用内事件消息不可用
- 应用内事件必须至少被记录到一次,相应的消息选项才会显示为可选。
- 使用测试设备生成应用内事件,或使用 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设置。
其他类型的用户可以查看Push API设置,但不能对其进行更改。 |
测试消息中的身份验证令牌 | 测试消息的header不包含身份验证令牌。 |
我可以在Push API请求中添加自定义header吗?
不可以。Push API仅支持使用header传递身份验证令牌。不支持额外的自定义header(如consumer-key
)。
如果需要传递额外参数,请将其包含在URL中。使用场景示例:
https://your.server.com?consumer_key=abc456