Pull API 原始数据报告

高阶付费
推荐用于
营销人员
最近更新：

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

PullAPIRaw_us-en.png

Pull API 原始数据报告

  • Pull API能够帮助您拉取到CSV格式的原始数据报告。详情请见原始数据报告说明。
  • 可用的筛选条件包括：媒体渠道、日期范围、应用内事件名称以及地理位置。
  • Pull API的其他功能包括：
    • 选择货币
    • 选择时区

Pull API能够拉取到的原始数据报告

报告 说明 更新频率
原始数据报告（非自然）
激活 用于记录非自然激活。每当有用户首次启动应用时就会生成一条记录。
 实时
应用内事件 用于记录用户完成的事件。
 实时
卸载 用于记录用户的应用卸载情况。
 每日报告
重装激活
 用于记录用户卸载应用后与拉新渠道互动并在再归因窗口期内重新安装并激活应用的情况。 实时
原始数据报告（自然量）
自然激活
 用于记录用户首次打开应用的情况。
 持续滚动
自然应用内事件
 用于记录用户所完成的事件的详细信息。 持续滚动
自然卸载
 用于记录用户的应用卸载情况。 每日报告
自然重装激活
 用于记录带量的再营销渠道在再互动窗口期内带来的广告收入。
 每天更新一次
广告收入原始数据
非自然广告收入
 		用于记录非自然（由媒体渠道带来的）用户产生的广告收入。 每日报告
自然广告收入 用于记录自然（未归因到任何渠道的）用户产生的广告收入。 每日报告
Protect360 防作弊
激活 用于记录系统识别的激活假量，AF不会将这些激活归因到任何媒体渠道。 实时
归因后-重新被判断为假量 用于记录来自虚假激活的应用内事件，AF不会对这些事件进行归因。 实时
应用内事件 用于记录Protect360识别到的应用内事件假量。 每日报告
归因后假量-应用内事件 用于记录归因到某渠道后被识别为假量的激活所产生的应用内事件，或直接被识别为假量的应用内事件。 每日报告
点击假量 用于记录被Protect360拦截的用户所完成的点击。 每日报告
已拦截的激活回传 若某渠道带来的激活被拦截，该报告会记录发送到这些渠道的回传。 实时
数据回传
激活回传 用于记录用户首次打开应用所形成的激活。 每日报告
应用内事件回传 用于记录发送到渠道的应用内事件回传。 每日报告
再营销应用内事件回传 用于记录用户在再互动窗口期内完成的应用内事件。 实时
再营销转化回传 用于记录用户在再互动窗口期内完成的应用内事件。 实时

相关文档：如何选择合适的数据传输工具/报告API

使用Pull API拉取原始数据

Pull API原始数据的拉取方式：

  1. AppsFlyerAdmin_us-en.png获取API token。只有账户管理员才能获取该token。
  2. 将该API token发送给您的开发人员，在认证头（Authentication Header）中使用。
  3. 将下表所列的相关参数发送给您的开发人员，让其在调用API时输入这些参数。这些参数用于界定报告的重点内容、信息梳理方式以及报告覆盖的时间范围。
  4. 让您的开发人员按照开发者资源中心的Pull API原始数据指南进行操作。

参数

参数 说明
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_download_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

Protect360字段

详情请见Protect360原始数据指南

时间范围字段

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

  • 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中只能出现一次。
  • 可用字段请见此列表。
  • 示例：additional_fields=device_download_time,deeplink_url

默认字段

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
Media Source
Channel
Keywords
Campaign
Campaign ID
Adset
Adset ID
Ad
Ad ID
Ad Type（广告类型）
Site ID
Sub Site 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
IDFA
Android ID
Customer User ID（客户用户ID）
IMEI
IDFV
Platform（系统平台）
Device Type（设备型号）
OS Version（OS版本）
App Version（应用版本）
SDK Version（SDK版本）
App ID
App Name（应用名称）
Bundle ID
Is Retargeting（是否为再营销广告）
Retargeting Conversion Type（再营销转化类型）
Attribution Lookback（归因回溯窗口期）
Reengagement Window（再互动窗口期）
Is Primary Attribution
（是否为主要转化来源）
User Agent
HTTP Referrer（HTTP来源标识）
Original URL

其他信息

特点与局限性

特点 说明
规定的API密钥类型 AppsFlyerAdmin_us-en.pngV2.0 token
渠道访问权限 否
代理访问权限 是
代理数据透明化 是
应用层级指定货币 是
应用层级指定时区 是
数据时效性
  • 与数据总览面板的时效性一致。
  • 报告更新会有数小时的延迟：
    • 自然应用内事件
  • 每日更新一次的报告包括：
    • 卸载
    • 归因后假量-应用内事件
    • 广告收入
历史数据 是。须遵循数据保存期限和频次限制规定。
非自然用户数据 是
自然用户数据 是
频次限制

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

问题排查

问题表现/报错 解决方案
所选时间段中有数据缺失，或原始数据和汇总数据报告之间有数据差异。

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