概要：本文重点介绍了如何使用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_urlPull 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密钥类型 |
 V1.0 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密钥。 |