Master API — 通过API获取拉新指标

高阶付费

概要:您可以通过该API获取指定的LTV、活跃、Protect360、和留存等维度的投放效果指标(CSV或JSON格式),且能同时拉取多个应用的数据。

 注意事项!

  • 从2023年5月31日起,AF将不再支持此API,并仅支持Master API V2。
  • Master API V2即将上线。

Master API — 通过API获取拉新指标

  • 可用KPI与数据总览、活跃和Protect360面板中的KPI一致。
  • 使用Master API时,请在URI中定义您需要拉取的数据。这与Pull API的使用方式很相似,调用后会返回CSV或JSON格式的文件。
  • Master API具有以下特点:
    • 以AppsFlyer数据透视表的结构为基础
    • 对代理和渠道不可用

Master API简介

概念 该API由路径、标头和带数据请求参数的JSON构成,调用后会以CSV格式返回数据。
路径 https://hq.appsflyer.com/export/master_report/v4?
HTTP方法 GET
数据时效性
  • Master API的数据每天更新一次,您可在更新后的24-48小时内拉取到新数据,具体取决于您应用配置中的指定时区。
  • 请使用下文所述的数据时效端点判断数据是否已更新完毕。部分指标的更新时间早于其他指标。

数据时效端点:

  • 数据时效端点会返回数据最近一次更新的日期,日期格式为yyyy-mm-dd,如2019-12-31
  • 举例说明:您在2020年1月2日时想要拉取2019年12月一整月(31天)的数据。在提交12月的Master API请求之前,请先通过数据时效端点查询最近一次的数据更新时间,以确保2019年12月31日的数据已更新完毕。也就是说,该端点应返回一个大于或等于2019-12-31的值。

https://hq1.appsflyer.com/master/lastupdate?api_token=[token]

Master API简介

API参数

https://hq.appsflyer.com/export/master_report/v4?api_token=api_token &app_id=app_id&from=yyyy-mm-dd&to=yyyy-mm-dd&groupings=groupings&kpis=kpis

调用参数

参数

是否必须配置
api_token  AppsFlyerAdmin_us-en.png需要由管理员获取token。该API token的获取方式为:点击面板右上角的邮箱地址 > API Tokens 是 
app_id
  • 即AppsFlyer后台显示的应用ID。
  • 请将此应用ID复制粘贴到路径中。
  • 对于iOS应用,请添加前缀id
  • 如需查询所有应用的数据,请使用app_id=all
from

用于指定日期范围中的起始日期(LTV维度)

  • 格式:yyyy-mm-dd
  • 示例:from: 2020-01-02
是 
to  

用于指定日期范围中的截止日期(LTV维度)

  • 可用的日期范围天数:1-31天
  • 拉取单天数据:fromto须设为同一个值。
  • 格式:yyyy-mm-dd
  • 示例:from: 2021-01-01, to: 2021-01-31即为31天的数据。
 是
groupings

用于将数据按参数分组,以逗号区隔。可用参数请见下一节中的分组维度表。

示例:groupings=pid,geo

 是
kpis

用于配置您想要拉取的KPI,各KPI之间以逗号区隔。可用的KPI列表请见后文表格。

示例:kpis=installs,clicks, impressions,sessions,retention_day_7

 是
filters

您可以使用一个或多个筛选条件来筛选数据。

currency 如需按应用配置中的指定货币拉取数据,请将该参数设置为currency=preferred
timezone

如需按应用配置中的指定时区拉取数据,请将该参数设置为timezone=preferred。详情请见数据本地化规则

format

默认情况下,该API会以CSV格式返回数据。如果您想要获取JSON格式的数据,请在URI中添加参数&format=json

分组

您可以使用以下维度对收集到的数据进行分组,以便更快捷准确地分析相关信息。这些字段的详细说明请见此文档

分组维度
可用参数
分组维度的显示名称 LTV KPI 留存KPI 活跃KPI Protect360 群组

app_id

App ID
(应用ID)

PID

Media Source
(媒体渠道)

af_prt

Agency
(代理商)

C

Campaign
(广告系列)

af_adset

Adset
(广告组)

af_ad

Ad
(广告素材)

af_channel

Channel
(流量入口)

af_siteid

Publisher ID
(子渠道ID)

af_keywords

Keywords
(关键词)

is_primary

Is Primary Attribution
(是否为主要转化来源)

af_c_id

Campaign ID
(广告系列ID)

af_adset_id

Adset ID
(广告组ID)

af_ad_id

Ad ID
(广告素材ID)

install_time

Install Time
(激活时间)

是*

attributed_touch_type

Touch Type
(广告互动类型)

geo

GEO
(地理位置)

*在活跃维度的KPI中,激活时间即事件时间。

KPI

KPI即用于说明应用使用情况的指标。您可以使用下表所列维度对KPI进行分组。

LTV留存活跃群组Protect360
LTV(生命周期价值)— 汇总的事件数据,即选定时间范围内激活应用的用户从激活之日起到目前为止所完成的事件数据。
KPI的API名称 说明
impressions 选定时间范围内的展示量
clicks 选定时间范围内的点击量
installs 选定时间范围内的激活量
cr 转化率
sessions 在选定时间范围内激活应用的用户打开应用的次数
loyal_users 在选定时间内激活应用的忠实用户数
loyal_users_rate 忠实用户数/总激活数
cost

选定时间范围内所产生的总成本。详情请见局限性一节

revenue 在选定时间范围内激活应用的用户所产生的LTV收入
roi 在选定时间范围内的投资回报率
arpu_ltv 在选定时间范围内激活应用的用户平均带来的收入
average_ecpi 选定时间范围内的平均有效激活成本(eCPI)。需在调用中同时包含成本和激活参数才能获取该指标。
uninstalls 在选定时间范围内激活应用,之后又将其卸载的用户
uninstalls_rate 卸载率
event_counter_[event%20name]* 事件发生次数
unique_users_[event%20name]* 完成相关事件的独立用户数
sales_in_usd_[event%20name]* 与事件一并上报的收入
*事件名称须小写

推算KPI

除上文所述的KPI之外,您也可以在Master API报告中添加推算KPI,这样您就能在Master API报告中配置自定义的推算报告。

您可以在KPI计算公式中添加各种预定义KPI,数量不限。

Master API支持标准的算术运算符,包括转码为%2b的加号(+)、减号(-)、乘号(*)和转码为%2f的除号(/)。

推算KPI的字段名称必须以“calculated_kpi_”开头,后接任意有效字符串,如“calculated_kpi_purchaserate”。

 示例

前三天的综合留存率

kpis=installs,loyal_users_rate&calculated_kpi_3days_retention=
retention_day_1%2Bretention_day_2%2Bretention_day_3

每次展示的平均收入

kpis=installs&calculated_kpi_rev_per_impression=revenue%2Fimpression

群组第7天的ROI

kpis=installs,roi,arpu_ltv,cost,revenue&calculated_kpi_roi_day_7=
(cohort_day_7_total_revenue_per_user-average_ecpi)%2Faverage_ecpi

筛选条件(可选)

参数 说明 示例 是否必须配置

PID

用于筛选具体渠道的数据,可以用逗号来区隔多个渠道名称。

pid=organic,applovin_int

C

用于筛选具体广告系列的数据,可以用逗号来区隔多个广告系列名称。

c=my_sample_campaign

af_prt

用于筛选具体代理的数据,可以用逗号来区隔多个代理名称。

af_prt=moburst

af_channel

用于筛选具体流量入口的数据,可以用逗号来区隔多个流量入口名称。

af_channel=Instagram

af_siteid

用于筛选具体子渠道的数据,可以用逗号来区隔多个子渠道ID。

af_siteid=12345678

geo

用于筛选具体国家的数据,可以用逗号来区隔多个国家名称。

geo=US,DE

时间范围字段

Master API中的时间范围可精确到天。

ToFrom为时间范围字段,用于界定数据拉取的时间段。

 示例

  • 时间范围可精确到天:请以天为单位界定时间范围,如From=2017-08-15&to=2017-08-17

本地化配置

本地货币和应用层级指定时区是在AF后台的应用配置页中设置的。Master API数据可以使用系统默认货币和时区拉取数据,也可以按应用层级的指定货币和时区拉取。

数据本地化遵循以下规则:

  • 如需按应用层级的指定时区/货币来拉取数据,请确保所有应用都配置了相同的时区/货币,否则只能按UTC和USD来拉取数据。时区和货币是分开设置的,也就是说,如果您为所有应用配置了相同的货币和不同的时区,那么您可以用指定货币来拉取数据,但不能用指定时区拉取。
  • 如果您在选定时间范围内更改了面板应用配置中的时区,则报告会呈现最近一次时区更改后的相关值。

您可以使用以下参数来选择应用层级设置。注意:如果您不使用应用层级设置参数,则会拉取到以USD为货币、以UTC为时区的数据。

参数 说明 示例 是否必须配置

currency

以应用配置中的指定货币显示金额

currency=preferred

timezone

使用应用配置中的指定时区

timezone=preferred

如需使用Master API拉取指定时区的数据,必须使用timezone=preferred参数。

调用示例

您可以在使用Master API时复制粘贴以下URL示例,帮助您节省时间。在使用URL之前,请务必:

  • 将应用名称com.greatapp替换成您的应用ID
  • 将[api_token ]替换成您的实际API token
  • 根据实际需要修改“from”和“to”的日期范围
  • 根据实际需要修改KPI
  • 如需按应用层级的指定时区和货币拉取数据,请在查询URL中添加&timezone=preferred和/或&currency=preferred
详细的Facebook报告

对比Facebook广告的投放效果:

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&pid=facebook
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,roi
详细的Google Ads报告
对比Google Ads的投放效果:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&pid=googleadwords_int
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,sessions,loyal_users,cost,revenue,arpu_ltv,roi
具体国家的报告
假设要拉取所有应用的北美(美国和加拿大)数据,则可使用以下URL:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=geo,pid,c&kpis=
installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,
roi&geo=us,ca	
关键词效用报告
根据用户在激活应用时使用的关键词对比其ROI等KPI:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_keywords
&kpis=roi,arpu_ltv,average_ecpi,installs,loyal_users_rate,cost,revenue
代理效果报告
对比所有代理的投放效果:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=af_prt,pid,c&kpis=installs,
loyal_users_rate
网盟效果报告
筛选媒体渠道为“affiliates”(网盟)的数据,考察哪个网盟带来的优质用户激活量最大,从而识别出投放效果最好的网盟(详情请见网盟的激活归因原理):
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_siteid&pid=affiliates
&kpis=installs,loyal_users_rate,arpu_ltv,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_30,retention_rate_day_30
归因类型报告
判断哪种广告互动带来的用户质量最高,是点击、展示还是自然量:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=attributed_touch_type
&kpis=installs,sessions,loyal_users_rate,arpu_ltv
渠道留存率报告
对比各渠道为账户下所有应用带来的用户在激活后第1、7、15、22和30天的留存率:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=pid,c
&kpis=installs,loyal_users_rate,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_22,retention_rate_day_22,retention_day_30,retention_rate_day_30

局限性及问题排查

局限性

  • 成本数据
    • 不同成本维度的可用性(即广告组、广告素材、地理位置、流量入口和子渠道)取决于具体的广告平台
    • 如需拉取eCPI数据,请在URL中同时加入激活和成本参数。
    • 总体而言,无论您查询的是什么维度的数据,所有流量来源,包括自有媒体(只要您使用带成本参数的AppsFlyer链接进行投放),都能全面支持成本数据。部分自归因平台会使用他们自己的API,这类API通常仅支持某些特定维度的成本数据。比如Facebook不支持在一次调用中同时按地理位置和流量入口分组,但可以分两次单独调用这两个维度的数据。
    • 对于近期(约最近7天内)有成本数据但无激活数据的广告系列,Master API无法拉取其相关数据。
  • 分组:指定的分组维度仅适用于LTV、活跃和留存KPI。如某个KPI的数据不可用,则API会返回N/A。举例来说,假设您请求了retention_rate_day_7(第7天的留存率)数据,并以af_channel(流量入口)分组,这时API返回N/A,则表示该数据不可用。
  • 报告行数上限:20万行
  • 事件名称:Master API目前不支持带有正斜杠“/”的事件名称。为避免出现数据拉取不到的情况,请勿在事件名称中使用“/”。
  • 处理时间:您选择的应用越多,处理时间就越长,等待响应的时间也就越长。

疑难解答

 

响应消息

说明

200 OK  
  • 问题:未返回文件
  • 未发送token
401 Unauthorized The supplied API token is invalid
(您提供的API token无效)
  • 服务器无法验证相关请求。API token缺失或无效。
  • 请确保URL中的API token正确无误。API token是通过api_token参数传递的。
404 Not found
(未找到)
  • 网络连接问题
  • 您的套餐中不包含Master API
416 No Groupings Selected
(未指定分组维度)
  • Master API提供汇总报告,因此需要指定数据汇总的维度。
  • 请使用分组参数指定分组维度
403 Unrecognized date format.
(日期格式无法识别)
请检查并更正日期
403 From date can't be after To date.
(开始日期不能晚于截止日期)
请检查并更正日期
403 From and To dates must have the same granularity format.
(开始日期与截止日期的颗粒度必须一致)
请检查并更正日期
403 No KPIs provided
(未提供KPI)
 
403 One or more of the formula's operators are not supported when not Unicode.
(公式中有一个或多个逻辑运算符不是Unicode,因此不支持)
 
403 No calculated KPI name provided.
(未提供计算后的KPI名称)
 
416 Something went wrong.Please re-try to download in a minute, choose a narrower time range, or contact AppsFlyer support.
(出错了。请稍等片刻,缩短时间范围后重新尝试下载,或联系AppsFlyer技术支持团队。)
  • 检查日期是否符合yyyy-mm-dd格式
  • 如果您将KPI类型设定为Cohort(群组),请确保群组天数在1-90的范围内。该API无法拉取群组天数为第0天的数据。
416 The requested time range is in UTC only (prior to the timezone change)
(指定时间范围内的数据仅能以UTC为时区(在时区更改前))
 
403 "}"Not authorized app-ids: <app_ids>  
  • 如果您请求了某个应用的数据,而该应用不在面板的应用列表内,就会收到这条报错消息。
  • 请检查app_id参数中的应用ID是否正确无误。
  • 安卓应用的应用ID即Package ID。

    iOS应用的应用ID是App ID,而非Bundle ID

416 Please select authorized app-id
(请选择已授权的应用ID)
 
416 No Groupings Selected
(未指定分组维度)
 
416 Wrong API Fields
(API字段有误)

该字段不存在或禁止使用

416 Other reason
(其他原因)

数据超过20万行