1. AppsFlyer Support
  2. 报告
  3. 分析

Master API - 自定义汇总报告API - Customizable Aggregated Data API

Avatar
Gray Goldstein
最近更新时间:
  • 广告商
  • 开发商

介绍

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指标。

LTV留存报告活动报告群组报告Protect360
终身价值 - 计算从安装日起随后发生的所有全生命周期行为
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币种统计

 提醒

事件名称大小写敏感，您在链接里填写的事件名称必须与您打点的事件完成一模一样，包括字母大小写。

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. 时间范围字段

Master API 自定义集成报告API有两个时间维度可选：
  • 日报
  • 周报
广告主可以使用To 和 From两个参数来定义时间范围，然后获取您指定时间范围的KPI结果。
确切的周数及对应的日期请参考这里。

 示例

当选择每日报表时，需要在链接里填写具体的日期，如 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 参数。

示例

为了节省您的时间，您可以直接使用下面这些示例链接来快速获取报告。在使用前，需要您先确认如下几点：

  1. 将示例链接里的com.gratapp替换成真实的APP包名
  2. 从您的AppsFlyer账户里获取API密钥，替换示例里的 [TOKEN]
  3. 在示例链接里from、to参数后填写您想查询的日期
  4. 根据您的实际要求，替换示例里的kpi参数
  5. 如果您的APP使用的不是系统默认设置的UTC（GMT）时区及USD货币，那么需要您在链接里添加参数 &timezone=preferred 及 &currency=preferred 获取与您APP后台设置时区匹配的数据
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广告精细化分析
比较分析不同Google广告效果： 
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
特定国家数据分析
例如: 账户内所有APP在加拿大和美国的广告投放效果： 
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及其他各项指标： 
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字段名称

错误信息

错误的API字段名称: <api_field>

错误代码

416

描述

构造的链接里，有一个或多个KPIs参数名称不对导致无法无法获取数据。

解决方案

确保链接里的KPIs参数名称是正确的，KPIs参数名称可以参考如下两个文档 KPIs 和 分组纬度。

未选定任何分组维度

错误信息

未选定任何分组维度

错误代码

416

描述

Master API自定义集成报告生成的是汇总报告，所以必须设定所需KPI的分组纬度。

解决方案

在分组维度参数下增加具体的 分组维度信息 。

分周和分天的数据

错误代码

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
这篇文章有帮助吗？

此组别内的文章

相关文章