使用Pull API拉取原始数据

概要:本文重点介绍了如何使用URI来拉取CSV格式的AppsFlyer原始数据报告。

PullAPIRaw_us-en.png

Pull API原始数据报告的特点

  • 原始数据报告内容说明。
  • 返回的报告是CSV格式的。
  • 筛选条件包括:媒体渠道、日期范围、应用内事件名称以及地理位置。
  • 提供时区和货币选项。
  • Pull API适用于账户用户以及BI开发人员。
    • 账户用户可将URI复制粘贴到浏览器中,就能获取报告。请从AppsFlyer后台进入对接 > API数据接口,查看URI模板。
    • BI开发人员在脚本中嵌入URI后就能拉取报告。
  • 频次限制:每天的报告拉取次数是有限额的。

URI模板示例

TemplateURL_us-en.jpg

 扩展阅读:如何选择合适的数据传输工具/报告API

概念定义

术语 说明
Pull API

通过URI下载CSV报告的解决方案。

API调用或调用

将URI复制粘贴到浏览器地址栏或通过脚本向AppsFlyer发送URI。

URI
  • Uniform resource identifier(统一资源标识符)类似于网页地址(URL),其中包含报告规格。
  • 请在面板的API页面中查看URI模板。

账户用户指南

URI模板简介

  • 您可以在面板中查看URI模板,其中带有应用ID和报告类型参数。
  • 模板中留出了API密钥以及日期范围的位置,这两个字段是需要您编辑的。
  • URI中问号(?)右侧的部分是各种参数,每个参数都以&开始。您可以使用这些参数来设置筛选条件、添加特定的字段(如货币币种和时区),比如您可以通过media_source(媒体渠道)参数在原始数据报告中筛选某一个渠道的结果,如&media_source=facebook
  • 请完成以下入门教程,更熟练地掌握Pull API这个工具。
  • 面板中没有回传URI,如需回传URI请参考此Excel表格

请按以下步骤获取Pull API报告入门教程:

开始之前:
  • 请向管理员申请Pull API密钥(管理员可在面板中查看令牌)。

从面板下载报告:

  1. 从后台进入对接 > API数据接口。
    打开API数据接口页面。
  2. 选择报告类型。如原始数据报告 > 再营销转化。
    界面会显示URI模板。
  3. 点击复制该URI。
  4. 在浏览器中打开一个新的标签页,然后将URI粘贴到地址栏中。
  5. 编辑URI:
    1. 在预留位置中填入由管理员提供的Pull API密钥。
      示例:在预留位置中填入API密钥后相关字段应该是这样的&api_token=12345678-1234-1234-1234-123456789012请注意:这里面不能有空格或其他的标点符号。
    2. from/to的日期范围预留位置中填入日期。
      示例:&from=2020-01-20&to=2020-01-31 请注意:不能带有空格,且不能删除&号。
  6. 按下回车键,发送API调用。
    开始下载报告。

Pull API的原始数据参数

URI中的原始数据参数

参数 说明
api_token API身份验证令牌(密钥)在调用示例中,该参数显示为<API TOKEN HERE>。
from
  • 日期范围包含一个fromto参数,其中的日期指的是用户行为发生的时间。
  • 格式:yyyy-mm-ddyyyy-mm-dd hh:mmyyyy-mm-dd hh:mm:ss。请注意:空格需要加密,具体如下:from=2020-04-01%2001:00:00。一般情况下浏览器会对空格进行加密。
  • 示例:2010-01-01或2010-01-01 20:15(原始数据报告中可以显示小时数和分钟数)。
to 结束日期,与from相对
可选的原始数据参数
参数 说明

media_source

media_source:用于筛选某个具体渠道的数据。请根据以下方式来设置media_sourcecategory参数:

  • 要筛选Facebook的数据,请将category和media_source都设置为facebook
  • 要筛选Twitter的数据,请将category和media_source都设置为twitter
  • 要筛选其他任何媒体渠道的数据,请将category设为standard,将media_source设为该媒体渠道的名称。
  • 示例
    • media_source=facebook&category=facebook
    • media_source=abc_example&category=standard
maximum_rows

单次API调用最多可以拉取到的数据行数。

  • 【默认】如果不发送该值,则最多返回20万行数据。该字段只支持以下两个值:
  • 200000:最多可拉取20万行数据
  • 1000000:最多可拉取100万行数据
  • 示例:maximum_rows=1000000可拉取100万行数据。
event_name

按指定事件来筛选应用内事件数据。可以选择多个事件,事件之间用逗号分隔。

示例event_name=af_purchase,ftd

reattr

设置再营销归因数据

  • 【默认】如果该参数为false,就会拉取到用户获取(UA)的投放数据。
  • 如果该参数的值为true,就会拉取再营销归因数据。
  • 示例reattr=true
additional_fields

用于拉取默认字段之外的数据。

示例additional_fields=device_donwload_time,deeplink_url

currency

收入和成本的货币币种

  • 【默认】如果不发送该参数,则相关数据以USD显示。也就是说在不配置该参数的情况下,报告中的结果是以美元为单位的。
  • 如果发送currency=preferred,相关数据会以应用层级的指定货币来显示。也就是说报告中的货币单位与应用层级的指定货币相同。

示例:如果应用层级的指定货币是EUR(欧元),发送currency=preferred后就可拉取以EUR为单位的值。

timezone

【默认】数据以UTC时间显示。

  • 如果要让报告按应用层级的指定时区来显示相关数据,请按以下方式在调用中添加timezone这个参数:
  •  timezone=[Numerical value] 
  • 示例:假设您要使用的时区为UTC+10:00,则需要发送timezone=+10:00。请注意:+-:这几个符号需要加密。示例:+10:00需加密为%2B10%3A00
geo

按国家代码筛选数据

限制:每次调用API时只能设置一个国家代码。

示例:geo=ZA

日期和时间范围

如果返回的结果超过行数上限,请通过小时数和分钟数来拆分报告。具体方法如下:

  • 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

示例:

  • from=2019-12-29
  • 从这一天的00:00开始

to=yyyy-mm-dd 12:00

示例:

  • to=2019-12-29 12:00
  • 到11:59:59结束,不包含12:00 

方案A:第二次API调用

 

示例

&from=2019-12-29 12:00&to=2019-12-29

  • 从2019年12月29日中午开始
  • 到2019年12月29日凌晨结束
 

from=yyyy-mm-dd 12:00

示例:

  • from=2019-12-29 12:00
  • 从12:00开始,包含12:00

 

to=yyyy-mm-dd

示例:

  • to=2019-12-29
  • 到凌晨结束

 

方案B:第二次API调用

from=yyyy-mm-dd 12:00

示例:

  • from=2019-12-29 12:00
  • 从12:00开始,包含12:00

to=yyyy-mm-dd+1 00:00

+1 = 第二天的00:00

示例:

  • to=2019-12-30 00:00
  • 表示在12月30日开始之前。

请注意:方案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密钥类型 AppsFlyerAdmin_us-en.pngV1.0 API密钥
渠道权限
代理访问权限
代理数据透明化
应用层级指定货币
应用层级指定时区
数据时效性
  • 与数据总览面板的时效性一致。
  • 报告更新会有数小时的延迟:
    • 自然应用内事件
  • 每日更新一次的报告包括:
    • 卸载
    • 归因后假量-应用内事件
    • 广告收入
历史数据 是。须遵循数据保存期限频次限制规定。
非自然量数据
自然量数据
拉取频次限制

原始数据的API调用限制

大小限制
  • 调用API后最多可拉取20万/100万行数据。
  • 如果报告中的数据条数正好是20万/100万条,基本可以判定数据有缺失。
  • 您可以使用maximum_rows参数来选择报告所含的数据行数上限。
  • 出现这种情况时,请进行多次调用,每次在from/to时间范围中指定某一天的具体时间。

API错误代码及疑难解答

错误代码、问题表现及解决方案
状态 代码 问题表现/报错 解决方案
    所选时间段中有数据缺失,或原始数据和汇总数据报告之间有数据差异。

请检查是否配置了timezone时区参数。如果未配置该参数,则数据会以UTC时间发送,而非应用层级的指定时区。

OK 200 CSV文件为空

URI中addtional_fields出现了一次以上。

OK

200

CSV文件为空

请确保“from”和“to”的日期都是yyyy-mm-dd格式。

Bad request
(请求无效)

400

Raw Reports historical lookback is limited to 90 days
(不能查看超过90天以前的原始数据报告)

tofrom的时间范围调整到3个月以下

Bad request
(请求无效)

400

Your API calls limit has been reached for report type
(您的API调用频次已达到所选报告类型的上限)

-
Bad request
(请求无效)
400

Invalid limit type
(限制类型无效)

report_rows的值只能是200000或1000000。
Unauthorized
(无权限)

401

Supplied API token is invalid 
(您提供的API密钥无效)

需要AppsFlyer管理员账户提供正确的API密钥。
Unauthorized
(无权限)

401

Account may be suspended
(账户可能已关停)

请登入面板并查看账户状态。

Not found
(不存在)

404

 

API密钥与应用不匹配,需要AppsFlyer管理员账户提供正确的API密钥。

这篇文章有帮助吗?