概要:您可以通过该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 |
数据时效性 |
数据时效端点:
|
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 |
![]() |
是 |
app_id |
|
是 |
from |
用于指定日期范围中的起始日期(LTV维度)
|
是 |
to |
用于指定日期范围中的截止日期(LTV维度)
|
是 |
groupings |
用于将数据按参数分组,以逗号区隔。可用参数请见下一节中的分组维度表。 示例: |
是 |
kpis |
用于配置您想要拉取的KPI,各KPI之间以逗号区隔。可用的KPI列表请见后文表格。 示例: |
是 |
filters |
您可以使用一个或多个筛选条件来筛选数据。 |
否 |
currency | 如需按应用配置中的指定货币拉取数据,请将该参数设置为currency=preferred | 否 |
timezone |
如需按应用配置中的指定时区拉取数据,请将该参数设置为timezone=preferred。详情请见数据本地化规则。 |
否 |
format |
默认情况下,该API会以CSV格式返回数据。如果您想要获取JSON格式的数据,请在URI中添加参数 |
否 |
分组
您可以使用以下维度对收集到的数据进行分组,以便更快捷准确地分析相关信息。这些字段的详细说明请见此文档。
分组维度 可用参数 |
分组维度的显示名称 | LTV KPI | 留存KPI | 活跃KPI | Protect360 | 群组 |
---|---|---|---|---|---|---|
app_id |
App ID |
是 |
是 |
是 |
是 |
是 |
PID |
Media Source |
是 |
是 |
是 |
是 |
是 |
af_prt |
Agency |
是 |
是 |
是 |
是 |
否 |
C |
Campaign |
是 |
是 |
是 |
是 |
是 |
af_adset |
Adset |
是 |
是 |
是 |
否 |
否 |
af_ad |
Ad |
是 |
是 |
是 |
否 |
否 |
af_channel |
Channel |
是 |
是 |
是 |
是 |
否 |
af_siteid |
Publisher ID |
是 |
是 |
是 |
是 |
是 |
af_keywords |
Keywords |
是 |
是 |
是 |
否 |
否 |
is_primary |
Is Primary Attribution |
是 |
否 |
是 |
是 |
否 |
af_c_id |
Campaign ID |
是 |
否 |
是 |
是 |
否 |
af_adset_id |
Adset ID |
是 |
否 |
是 |
否 |
否 |
af_ad_id |
Ad ID |
是 |
否 |
是 |
否 |
否 |
install_time |
Install Time |
是 |
是 |
是* |
是 |
是 |
attributed_touch_type |
Touch Type |
是 |
是 |
是 |
是 |
否 |
geo |
GEO |
是 |
是 |
是 |
是 |
是 |
*在活跃维度的KPI中,激活时间即事件时间。 |
KPI
KPI即用于说明应用使用情况的指标。您可以使用下表所列维度对KPI进行分组。
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]* | 与事件一并上报的收入 |
*事件名称须小写 |
留存是用于衡量现有活跃用户的指标。
局限性:
- 留存天数最长可支持到激活后的第30天,第0天为激活当天。也就是说,[x]的值不能超过30。
- 如果您请求的是retention_day_1(留存第1天)的数据,而该数据还未达到可用状态,则该指标会返回前一天激活应用的用户数据。举例来说,假设您在1月2日请求retention_day_1(留存第1天),拉取1月1日激活应用的用户数据。由于该指标尚未达到可用状态,因此该指标会返回12月31日激活应用的用户数据。
KPI | 说明 |
---|---|
retention_day_[x] | 第X天的用户留存量 |
retention_rate_day_[x] | 第X天的用户留存量在激活量中的占比 |
KPI | 说明 |
---|---|
activity_average_dau | 选定时间范围内的平均日活用户(DAU) |
activity_average_mau | 选定时间范围内的平均月活用户(MAU,其中单天数据为之前30天的总用户数) |
activity_average_dau_mau_rate | 平均DAU/MAU比率 |
activity_average_arpdau | 平均日活用户收入——某一天的收入除以总独立用户数得到的平均值 |
activity_sessions | 在选定时间范围内的应用打开次数 |
activity_revenue | 选定时间范围内上报的收入 |
activity_event_counter_[event%20name]* | 选定时间范围内用户产生的事件数 |
activity_sales_in_usd_[event%20name]* | 选定时间范围内与事件一并上报的收入 |
activity_average_unique_users_[event%20name]* |
在选定时间范围内完成某个事件的平均独立用户数 |
* 事件名称区分大小写 |
广告主可以使用AppsFlyer的群组功能来查看并对比多个群组在不同时间范围内的不同指标。
局限性:
- 取整误差:群组每用户KPI的数据精确到小数点后四位。也就是说,如果计算得出的每用户数据< 0.0001,则该数据会显示为0。举例来说,假设用户数为10万,总收入为9美元,则每用户平均收入为9/100000=0.00009,由于0.00009<0.0001,因此该值会显示为0。
- 群组天数:群组天数最长可支持到激活后的第90天,第0天为激活当天。群组天数的值[x]必须在1-90之间,Master API不支持cohort_day_0(群组第0天),但您可以在群组面板查看第0天的数据。
- Master API、群组报告API和群组面板之间的差异:三者处理重装激活的方式不同,更新数据的时间点也不同,因此得出的指标可能会有所不同。
Sessions(应用打开)
KPI | 说明 |
---|---|
cohort_day_[x]_total_sessions_per_user | 群组第X天 - 到第X天(含)的每用户累计session数 |
cohort_day_[x]_sessions_per_user | 群组第X天 - 仅该群组在第X天的session数 |
cohort_[x]_days_total_sessions_per_user |
现已无需再指定Cohort_day_1_total_sessions_per_user的KPI,而是在URL中添加Cohort_day_x_total_sessions_per_user 举例说明:如果您在URL中添加了cohort_3_days_total_sessions_per_user,则返回的报告中会对应有3列数据: |
收入
KPI | 说明 |
---|---|
cohort_day_[x]_total_revenue_per_user | 群组第X天 - 到第X天(含)的每用户累计收入 |
cohort_day_[x]_revenue_per_user | 群组第X天 - 仅该群组在第X天的ARPU |
cohort_[x]_days_total_revenue_per_user |
现已无需再指定Cohort_day_1_total_revenue_per_user的KPI,而是在URL中添加Cohort_day_x_total_revenue_per_user。 举例说明:如果您在URL中添加了cohort_3_days_total_revenue_per_user,则返回的报告中会对应有3列数据: |
cohort_day_[x]_total_event_[eventname]_revenue_per_user |
群组第X天指定应用内事件的每用户累计收入 |
cohort_day_[x]_event_[eventname]_revenue_per_user | 群组第X天指定事件的每用户收入 |
事件
KPI | 说明 |
---|---|
cohort_day_[x]_total_event_[eventname]_per_user | 群组第X天 - 到第X天(含)的每用户累计事件数 |
cohort_day_[x]_event_[eventname]_per_user | 群组第X天 - 仅该群组在第X天的事件 |
cohort_[x]_days_total_event_[eventname]_per_user |
现已无需再指定事件KPI,而是在URL中添加Cohort_day_x_total_events_per_user。 举例说明:如果您在URL中添加了cohort_3_days_total_events_per_user,则返回的报告中会对应有3列数据: |
说明 |
KPI |
---|---|
激活假量 | |
总计 | protect360_total_installs |
已拦截的激活 | blocked_installs |
拦截率 | blocked_installs_rate |
归因后被识别为假量的激活 | post_attribution_installs |
归因后的激活假量识别率 | post_attribution_installs_rate |
总体激活假量 | total_fraudulent_installs |
激活假量占比 | fraudulent_installs_rate |
激活假量 | |
被实时拦截的激活 | real_time_fake_installs |
归因后被识别为假量的激活 | post_attribution_fake_installs |
被劫持的激活 | |
被实时拦截的激活 | real_time_hijacked_installs |
归因后被识别为假量的激活 | post_attribution_installs_hijacked_installs |
验证规则 | |
被拦截的激活 | validation_rules_blocked_installs |
被拦截的归因 | validation_rules_blocked_attribution |
被拦截的激活假量细览 | |
根据子渠道黑名单拦截的激活 | blocked_installs_siteid_blacklist |
归因后根据子渠道黑名单识别的激活假量 | post_attribution_installs_siteid_blacklist |
已拦截的机器人作弊 | blocked_installs_bots |
归因后识别的机器人作弊 | post_attribution_installs_bots |
基于异常现象拦截的激活 | blocked_installs_behavioral_anomalies |
归因后基于异常现象识别的激活假量 | post_attribution_installs_behavioral_anomalies |
基于验证规则拦截的激活 | blocked_installs_install_validation |
被劫持的激活假量拦截细览 | |
被拦截的激活劫持 | blocked_installs_install_hijacking |
归因后识别的激活劫持 | post_attribution_installs_installs_hijacking |
基于CTIT异常拦截的激活 | blocked_installs_ctit_anomalies |
归因后基于CTIT异常拦截的激活 | post_attribution_installs_ctit_anomalies |
已拦截的点击撞库激活 | blocked_installs_click_flood |
归因后识别为点击撞库的激活假量 | post_attribution_installs_click_flood |
点击 | |
总计 | protect360_total_clicks |
已拦截的激活 | blocked_clicks |
% | blocked_clicks_rate |
应用内事件 | |
总计 | protect360_total_in_apps |
已拦截的激活 | blocked_in-app-events |
% | blocked_in-app-events_rate |
刷单迹象 - 新设备 | |
激活假量 | install_fraud_new_devices_total |
激活假量占比 | install_fraud_new_devices_total_installs_rate |
忠实用户假量占比 | install_fraud_new_devices_total_loyal_user_rate |
刷单迹象 - LAT设备 | |
激活假量 | install_fraud_lat_devices_total |
激活假量占比 | install_fraud_lat_devices_total_installs_rate |
忠实用户假量占比 | install_fraud_lat_devices_total_loyal_user_rate |
点击撞库迹象 | |
转化率 | conversion_rate |
点击撞库迹象 - CTIT | |
超过60分钟 | click_flood_over_1_hour_rate |
超过5小时 | click_flood_over_5_hours_rate |
推算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中的时间范围可精确到天。
To和From为时间范围字段,用于界定数据拉取的时间段。
示例
- 时间范围可精确到天:请以天为单位界定时间范围,如
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
和/或¤cy=preferred
对比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
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
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
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
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
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
局限性及问题排查
局限性
- 成本数据:
- 分组:指定的分组维度仅适用于LTV、活跃和留存KPI。如某个KPI的数据不可用,则API会返回N/A。举例来说,假设您请求了retention_rate_day_7(第7天的留存率)数据,并以af_channel(流量入口)分组,这时API返回N/A,则表示该数据不可用。
- 报告行数上限:20万行
-
事件名称:Master API目前不支持带有正斜杠“
/
”的事件名称。为避免出现数据拉取不到的情况,请勿在事件名称中使用“/
”。 - 处理时间:您选择的应用越多,处理时间就越长,等待响应的时间也就越长。
疑难解答
响应消息 |
说明 |
|
---|---|---|
200 OK |
|
|
401 Unauthorized | The supplied API token is invalid (您提供的API token无效) |
|
404 | Not found (未找到) |
|
416 | No Groupings Selected (未指定分组维度) |
|
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技术支持团队。) |
|
416 | The requested time range is in UTC only (prior to the timezone change) (指定时间范围内的数据仅能以UTC为时区(在时区更改前)) |
|
403 | "}"Not authorized app-ids: <app_ids> |
|
416 | Please select authorized app-id (请选择已授权的应用ID) |
|
416 | No Groupings Selected (未指定分组维度) |
|
416 | Wrong API Fields (API字段有误) |
该字段不存在或禁止使用 |
416 | Other reason (其他原因) |
数据超过20万行 |