1. AppsFlyer Support
  2. 市场人员
  3. 分析与优化
  4. 数据分析
  5. 数据传输工具

使用Pull API拉取原始数据

Avatar
Gray Goldstein
最近更新：

概要：本文讲解了如何使用URI来拉取CSV格式的原始数据报告。

PullAPIRaw_us-en.png

Pull API原始数据报告的特点

  • 原始数据报告内容说明。
  • 返回的报告是CSV格式的。
  • 筛选条件包括：媒体渠道、日期范围、应用内事件名称以及地理位置。
  • 提供时区和货币选项。
  • Pull API适用于账户用户以及BI开发人员。
  • 频次限制：每天的报告拉取次数是有限额的。

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

概念定义

术语 说明
Pull API

通过URI下载CSV报告的解决方案。
API调用或调用

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

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

账户用户指南

URI模板简介

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

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

您可以在开发者资源中心（Dev Hub）中输入自定义数据并下载报告，以测试Pull API。

前期准备：

请按以下步骤从开发者资源中心（Dev Hub）下载报告：

  1. 进入AppsFlyer开发者资源中心（Dev Hub）的API参考信息部分。

    API_Reference.jpg

  2. 在左侧菜单栏中选择一个报告类型。
    如原始数据报告（非自然量） > 激活。
    各种可用报告类型请见下表。

  3. 填写所有必填字段。
  4. 界面右侧会显示URI模板。
  5. 点击复制图标，复制该URI。
  6. 在浏览器中打开一个新的标签页，然后将URI粘贴到地址栏中。
  7. 按下回车键，发送API调用。
    开始下载报告。
报告 说明 更新频率
原始数据报告（非自然）
激活假量 用于记录非自然激活。每当有用户首次启动应用时就会生成一条记录。
 实时
应用内事件 用于记录用户完成的事件。
 实时
卸载 用于记录用户的应用卸载情况。
 每日报告
重装激活
 用于记录用户卸载应用后与拉新渠道互动并在再归因窗口期内重新安装并激活应用的情况。 实时
原始数据报告（自然量）
自然激活
 用于记录用户首次打开应用的情况。
 持续滚动
自然应用内事件
 用于记录用户所完成的事件的详细信息。 持续滚动
自然卸载
 用于记录用户的应用卸载情况。 每日报告
自然重装激活
 用于记录带量的再营销渠道在再互动窗口期内带来的广告收入。
 每天更新一次
广告收入原始数据
非自然广告收入
 		用于记录非自然（由媒体渠道带来的）用户产生的广告收入。 每日报告
自然变现收入 用于记录自然（未归因到任何渠道的）用户产生的广告收入。 每日报告
Protect360 防作弊
激活假量 用于记录系统识别的激活假量，AF不会将这些激活归因到任何媒体渠道。 实时
归因后-重新被判断为假量 用于记录来自虚假激活的应用内事件，AF不会对这些事件进行归因。 实时
应用内事件 用于记录Protect360识别到的应用内事件假量。 每日报告
归因后假量-应用内事件 用于记录归因到某渠道后被识别为假量的激活所产生的应用内事件，或直接被识别为假量的应用内事件。 每日报告
点击 用于记录被Protect360拦截的用户所完成的点击。 每日报告
已拦截的激活回传 若某渠道带来的激活被拦截，该报告会记录发送到这些渠道的回传。 实时
数据回传
激活回传 用于记录用户首次打开应用所形成的激活。 每日报告
应用内事件回传 用于记录发送到渠道的应用内事件回传。 每日报告
再营销应用内事件回传 用于记录用户在再互动窗口期内完成的应用内事件。 实时
再营销转化回传 用于记录用户在再互动窗口期内完成的应用内事件。 实时

Pull API的原始数据参数

URI中的原始数据参数

参数 说明
api_token API身份验证令牌（密钥）。在调用示例中，该参数显示为<API TOKEN HERE>。
from
  • 日期范围包含一个from和to参数，其中的日期指的是用户行为发生的时间。
  • 格式：yyyy-mm-dd、yyyy-mm-dd hh:mm或yyyy-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_source和category参数：

  • 要筛选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

Protect 360

详情请见Protect360原始数据指南

日期和时间范围

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

  • 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天以前的原始数据报告）

将to和from的时间范围调整到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密钥。
这篇文章有帮助吗？

此组别内的文章

相关文章