群组报告API

高阶付费

概要:群组报告API能让广告主以程序化的方式来获取群组数据。您可以使用该API将群组数据集成到您的BI以及营销自动化系统中。

群组报告API

群组报告API用于从AppsFlyer平台获取不同用户群组的投放效果数据,其功能相当于群组面板。 

如需使用群组和留存面板,您必须先界定您要查看的数据,即选择某个特定应用的用户,并将其按转化时间分组。可用的群组指标包括收入、ROI和事件转化率等。您可以将相关用户群组按广告系列或媒体渠道等维度进行拆分,以便对比分析。调用Cohort API后,会返回CSV或JSON格式的文件。您可以使用这些数据,考察用户或广告生命周期内的投放效果规律或变化。

详情请见群组功能的使用场景

Cohort API的使用方式如下

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

群组 API 参数

您可以使用下列参数获取您需要的数据。

参数名称

说明 是否必须发送 

bearer

在API验证头(authentication header)中使用的API token。

cohort _type

可能出现的群组归因(转化)类型为: user_acquisition(新用户获取)、retargeting(再营销)、unified(统一)

  • Unified(统一)指同时包含拉新广告和再营销广告的投放效果数据
  • 如果一个事件同时被归因到再营销和拉新广告,则返回的KPI中仅包含再营销事件,即is_primary=true。
  • 格式:字符串
  • 例如: "cohort_type": "user_acquisition"

min_cohort_size

群组体量下限可排除用户数量较少的群组,从而减少返回的数据条数。 也就是说用户KPI的值不小于您指定的群组体量下限。

  • 格式:整数
  • 允许发送的最小值:1。请勿发送零值(0)
  • 默认:1 
  • 示例:"min_cohort_size": 50

from 

用于指定日期范围中的起始日期(LTV维度)最早可设为当前日期之前的720天。 

  • 格式:格式为yyyy-mm-dd的字符串
  • 示例:"from": "2020-01-02"

to

LTV归因日期范围的截止日期

  • 日期范围内可包含的天数:1-31天
  • 如需查看单天数据:请将fromto设为同一个值。 
  • 格式:yyyy-mm-dd
  • 示例:"from": "2020-01-01", "to": 2020-01-31,即为31天。

granularity

过去72小时的数据颗粒度可精确到小时数。如需查看精确到小时数的数据,请发送"granularity": "hour",并在fromto的日期范围内设置具体时间值。

  • 格式:yyyy-mm-dd hh:mm:ss
  • 示例:
"granularity": "hour", "from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",

partial_data

为了避免数据失真和误判,群组报告会返回天数完整的数据。但广告主有时可能需要查看天数不完整的数据。 

针对某个查询的同类群组完整天数 = 当前日期 - to日期。

  • 【默认】如果为false,则返回天数完整的数据。
  • 如果为true,则最多返回同类群组180天的数据,包括不完整数据。 
  • 格式:布尔值
  • AF面板:false(即仅显示天数完整的数据)

示例:假设4月1日到30日之间转化的用户为一个群组,到5月10日,该群组的完整天数为10天。 

  • 如果没有设置,则【默认】返回群组第0-9天的数据,即从最后一个转化日期到当前日期的天数(10)。 
  • 如果设置为true,则返回群组第1-40天的数据。群组第11-40天包含不完整数据,因此不会返回这部分数据。以4月20日为例,由于自该日期以来仅过去了20天,因此数据不完整。其他日期以此类推。

请注意:仅在汇总类型为“累计”时才能拉取不完整数据。

 否

filters

您可以按归因后天数及其他条件对返回的数据进行筛选。 可用的筛选条件请见筛选维度列表

  • 格式:多层嵌套JSON中的字符串,必须以数组的形式发送相关值。
  • 按Geo(国家/地区)筛选示例:"filters": {"geo": ["US"]}表示仅包含归因到美国的用户。
  • 群组维度的period示例period(归因后天数)用于界定报告返回哪几天的衡量数据。可用的值为:0-180。0-180。
  • 默认:如果不设置period筛选条件,则返回群组第0-30天、60天、90天和180天的数据。 period筛选条件使用示例。
 否

groupings

  • 您可以使用分组参数在报告中添加列,帮助您更为宏观地了解数据。
  • 分组维度列表中选择1-7个值。
  • 格式:以数组形式组成的字符串
  • 示例:"groupings": ["af_ad", "c", "af_c_id", "af_prt"]

kpis

KPI可以说明您应用的使用情况,帮助您提炼用户行为中的关键信息。详情请见KPI的选择方式和格式设置说明
preferred_currency 该参数用于设置返回的KPI格式。详情请见KPI格式设置说明
preferred_timezone 该参数用于设置返回的KPI格式。详情请见KPI格式设置说明
aggregation_type 该参数用于设置返回的KPI格式。详情请见KPI格式设置说明
per_user 该参数用于设置返回的KPI格式。详情请见KPI格式设置说明

选择KPI并调整格式

  • 下表列出了可用的KPI以及各KPI对应的函数,调用某个KPI时会返回其对应的所有函数。
  • 拉取报告时默认包含的KPI为:users(用户)、ecpi(有效平均激活成本)以及cost(成本)。 
  • 每次调用仅限发送一个可选KPI。
  • 调用任一个KPI都会返回其对应的对应函数。 
  • 格式:以数组形式组成的字符串 
    • 示例A:"kpis": ["sessions"]
    • 示例B:"kpis": ["event_name"]
    功能
默认/可选  KPI(维度名称)  数量 cvr(转化率) Rate 总和 独立用户
数字 百分比 百分比 数字 数字
默认 用户 Y - - - -
默认 eCPI(有效平均激活成本) - - Y - -
默认 cost - - - Y -
可选 "event_name"(4)  Y Y - Y (3) Y
可选 revenue Y - - Y -
可选 ROAS(广告支出回报率) - - Y - -
可选 roi - - Y - -
可选 sessions Y - Y - Y(1)
可选 uninstalls(卸载)(2) Y - Y - -

(1) aggregation_type=on_day 时返回独立session(应用打开)数据。

(2) cohort_type=unified时不可用。 

(3) 这里的总和是指定事件产生的收入总和,在报告中显示为sum_event_name"

(4) 请注意:事件名称区分大小写

设置KPI函数的格式

您可以使用下列参数设置报告中的KPI格式。 

参数

是否必须发送 

preferred_currency

KPI收入的货币单位

  • 如果为true,则报告以应用层级的指定货币(在AF后台设置)为单位显示收入。 
  • 【默认】如果为false,则报告以美元为单位显示收入。
  • 格式:布尔 
  • AF面板:true

 否

preferred_timezone

日期范围的时区

  • 如果为true,则报告以应用层级的指定时区(在AF后台设置)显示时间。
  • 【默认】如果为false,则报告以UTC时区显示时间。
  • 格式:布尔 
  • AF面板:true

 否

aggregation_type

  • cumulative
  • on_day

"aggregation_type": "cumulative"

Format: String

per_user

由KPI值除以用户数得出。仅适用于相关KPI。

  • 如为true,则将KPI值除以该群组中的用户数。
  • 如为false,则不相除。
  • 格式:布尔 
  • 参数值为true的示例:假设总收入为$1000,用户数为500,则返回的值为$2。 
 否

分组及筛选维度列表

维度名称 

维度API值

分组

筛选条件

Ad

af_ad

Y

Y

Ad ID

af_ad_id

Y

Y

广告系列

c

Y

Y

Campaign ID

af_c_id

Y

Y

Channel(流量入口)

af_channel

Y

Y

媒体渠道

PID

Y

Y

Sub Param 1(可配置参数1)

af_sub1

Y

Y

Keywords

af_keywords

Y

Y

代理商

af_prt

Y

Y

Conversion Type(转化类型)(1)

cohort _type

Y

Y

Site ID

site_id

Y

Y

Revenue Type(收入类型)(2)

revenue_type

Y

Attributed Touch Type(归因触点类型)(3)

attributed_touch_type

Y

Y

广告组

af_adset

Y

Y

Adset ID

af_adset_id

Y

Y

国家

geo

Y

Y

Date(根据选定的cohort_type所定义的激活/再归因/再互动日期)

date

Y

Period(归因后天数)

时段

具体说明

 

x

Y

请注意: 

可选维度:

(1) Conversion Type(转化类型):user_acquisition(用户获取)、retargeting(再营销,包括re-engagementre-attribution,即再互动和再归因)、unified(统一)

  • 导出数据时:
    • re-engagement会显示为retargeting
    • re-attribution会显示为reattr

(2) 收入类型(Revenue Type):regularad_monetization

(3) Attributed Touch Type(归因触点类型):clickimpressionTVpre-installed

附加信息

period(归因后天数)筛选条件使用方式

Period是指归因后的天数,period 0即为归因当天(归因日)。假设某用户在1月1日激活应用,1月1日则为归因日。在period 0发生的购买事件即为用户在1月1日完成的购买;在period 3发生的购买事件即为用户在1月4日完成的购买;同理,对于在1月11日激活的用户,1月11日即为period 0,其在1月14日完成的购买即为period 3的购买事件。

如果您的报告日期范围设置为1月1日至1月11日,则返回的数据仅限在这段时间内归因(激活)的用户,而不包含其他数据。 

  • period可以是0-180之间的一个或多个值,如0、1、2、30、180。 
  • 如果没有指定period,则报告会根据默认值0、1、2到30、60、90和180返回数据。  

 period筛选条件使用示例

  • 该示例包含JSON查询参数、原始数据以及返回的CSV文件。
  • 查询筛选period 0、1和2,并选择revenue(收入)为KPI。
  • 返回的数据包含:
    • 总是返回用户、成本和ecpi数据 
    • 收入数据,包括收入总和以及每个period(即period 0、1和2)的收入。 

查询

{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": false,
    "from": "2019-12-01",
    "to": "2020-01-01",
    "filters": {
        "period": [
            0,
            1,
            2
        ]
    },
    "aggregation_type": "on_day",
    "per_user": false,
    "groupings": [
        "pid"
    ],
    "kpis": [
        "revenue"
    ]
}

原始数据

mceclip1.png

结果

mceclip0.png

特点与局限性

特点 说明 
渠道权限 

无。自动化投放平台可在广告主开放权限后使用该API。 

代理访问权限
代理数据透明化 不支持。对于通过代理带来的流量,其媒体渠道总是显示为相关代理的名称,而非实际带量渠道的名称。
应用层级的指定时区
应用配置中的指定货币 
大小限制
拉取频次限制
  • API调用频次限制:每个账户下每分钟最多60次,每天最多5万次
  • 调用后最多返回3万行数据。
自然量数据 可用
非自然量数据 可用
成本数据局限性
  • 只有带来过激活的广告系列才会有成本数据。
  • AppsFlyer的群组报告或Cohort API不上报包含大写字母的关键词成本数据。
  • 成本指标不能与某些分组维度相结合。如FMeta ads的数据可以按Geo(国家/地区)或Channel(流量入口)分组,但不能同时结合这两个维度进行分组。具体的可用分组维度组合取决于广告平台。
数据时效性

数据时效性取决于partial_data的值,具体如下: 

历史数据 日度群组数据:2年。
账户用户权限 AF账户管理员可在面板中查看身份验证token
广告收入

对于af_ad_revenue事件,如果您将汇总类型设置为“当天”,则2022年10月5日到2023年2月16日之间的独立用户指标不可用。

按周和按月分组

Cohort API不支持按周或按月分组。如需查看这两个维度的数据,请使用群组面板。

Cohort API的周期
  • 转化发生的当前周期为第0期,如第0个小时(Hour 0)或第0天(Day 0);下一个周期即为第1期,如第1个小时(Hour 1)或第1天(Day 1),以此类推。
  • AppsFlyer平台中的群组周期不考虑具体的激活时间戳,而是对群组小时数就近取整,群组天数以公历日期为准。对于根据具体激活时间戳判定群组周期(1小时为激活时间戳后的60分钟,1天为激活时间戳后的24小时)的平台,这一逻辑可能会使其群组数据与AppsFlyer之间产生一定差异。
日期
  • 这里的日期或日期范围是指生命周期价值(LTV)维度的日期,即用户被归因(激活转化)的日期,而不是具体用户行为发生的日期。
  • 最多可查看当前日期之前730天(即2年)内的数据
  • 查询范围上限为60天。