概要:本文重点介绍了如何使用URI来拉取CSV格式的AppsFlyer原始数据报告。
Pull API原始数据报告的特点
- 原始数据报告内容说明。
- 返回的报告是CSV格式的。
- 筛选条件包括:媒体渠道、日期范围、应用内事件名称以及地理位置。
- 提供时区和货币选项。
- Pull API适用于账户用户以及BI开发人员。
- 频次限制:每天的报告拉取次数是有限额的。
URI模板示例
扩展阅读:如何选择合适的数据传输工具/报告API
概念定义
术语 | 说明 |
---|---|
Pull API |
通过URI下载CSV报告的解决方案。 |
API调用或调用 |
将URI复制粘贴到浏览器地址栏或通过脚本向AppsFlyer发送URI。 |
URI |
|
账户用户指南
URI模板简介
- 您可以在面板中查看URI模板,其中带有应用ID和报告类型参数。
- 模板中留出了API密钥以及日期范围的位置,这两个字段是需要您编辑的。
- URI中问号(?)右侧的部分是各种参数,每个参数都以&开始。您可以使用这些参数来设置筛选条件、添加特定的字段(如货币币种和时区),比如您可以通过media_source(媒体渠道)参数在原始数据报告中筛选某一个渠道的结果,如
&media_source=facebook
。 - 请完成以下入门教程,更熟练地掌握Pull API这个工具。
- 面板中没有回传URI,如需回传URI请参考此Excel表格。
请按以下步骤获取Pull API报告入门教程:
开始之前:- 请向管理员申请Pull API密钥(管理员可在面板中查看令牌)。
从面板下载报告:
-
从后台进入对接 > API数据接口。
打开API数据接口页面。 - 选择报告类型。如原始数据报告 > 再营销转化。
界面会显示URI模板。 - 点击复制该URI。
- 在浏览器中打开一个新的标签页,然后将URI粘贴到地址栏中。
- 编辑URI:
- 在预留位置中填入由管理员提供的Pull API密钥。
示例:在预留位置中填入API密钥后相关字段应该是这样的&api_token=12345678-1234-1234-1234-123456789012
。请注意:这里面不能有空格或其他的标点符号。 - 在from/to的日期范围预留位置中填入日期。
示例:&from=2020-01-20&to=2020-01-31
请注意:不能带有空格,且不能删除&号。
- 在预留位置中填入由管理员提供的Pull API密钥。
- 按下回车键,发送API调用。
开始下载报告。
Pull API的原始数据参数
URI中的原始数据参数
参数 | 说明 |
---|---|
api_token | API身份验证令牌(密钥)。在调用示例中,该参数显示为<API TOKEN HERE>。 |
from |
|
to |
结束日期,与from 相对
|
参数 | 说明 |
---|---|
media_source |
|
maximum_rows |
单次API调用最多可以拉取到的数据行数。
|
event_name |
按指定事件来筛选应用内事件数据。可以选择多个事件,事件之间用逗号分隔。 示例: |
reattr |
设置再营销归因数据
|
additional_fields |
用于拉取默认字段之外的数据。 示例: |
currency |
收入和成本的货币币种
示例:如果应用层级的指定货币是EUR(欧元),发送 |
timezone |
【默认】数据以UTC时间显示。
|
geo |
按国家代码筛选数据 限制:每次调用API时只能设置一个国家代码。 示例: |
Protect 360
日期和时间范围
如果返回的结果超过行数上限,请通过小时数和分钟数来拆分报告。具体方法如下:
- from/to参数的格式为:yyyy-mm-dd hh:mm
-
from:
- 如果参数仅包含日期 = 从选定日期的零时(00:00)开始
- 如果同时包含日期和时间 = 从hh:mm开始(含)
-
参数to:
- 如果参数仅包含日期 = 到选定日期结束(24:00)为止
- 如果同时包含日期和时间 = 到显示的时间(不含)为止
示例:各渠道每天共为某广告主带来130万个新增激活。为克服100万行的限制,该广告主分两次调用API,每次拉取12小时的数据。具体方案请见下表:
API调用 | From | To |
---|---|---|
首次API调用 |
from=yyyy-mm-dd 示例:
|
to=yyyy-mm-dd 12:00 示例:
|
方案A:第二次API调用
示例:
|
from=yyyy-mm-dd 12:00 示例:
|
to=yyyy-mm-dd 示例:
|
方案B:第二次API调用 |
from=yyyy-mm-dd 12:00 示例:
|
to=yyyy-mm-dd+1 00:00 +1 = 第二天的00:00 示例:
|
请注意:方案A和方案B拉取到的结果是一样的。 |
可选的非默认字段
添加非默认字段不会影响您的数据入库和接入流程。您可以使用additional_fields
这个参数来拉取非默认字段的值。
- 这个参数在每个URI中只能出现一次。
- 可用字段请见此列表。
- 部分URI示例中包含了非默认字段,您可以根据需要添加多个字段。
-
Example:
additional_fields=device_download_time,deeplink_url
- 下表中所列字段是一定能拉取到结果的。
示例
带有非默认字段的URI调用示例:
https://hq.appsflyer.com/export/<APP ID HERE>/installs_report/v5?
api_token=<API TOKEN HERE>&from=yyyy-mm-dd&to=yyyy-mm-dd
&additional_fields=device_download_time,deeplink_url
Pull API默认字段
Pull API默认字段 |
---|
Attributed Touch Time(记录到的广告触达时间) |
Install Time(激活时间) |
Event Time(事件时间) |
Event Name(事件名称) |
Event Value(事件值) |
Event Revenue(事件收入) |
Event Revenue Currency(事件收入货币) |
Event Revenue USD(以美元为单位的事件收入) |
Event Source(事件来源) |
Is Receipt Validated(收入验证) |
Partner(代理或PMD) |
Media Source(广告平台) |
Channel(流量入口) |
Keywords(关键词) |
Campaign(广告系列) |
Campaign ID(广告系列ID) |
Adset(广告组) |
Adset ID(广告组ID) |
Ad(广告素材) |
Ad ID(广告ID) |
Ad Type(广告类型) |
Site ID(子渠道ID) |
Sub Site ID(次级子渠道ID) |
Sub Param 1(可配置参数1) |
Sub Param 2(可配置参数2) |
Sub Param 3(可配置参数3) |
Sub Param 4(可配置参数4) |
Sub Param 5(可配置参数5) |
Cost Model(计费模式) |
Cost Value(成本值) |
Cost Currency(成本货币) |
Contributor 1 Partner(助攻1 代理) |
Contributor 1 Media Source(助攻1 广告平台) |
Contributor 1 Campaign(助攻1 广告系列) |
Contributor 1 Touch Type(助攻1 触点类型) |
Contributor 1 Touch Time(助攻1 触达时间) |
Contributor 2 Partner(助攻2 代理) |
Contributor 2 Media Source(助攻2 广告平台) |
Contributor 2 Campaign(助攻2 广告系列) |
Contributor 2 Touch Type(助攻2 触点类型) |
Contributor 2 Touch Time(助攻2 触达时间) |
Contributor 3 Partner(助攻3 代理) |
Contributor 3 Media Source(助攻3 广告平台) |
Contributor 3 Campaign(助攻3 广告系列) |
Contributor 3 Touch Type(助攻3 触点类型) |
Contributor 3 Touch Time(助攻3 触达时间) |
Region(地区) |
Country Code(国家代码) |
State(州) |
City(城市) |
Postal Code(邮政编码) |
DMA(指定市场区域) |
IP |
WIFI |
Operator(手机运营商) |
Carrier(移动通信运营商) |
Language(语言) |
AppsFlyer ID |
Advertising ID(广告ID) |
IDFA |
Android ID |
Customer User ID(客户用户ID) |
IMEI |
IDFV |
Platform(平台) |
Device Type(设备型号) |
OS Version(OS版本) |
App Version(应用版本) |
SDK Version(SDK版本) |
App ID(应用ID) |
App Name(应用名称) |
Bundle ID |
Is Retargeting(是否为再营销广告) |
Retargeting Conversion Type(再营销转化类型) |
Attribution Lookback(归因回溯窗口期) |
Reengagement Window(再互动窗口期) |
Is Primary Attribution(是否为主要转化来源) |
User Agent |
HTTP Referrer(HTTP来源标识) |
Original URL(原始URL) |
开发人员的Pull API使用指南
请参考Pull API汇总数据指南,其中说明了如何通过脚本拉取报告。请根据该文档来部署Pull API原始数据的脚本,因为其原理是相通的。
其他信息
从API V4迁移到V5
原始数据:V4版的API已于2021年12月1日下线,AF后台将不再显示该版API,因此请务必在此日期前从V4切换到V5。
从API V4迁移到V5
从V4迁移到V5时请注意:V5带有一组默认字段,报告会默认拉取这些字段的值;另外V5还支持可选的非默认字段,这些字段必须由您在调用Pull API时手动添加。请根据您的具体需求调整您的API调用。您可以在AppsFlyer后台查看包含非默认字段的URI模板,并根据您的需求编辑该模板。详情请见如何从AF后台获取URI模板。
特点和局限性
特点 | 说明 |
---|---|
规定的API密钥类型 |
![]() |
渠道权限 | 否 |
代理访问权限 | 是 |
代理数据透明化 | 是 |
应用层级指定货币 | 是 |
应用层级指定时区 | 是 |
数据时效性 |
|
历史数据 | 是。须遵循数据保存期限和频次限制规定。 |
非自然量数据 | 是 |
自然量数据 | 是 |
拉取频次限制 |
原始数据的API调用限制 |
大小限制 |
|
API错误代码及疑难解答
状态 | 代码 | 问题表现/报错 | 解决方案 |
---|---|---|---|
所选时间段中有数据缺失,或原始数据和汇总数据报告之间有数据差异。 |
请检查是否配置了 |
||
OK | 200 | CSV文件为空 |
URI中 |
OK |
200 |
CSV文件为空 |
请确保“from”和“to”的日期都是yyyy-mm-dd格式。 |
Bad request (请求无效) |
400 |
Raw Reports historical lookback is limited to 90 days |
将 |
Bad request (请求无效) |
400 |
Your API calls limit has been reached for report type |
- |
Bad request (请求无效) |
400 |
Invalid limit type |
report_rows的值只能是200000或1000000。 |
Unauthorized (无权限) |
401 |
Supplied API token is invalid |
需要AppsFlyer管理员账户提供正确的API密钥。 |
Unauthorized (无权限) |
401 |
Account may be suspended |
请登入面板并查看账户状态。 |
Not found (不存在) |
404 |
|
API密钥与应用不匹配,需要AppsFlyer管理员账户提供正确的API密钥。 |