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

高阶付费

推荐用于

营销人员 开发商

最近更新： 2023年11月22日 09:33

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

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

Master API具有以下特点：

您可以获取指定的LTV、活跃、群组、Protect360和留存等维度的投放效果指标。可用KPI与数据总览、活跃、留存、群组和Protect360面板中的KPI一致。
每天计算一次。您可在更新后的24-48小时内拉取到新数据，具体取决于您应用配置中的指定时区。
以AppsFlyer数据透视表的结构为基础

使用Master API时，请定义您需要拉取的数据（这与Pull API的使用方式很相似），调用后会返回CSV或JSON格式的文件。

请按以下方式使用Master API：

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

API参数

参数	值	是否必须配置
app_id	即AppsFlyer后台显示的应用ID。请将此应用ID复制粘贴到路径中。对于iOS应用，请添加前缀id 如需查询所有应用的数据，请使用all app IDs作为参数值	是
from	用于指定日期范围中的起始日期（LTV维度）格式：yyyy-mm-dd 示例：`from: 2020-01-02`	是
to	用于指定日期范围中的截止日期（LTV维度）可用的日期范围天数：1-31天拉取单天数据：`from`和`to`须设为同一个值。格式：yyyy-mm-dd 示例：`from: 2021-01-01, to: 2021-01-31`即为31天的数据。	是
分组	用于将数据按参数分组，以逗号区隔。可用参数请见下一节中的分组维度表。示例：`groupings=pid,geo`	是
KPI	用于配置您想要拉取的KPI，各KPI之间以逗号区隔。可用的KPI列表请见后文表格。示例：`kpis=installs,clicks, impressions,sessions,retention_day_7`	是
筛选条件	您可以使用一个或多个筛选条件来筛选数据。	否
货币	如需按应用配置中的指定货币拉取数据，请将该参数设置为currency=preferred	否
时区	如需按应用配置中的指定时区拉取数据，请将该参数设置为timezone=preferred。详情请见数据本地化规则	否
格式	默认情况下，该API会以CSV格式返回数据。如果您想要获取JSON格式的数据，请选择`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	国家/地区	是	是	是	是	是
*在活跃维度的KPI中，激活时间即事件时间。

KPI

KPI可以说明您应用的使用情况，帮助您提炼用户行为中的关键信息。您可以使用下表所列维度对KPI进行分组。

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_name]	事件发生次数
unique_users_[event_name]	完成相关事件的独立用户数
sales_in_usd_[event_name]	与事件一并上报的收入

留存是用于衡量现有活跃用户的指标。

注意：

留存天数最长可支持到激活后的第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	选定时间范围内的平均月活用户（该时间范围中某个日期的单天数据是该日期之前30天内的独立用户总数）
activity_average_dau_mau_rate	平均DAU/MAU比率
activity_average_arpdau	平均日活用户收入——某一天的收入除以总独立用户数得到的平均值
activity_sessions	在选定时间范围内的应用打开次数
activity_revenue	选定时间范围内上报的收入
activity_event_counter_[event_name]	选定时间范围内用户产生的事件数
activity_sales_in_usd_[event_name]	选定时间范围内与事件一并上报的收入
activity_average_unique_users_[event_name]	在选定时间范围内完成某个事件的平均独立用户数

广告主可以使用AppsFlyer的群组功能来查看并对比多个群组在不同时间范围内的不同指标。

取整误差：群组每用户KPI的数据精确到小数点后四位。也就是说，如果计算得出的每用户数据< 0.0001，则该数据会显示为0。举例来说，假设用户数为10万，总收入为9美元，则每用户平均收入为9/100000=0.00009，由于0.00009<0.0001，因此该值会显示为0。
群组天数：群组天数最长可支持到激活后的第90天，第0天为激活当天。群组天数的值[x]必须在1-90之间，请注意：虽然您可以在群组面板查看第0天的数据，但Master API不支持cohort_day_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列数据：
Cohort_day_1_total_sessions_per_user（群组第1天的每用户平均总session数）+ Cohort_day_2_total_sessions_per_user（群组第2天的每用户平均总session数）+Cohort_day_3_total_sessions_per_user（群组第3天的每用户平均总session数）

收入

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，而是在URL中添加Cohort_day_x_total_revenue_per_user。举例说明：如果您在URL中添加了cohort_3_days_total_revenue_per_user，则返回的报告中会对应有3列数据： Cohort_day_1_total_revenue_per_user（群组第1天的每用户平均总收入）+ Cohort_day_2_total_revenue_per_user（群组第2天的每用户平均总收入）+Cohort_day_3_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_revenue_per_user。

举例说明：如果您在URL中添加了cohort_3_days_total_events_per_user，则返回的报告中会对应有3列数据：
Cohort_day_1_total_events_per_user（群组第1天的每用户平均总事件数）+ Cohort_day_2_total_events_per_user（群组第2天的每用户平均总事件数）+Cohort_day_3_total_events_per_user（群组第3天的每用户平均总事件数）

Protect360的KPI

说明	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对象，数量不限。每个KPI计算对象中包含一个键和一个值。其中的键即为该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	用于按子渠道筛选数据。可以用逗号来区隔多个渠道名称。	af_siteid=12345678	否
geo	用于按国家筛选数据。可以用逗号来区隔多个渠道名称。	geo=US,DE	否

本地化配置

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

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

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

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

参数	说明	示例	是否必须配置
currency	以应用配置中的指定货币显示金额	currency=preferred	否
timezone	使用应用配置中的指定时区	timezone=preferred	否

其他信息

特点与局限性

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