概要：群组报告API能让广告主以程序化的方式来获取群组数据。您可以使用该API将群组数据集成到您的BI以及营销自动化系统中。
群组报告API
群组报告API用于从AppsFlyer平台获取不同用户群组的投放效果数据，其功能相当于群组面板。
如需使用群组和留存面板，您必须先界定您要查看的数据，即选择某个特定应用的用户，并将其按转化时间分组。可用的群组指标包括收入、ROI和事件转化率等。您可以将相关用户群组按广告系列或媒体渠道等维度进行拆分，以便对比分析。调用Cohort API后，会返回CSV或JSON格式的文件。您可以使用这些数据，考察用户或广告生命周期内的投放效果规律或变化。
详情请见群组功能的使用场景。
Cohort API的使用方式如下：
获取API token。只有相关账户的管理员才能获取该token。
- 将该API token发送给您的开发人员，用于认证头（Authentication Header）中。
- 将下表所列的相关参数发送给您的开发人员，让其在调用API时输入这些参数。这些参数用于界定报告的重点内容、信息梳理方式以及报告覆盖的时间范围。
- 让您的开发人员按照开发者资源中心的Cohort API使用指南进行操作。
群组 API 参数
您可以使用下列参数获取您需要的数据。
|
参数名称 |
说明 | 是否必须发送 |
|---|---|---|
|
bearer |
在API验证头（authentication header）中使用的API token。 |
是 |
|
cohort _type |
可能出现的群组归因（转化）类型为：
|
是 |
|
min_cohort_size |
群组体量下限可排除用户数量较少的群组，从而减少返回的数据条数。 也就是说用户KPI的值不小于您指定的群组体量下限。
|
否 |
|
from |
用于指定日期范围中的起始日期（LTV维度）最早可设为当前日期之前的720天。
|
是 |
|
to |
LTV归因日期范围的截止日期
|
是 |
|
granularity |
过去72小时的数据颗粒度可精确到小时数。如需查看精确到小时数的数据，请发送
"granularity": "hour",
"from": "2021-12-01 14:00:00", "to": "2021-12-03 11:00:00",
|
否 |
|
partial_data |
为了避免数据失真和误判，群组报告会返回天数完整的数据。但广告主有时可能需要查看天数不完整的数据。 针对某个查询的同类群组完整天数 = 当前日期 - to日期。
示例:假设4月1日到30日之间转化的用户为一个群组，到5月10日，该群组的完整天数为10天。
请注意：仅在汇总类型为“累计”时才能拉取不完整数据。 |
否 |
|
filters |
您可以按归因后天数及其他条件对返回的数据进行筛选。 可用的筛选条件请见筛选维度列表。
|
否 |
|
groupings |
|
是 |
|
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"]
- 示例A：
| 功能 | ||||||
|---|---|---|---|---|---|---|
| 默认/可选 | 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) 这里的总和是指定事件产生的收入总和，在报告中显示为 (4) 请注意：事件名称区分大小写 |
||||||
设置KPI函数的格式
您可以使用下列参数设置报告中的KPI格式。
|
参数 |
值 | 是否必须发送 |
|---|---|---|
|
preferred_currency |
KPI收入的货币单位
|
否 |
|
preferred_timezone |
日期范围的时区
|
否 |
|
aggregation_type |
|
是 |
|
per_user |
由KPI值除以用户数得出。仅适用于相关KPI。
|
否 |
分组及筛选维度列表
|
维度名称 |
维度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 |
x |
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 |
x |
|
Period（归因后天数） |
时段
|
x |
Y |
|
请注意： 可选维度： (1) Conversion Type（转化类型）：
(2) 收入类型（Revenue Type）： click、impression、TV、pre-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"
]
}
原始数据
结果
特点与局限性
| 特点 | 说明 |
|---|---|
| 渠道权限 |
无。自动化投放平台可在广告主开放权限后使用该API。 |
| 代理访问权限 | 否 |
| 代理数据透明化 | 不支持。对于通过代理带来的流量，其媒体渠道总是显示为相关代理的名称，而非实际带量渠道的名称。 |
| 应用层级的指定时区 | 是 |
| 应用配置中的指定货币 | 是 |
| 大小限制 | 无 |
| 拉取频次限制 |
|
| 自然量数据 | 可用 |
| 非自然量数据 | 可用 |
| 成本数据局限性 |
|
| 数据时效性 |
数据时效性取决于partial_data的值，具体如下：
|
| 历史数据 | 日度群组数据：2年。 |
| 账户用户权限 | AF账户管理员可在面板中查看身份验证token |
| 广告收入 |
对于af_ad_revenue事件，如果您将汇总类型设置为“当天”，则2022年10月5日到2023年2月16日之间的独立用户指标不可用。 |
| 按周和按月分组 |
Cohort API不支持按周或按月分组。如需查看这两个维度的数据，请使用群组面板。 |
| Cohort API的周期 |
|
| 日期 |
|