介绍
AppsFlyer提供的自定义汇总数据报告API功能可以根据您的需求生成专属于您的数据报告,无论您需要的是LTV维度分析、留存分析、群组用户分析、活跃用户分析,或是基于Protect360的假量分析,无论您是想分析一个APP、或是多个APP,您都可以借助这个功能在一张报表里完成全部的分析工作!
除此之外,您还可以根据您的特定需求划分不同的数据分组维度。
使用该API,创建链接是关键。与AppsFlyer的Pull API功能相同,数据默认以csv格式导出。
Master API是AppsFlyer另一个功能数据透视表pivot table的基础,这两个功能均属于高级功能。
Master API 链接结构
每一条Master API链接均由不同部分组成,包含强制参数和可选参数,下面会有详细介绍。这些参数主要有:Master API基础终端,强制参数,分组维度,KPI,计算后的KPI,过滤条件,时间范围和地区相关参数。
1. Master API 基础终端
每次调用Master API创建链接,必须以如下终端开始:
https://hq.appsflyer.com/export/master_report/v4?
Master API链接里所有动态参数都需要以 ‘?' 开头。
2. 强制参数
每一条Master API链接的基础结构都是一样的,如下:
https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=[app_id]&from=[from_date]&to=[to_date]&groupings=[list]&kpis=[list]
重要提示!
KPIs参数名称、分组维度名称和所有参数的名称均大小写敏感,且必须是小写字母。
下面这些表格会详细介绍必要字段的含义:
参数 | 描述 | 示例 | 强制? |
---|---|---|---|
api_token |
API密钥是账户唯一标识符,在控制面板左侧目录点击 API 数据接口,在新页面可获取API密钥 |
123510e9-1111-2222-3333-123bd8eeca9f |
是 |
from |
开始时间 |
2016-08-02, 2017-w23 |
是 |
to |
结束时间 |
2016-08-08, 2017-w24 |
是 |
app_id |
App包名,若想同时分析多个APP,APP包名间需以逗号隔开,或直接写“All”代表账户内全部APP |
app_id=app_id1,app_id2 app_id=all |
是 |
groupings |
分组维度,若需要填写多个分组维度,可用逗号隔开 |
groupings=pid,geo |
是 |
kpis |
KPI参数,多个参数间以逗号隔开,下面有详细介绍 |
kpis=installs,clicks, impressions,sessions,retention_day_7 |
是 |
3. 分组维度
使用这些分组维度可以让你更精准的分析数据。
链接参数 | 报表字段名称 | LTV KPIs |
留存 KPIs |
活跃用户 KPIs | 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 |
是 |
是 |
是 |
是 |
是 |
4. 关键绩效指标KPIs
关键绩效指标(KPI)是用于从不同的维度深入了解应用内用户行为的指标。单击每个选项卡查看其关联的KPI指标。
KPI链接参数 | 解释 |
---|---|
impressions | 所选时间段内的曝光数 |
clicks | 所选时间内的点击数 |
installs | 选定时间内的新激活数 |
cr | 点击到新激活的转化率 |
sessions | 所选时间段内新激活用户的会话数 |
loyal_users | 所选时间段内的忠实用户数 |
loyal_users_rate | 忠实用户数 / 新激活数 |
cost | 所选时间段内的买量成本 |
revenue | 所选时间段内新增用户到目前为止带来的收益 |
roi | 投资回报率 |
arpu_ltv | 所选时间段内新增用户的每用户平均收入 |
average_ecpi | 所选时间段内实际平均安装成本 |
uninstalls | 所选时间段内新增用户到目前为止的卸载数 |
uninstalls_rate | 卸载率 |
event_counter_[event%20name] | 事件发生次数 |
unique_users_[event%20name] | 执行事件的独立用户数 |
sales_in_usd_[event%20name] | 事件收入按照USD币种统计 |
KPI链接参数 | 解释 |
---|---|
retention_day_[x] | 在安装后第X天的留存用户数 |
retention_rate_day_[x] | 在安装后第X天的留存率 |
retention_week_[x] | 在安装后第X周的留存用户数 |
retention_rate_week_[x] | 在安装后第X周的留存率 |
KPI链接参数 | 解释 |
---|---|
activity_average_dau | 所选时间段内的平均日活用户数 |
activity_average_mau | 所选时间段内的平均月活用户数(计算逻辑是选定日期向前30天的月活数据) |
activity_average_dau_mau_rate | 平均日活数与月活数的比值 |
activity_average_arpdau | 平均每个活跃用户带来的收入 |
activity_sessions | 所选时间段内的会话数(应用打开数) |
activity_revenue | 所选时间段内的应用总收入 |
activity_event_counter_[event%20name] | 所选时间段内指定事件发生的次数 |
activity_sales_in_usd_[event%20name] | 所选时间段内指定事件带来的应用内收入USD总额 |
AppsFlyer群组分析报告让广告主基于拥有某一类共同特征的人群,从不同的时间维度和分组维度进行分析
会话数据
KPI链接参数 | 解释 |
---|---|
cohort_day_[x]_total_sessions_per_user | 截止到第X天,平均每个用户打开APP的总次数(包含截止日当天) |
cohort_day_[x]_sessions_per_user | 所选日期当天,平均每个用户打开APP的次数 |
cohort_[x]_days_total_sessions_per_user |
同时获取多份数据 |
收入数据
KPI链接参数 | 解释 |
---|---|
cohort_day_[x]_total_revenue_per_user | 截止到第X天,平均每个用户给APP带来的总收益(包含截止日当天) |
cohort_day_[x]_revenue_per_user | 在所选日期当天,平均每个用户给APP带来的总收益 |
cohort_[x]_days_total_revenue_per_user |
同时获取多份数据: Cohort_day_1_total_revenue_per_user 截止到第一天平均每个用户给APP带来的总收益; Cohort_day_2_total_revenue_per_user 截止到第二天平均每个用户两天内给APP带来的总收益; Cohort_day_3_total_revenue_per_user 截止到第三天平均每个用户三天内给APP带来的总收益; |
cohort_day_[x]_total_event_[eventname]_revenue_per_user |
截止到第X天,平均每个执行了指定事件的用户给APP带来的总收益(包含截止日当天) |
cohort_day_[x]_event_[eventname]_revenue_per_user | 在所选日期当天,平均每个执行了指定事件的用户给APP带来的总收益 |
事件数据
KPI链接参数 | 解释 |
---|---|
cohort_day_[x]_total_event_[eventname]_per_user | 截止到第X天,平均每个用户执行指定事件的总次数(包含截止日当天) |
cohort_day_[x]_event_[eventname]_per_user | 在所选日期当天,平均每个用户执行指定事件的总次数 |
cohort_[x]_days_total_event_[eventname]_per_user |
通过修改X天数参数,可同时获取多份数据 : Cohort_day_2_total_events_per_user 截止到第二天,平均每个用户在两天内执行指定事件的总次数; Cohort_day_3_total_events_per_user 截止到第三天,平均每个用户在三天内执行指定事件的总次数 |
KPI链接参数 | 解释 |
---|---|
protect360_total_installs | 非自然安装总计 |
blocked_installs | 拦截总数,包含:设备评级拦截,点击到激活时长异常拦截,安装验证失败拦截,子渠道黑名单拦截 |
blocked_installs_rate | 拦截安装比例 |
blocked_installs_device_rank | 由于设备评级低被拦截的安装数 |
blocked_installs_validation | 由于安装验证失败被拦截的安装数 |
blocked_installs_siteid_blacklist | 由于子渠道黑名单被拦截的安装数 |
blocked_installs_ctit_anomalies | 由于点击到激活时长异常被拦截的安装数 |
blocked_installs_bots | 机器人作弊被拦截的安装数 |
blocked_installs_click_flood | 点击泛滥作弊被拦截的安装数 |
blocked_installs_hijacking | 安装劫持作弊被拦截的安装数 |
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_installs | 来自新设备的安装数 |
install_fraud_new_devices_installs_rate | 新设备安装比例 |
install_fraud_new_devices_loyal_user_rate | 新设备忠实用户比例 |
install_fraud_lat_devices_installs | 打开‘限制广告追踪’设备的安装数 |
install_fraud_lat_devices_install_rate | 打开‘限制广告追踪’设备的安装比例 |
install_fraud_lat_devices_loyal_user_rate | 打开‘限制广告追踪’设备的忠实用户比例 |
install_fraud_suspicious_devices_installs | 可疑设备的安装数 |
install_fraud_suspicious_devices_install_rate | 可疑设备的安装比例 |
install_fraud_suspicious_devices_loyal_user_rate | 可疑设备的忠实用户比例 |
install_fraud_clean_device_installs | 合规设备的安装数 |
install_fraud_clean_device_install_rate | 合规设备的安装比例 |
install_fraud_clean_device_loyal_user_rate | 合规设备的忠实用户比例 |
click_flood_under_5_min_rate | 点击泛滥 - 点击到激活时长短于5分钟的安装比例 |
click_flood_from_5_to_60_min_rate | 点击泛滥 - 点击到激活时长在5分钟到60分钟间的安装比例 |
click_flood_over_60_min_rate | 点击泛滥 - 点击到激活时长超过60分钟的安装比例 |
contribution_rate | 辅助点击率 |
install_hijacking_up_to_10_sec_rate | 安装劫持 - 点击到激活时长在10秒内的安装比例 |
install_hijacking_10_to_30_sec_rate | 安装劫持 - 点击到激活时长在10秒到30秒间的安装避里 |
install_hijacking_over_30_sec_rate | 安装劫持 - 点击到激活时长超过30秒的安装比例 |
提醒
事件名称大小写敏感,您在链接里填写的事件名称必须与您打点的事件完成一模一样,包括字母大小写。
5. 可计算KPIs
除了上面提到的这些可直接添加到链接里的KPI参数外,您还可以在链接中添加计算符号,这样可以让您更快速的获取一个符合您需求的报告。
您可以在计算的KPI公式中插入任意数量的内置KPI.
支持的计算公式有: + (加号,必须编码为%2b), - (减号), *(乘号), / (除号,必须编码为%2) 以及 () (括号).
每个计算的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
6. 过滤条件
参数 | 描述 | 示例 | 强制? |
---|---|---|---|
pid |
用于选择展示指定媒体的数据,支持逗号分隔开多个选项 |
pid=organic,applovin_int |
否 |
c |
用于选择展示指定广告的数据,支持逗号分隔开多个选项 |
c=my_sample_campaign |
否 |
af_prt |
用于选择展示指定代理的数据,支持逗号分隔开多个选项 |
af_prt=moburst |
否 |
af_channel |
用于选择展示指定渠道(channel)的数据,支持逗号分隔开多个选项 |
af_channel=Instagram |
否 |
af_siteid |
用于选择展示指定子渠道的数据,支持逗号分隔开多个选项 |
af_siteid=12345678 |
否 |
geo |
用于选择展示指定国家的数据,支持逗号分隔开多个选项 |
geo=US,DE |
否 |
7. 时间范围字段
- 日报
- 周报
示例
当选择每日报表时,需要在链接里填写具体的日期,如 From=2017-08-15&to=2017-08-17
;当选择查看每周报表时,需要在链接里填写具体的周数,如 From=2017-w27&to=2017-w28
8. 本地化
您可以在 应用配置页面 为应用设置本地货币和时区。使用以下参数也可以在自定义集成报告中获取与应用配置相同时区的数据结果。
字段 | 描述 | 示例 | 强制? |
---|---|---|---|
currency |
自定义报告币种与应用APP设置的币种一致 |
currency=preferred |
否 |
timezone |
自定义报告时区与应用APP设置的时区一致 |
timezone=preferred |
否 |
- 如果账户下所有应用所设置的时区、货币一致(无论选择的是默认设置还是自定义设置),则数据按照设置展示;若账户下应用设置的时区、货币不一致,则数据按照GMT时区及USD货币展示。
- 按周展示的留存数据均按照GMT时区及USD货币展示,无法按照自定义时区、货币展示。
- 如果在所选时间范围内,广告主曾经更改过应用时区,则生成的报告仅包含从上次更改时区日期开始的值。例如您选择查看8月1日至8月30日的数据报告,您曾经在8月10日更改过应用的时区,则导出的报告仅包含8月10日至8月30日的数据。
注意
若希望通过自定义集成报告API生成的报告展示本地化时区,则必须在链接里添加timezone=preferred parameter参数。
数据导出格式
导出报告里所有字段的含义可参考 V5 format。
默认导出表格为csv格式。如果您希望接收JSON格式数据,请在构建的链接里增加 &format=json
参数。
示例
为了节省您的时间,您可以直接使用下面这些示例链接来快速获取报告。在使用前,需要您先确认如下几点:
- 将示例链接里的com.gratapp替换成真实的APP包名
- 从您的AppsFlyer账户里获取API密钥,替换示例里的 [TOKEN]
- 在示例链接里from、to参数后填写您想查询的日期
- 根据您的实际要求,替换示例里的kpi参数
- 如果您的APP使用的不是系统默认设置的UTC(GMT)时区及USD货币,那么需要您在链接里添加参数
&timezone=preferred
及¤cy=preferred
获取与您APP后台设置时区匹配的数据
比较分析不同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=com.greatapp&from=[from_date]&to=[to_date]&groupings=is_primary&kpis=revenue
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(有效安装成本),并不是总能获取到,这个取决于广告平台是否支持成本数据回传,以及广告平台的类型。例如,AppsFlyer自定义链接不支持直接回传成本数据,自归因平台仅能回传部分维度的成本数据。
总的来说,所有的流量渠道,包含自媒体平台,只要使用的是AppsFlyer的追踪链接,并且在链接里添加了成本数据相关的参数,您都可以获取各个维度的成本数据。自归因平台则通过他们各自的API接口,将部分维度的成本数据回传给AppsFlyer。
想了解更多渠道及成本数据,请点击 这里。
重要事项
- 某些分组维度仅适用于LTV全生命周期数据报告KPIs、活动报告KPIs或留存报告的KPIs。当某个指标的KPI无法获取时,报告会返回 N/A。例如,由于我们无法提供channel维度的七日留存报告,若您尝试获取这个报告,则报告会返回 “N/A”。
- 数据更新时间: 自定义集成报告是 以“日”为纬度生成的报告。所以如果应用APP在AppsFlyer后台设定的时区是UTC-,则仅能获取2天及2天前的报告;如果应用APP在AppsFlyer后台设置的时区是UTC+,则可以获取1天及1天前的报告。
- 报告最大行数:20万行。
故障排查
如下是各类报错信息的含义,以及对应的解决方案。
API密钥无效
错误信息
API密钥无效
错误代码
401
描述
这个错误信息表示,由于构造的链接里填写了错误的API密钥,或未填写API密钥,导致服务器无法执行此数据需求。
解决方法
确保构造的链接里填写的是正确的API密钥,并且正确的密钥是天蝎在参数 api_token
里。
未授权的App-ids
错误信息
请求ID:<request_id>。未授权的APP ID:<app_id>
错误代码
416
描述
若您想获取数据的APP未被添加到AppsFlyer后台,则您会在提交数据请求时收到这个提示。
解决方案
确认您填在 app_id
参数里的id是正确的。
注意
对于Android,APP ID就是包名。r Android, the app ID is the package ID.
对于iOS,APP ID是APP ID而不是bundle ID,更新信息请点 这里。
未配置KPIs
错误信息
请求ID: <request_id>。 [错误] 未配置KPIs
错误代码
403
描述
Master API自定义集成报告提供的是汇总报告,所以查询的KPIs参数是报告里的必须项。
解决方案
在kpis参数下添加具体需要查询的 KPis参数名称 。
错误的API字段名称
未选定任何分组维度
分周和分天的数据
错误代码
403
描述
如果您想获取分周的数据,请不要在date字段里填写日期,而应该填写对应的周数;反之亦然。
解决方案
在时间维度上填写具体的周数,如下述例子:
https://hq1.appsflyer.com/master/v4?api_token=<API_TOKEN>&from=2019-w4&to=2019-w4&groupings=geo,pid&kpis=installs,retention_week_2&app_id=com.sample.app
若想获取分天数据,请在时间维度上填写具体的日期,如下述例子:
https://hq1.appsflyer.com/master/v4?api_token=<API_TOKEN>&from=2019-08-01&to=2019-08-04&groupings=geo,pid&kpis=installs,retention_day_2&app_id=com.sample.app