群组报告API

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

群组报告API

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

扩展阅读:群组功能的各种形式及对比

开发人员注意事项

  • 日期:这里的日期或日期范围是指生命周期价值(LTV)维度的日期,即用户被归因(激活转化)的日期,而不是具体用户行为发生的日期。
  • 布尔值:true或false(区分大小写)。
  • 透明或不透明的代理流量:由代理的渠道带来的流量总是显示为代理的流量,而非具体渠道。这与目前的群组面板有所不同。
  • 仅限单个应用:群组报告API是一个单应用解决方案。这与群组面板不同,面板可一次调用多个应用的数据。
  • 数据时效性:详情请见特点和局限性部分。

API使用指南

本节主要讲解如何生成并使用群组报告API。

群组报告API要点简介

概述 群组报告API的调用由路径、header、以及包含数据查询的JSON组成,并默认以CSV文件的形式返回数据。
路径

https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id

路径参数(必须配置)
  • app_id:即AppsFlyer面板中显示的应用标识符。请将面板中的ID按原样粘贴到路径中。

查询参数

(可选)

以CSV或JSON格式返回数据。CSV格式是纯文本的表格,而JSON格式则更为结构化。

  • 【默认】csv文件名取决于具体查询。
  • json包含查询和结果部分。
  • 示例:format=json
  • https://hq1.appsflyer.com/api/cohorts/v1/data/app/app_id?format=json
HTTP方法 POST
适用格式 application/json
授权
  • Request Header(请求头)中的Bearer Token
  • 联系CSM帮助您启用群组报告API,然后从面板中获取token
    • 该token适用于同一个账户下的所有应用
日期限制
  • 最多可查看当前日期之前720天(即2年)内的数据。
  • 查询范围上限:60天
拉取频次限制
  • 每个账户的API调用频次不能超过每分钟60次、每天50000次。
  • 查询最多返回10000行数据。
布尔值 总是以小写字母显示:truefalse
群组报告API要点简介

Request header(请求头)

是否必须配置
Content-Type application/json 是 
Authorization Bearer api_token_placeholder 是 
Accept application/json 是 

筛选及分组参数

您可以使用筛选参数筛选出您需要的数据。

筛选参数

参数名称

说明 是否必须配置

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。
  • 默认:如果不设置period筛选条件,则返回群组第0-30天、60天、90天和180天的数据。详见period筛选条件使用示例
 否

您可以使用分组参数在报告中添加列,帮助您更为宏观地了解数据。

分组参数

参数

是否必须配置

groupings

  • 分组维度列表中选择1-7个值。
  • 格式:以数组形式组成的字符串
  • Example: "groupings": ["af_ad", "c", "af_c_id", "af_prt"]

选择KPI并调整格式

  • 下表列出了可用的KPI以及各KPI对应的函数,调用某个KPI时会返回其对应的所有函数。
  • 拉取报告时默认包含的KPI为:users(用户)、ecpi(有效平均激活成本)以及cost(成本)。
  • 每次调用仅限发送一个可选KPI。
可用KPI及对应函数
    功能
默认/可选 KPI(维度名称) 数量 cvr(转化率) 比率 总和 独立用户数
数字 百分比 百分比 数字 数字
默认 users(用户) 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) 请注意:事件名称区分大小写

参数

是否必须配置

kpis

从可用KPI中选择一个。AF后续计划开放多个KPI复选功能。

  • 调用任一个KPI都会返回其对应的对应函数。
  • 格式:以数组形式组成的字符串
  • 示例A:"kpis": ["sessions"]
  • 示例B:"kpis": ["event_name"]

KPI格式参数用于设置报告中的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"

格式:字符串

per_user

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

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

分组及筛选维度列表

可用分组及筛选维度

维度名称

维度API值

分组

筛选条件

Ad(广告素材)

af_ad

Y

Y

Ad ID(广告ID)

af_ad_id

Y

Y

Campaign(广告系列)

C

Y

Y

Campaign ID(广告系列ID)

af_c_id

Y

Y

Channel(流量入口)

af_channel

Y

Y

Media Source(媒体渠道)

PID

Y

Y

Sub Param 1(可配置参数1)

af_sub1

Y

Y

Keywords(关键词)

af_keywords

Y

Y

Agency(代理)

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

Adset(广告组)

af_adset

Y

Y

Adset ID(广告组ID)

af_adset_id

Y

 Y

Country(国家)

geo

Y

Y

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

date

Y

Period(归因后天数)

period 

具体说明

 

X

Y

备注:

可选维度:

(1) Conversion Type(转化类型):user_acquisitionretargetingunified

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

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

Curl示例

本示例包含完整的API调用。


curl -L -X POST 'https://hq1.appsflyer.com/api/cohorts/v1/data/app/<insert your app_id here>?format=<insert results format here>' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <cohort_api_token_placeholder. Note the token has more than 700 characters.>' \
-H 'Accept: application/json' \
--data-raw '{
    "cohort_type": "user_acquisition",
    "min_cohort_size": 1,
    "preferred_timezone": false,
    "from": "2020-01-01",
    "to": "2020-01-31",
    "filters": {
        "period": [
            0,
            1,
            2,
            10,
            30,
            60
        ],
        "geo": [
            "US",
            "CN"
        ],
        "pid": [
            "Facebook Ads",
            "googleadwords_int"
        ]
    },
    "preferred_currency": true,
    "aggregation_type": "on_day",
    "per_user": false,    
    "groupings": [
        "pid",
        "date"
    ],
    "kpis": [
        "sessions"
    ]
}'
示例返回的报告:CSV格式JSON格式

Python示例

import http.client
import mimetypes
conn = http.client.HTTPSConnection("hq1.appsflyer.com")
payload = "{\r\n    \"cohort_type\": \"user_acquisition\",\r\n    \"min_cohort_size\": 1,\r\n    \"preferred_timezone\": false,\r\n    \"from\": \"2020-05-01\",\r\n    \"to\": \"2020-05-10\",\r\n    \"preferred_currency\": true,\r\n    \"aggregation_type\": \"cumulative\",\r\n    \"per_user\": false,   \r\n     \"groupings\": [\r\n               \"pid\",\r\n         \"date\"\r\n        ],\r\n    \"kpis\": [\r\n        \"roas\"\r\n    ]\r\n}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer [Enter token here]',
  'Accept': 'application/json',
  'Content-Type': 'application/json'
}
conn.request("POST", "/api/cohorts/v1/data/app/[My App ID here]?format=csv", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
   

使用场景

示例1:留存

在1月期间激活应用的用户在群组第7天、第14天和28天的分渠道留存(session)数据

{
  "per_user": false,
  "groupings": [
    "pid"
  ],
  "filters": {
    "period": [
      7, 14, 28
    ]
  },
  "partial_data": false,
  "aggregation_type": "on_day",
  "min_cohort_size": 1,
  "cohort_type": "user_acquisition",
  "from": "2021-01-01",
  "to": "2021-01-30",
  "kpis": [
    "sessions"
  ]
}

示例2:分广告系列的购买数据

激活后群组第3天的分广告系列收入数据

{  
  "per_user": false,
  "groupings": [
    "c"
  ],
  "filters": {
    "period": [
      3
    ],
    "c":[
        "example_campaign_name"
    ]
  },
  "partial_data": false,
  "aggregation_type": "cumulative",
  "min_cohort_size": 1,
  "cohort_type": "user_acquisition",
  "from": "2021-01-01",
  "to": "2021-01-30",
  "kpis": [
    "Checkout Start"
  ]
}

示例3:昨日用户行为
查看在指定转化时段内转化(激活、再互动、再归因)的用户在昨天完成了什么操作。

您可以通过Data Locker群组报告中的可用数据获取该信息。转化时段需限制在前360天之内。

 

其他信息

相应代码及问题排查

响应代码

响应代码

响应消息

说明

200 OK

返回有效数据

200 OK
  • 未返回任何数据
    • 查询有效,但未找到匹配的数据。
    • 请确保日期范围不包含未来的日期。
    • 调用中未发送任何token。
401 Unauthorized
(无权限)
  • 身份验证token格式不正确。token应由700个字符组成,请检查您使用的token是否正确。
404 Not found
(不存在)
  • 排查并解决网络、防火墙等相关的问题。
  • 确保您使用的token是最新的。您可以从面板获取最新的token。
  • 确保路径中指明的应用具有群组报告API的使用权限,即您的套餐中包含群组报告API。AppsFlyer账户管理员可在后台“我的套餐”中查看该信息。
 422 Unprocessable entity
(无法处理)

出现该错误代码时,请:

  • 确保请求是以JSON形式发送的,而不能查询参数的形式发送。
  • 确保JSON的格式符合本文说明。
  • 确保日期格式正确

CSV文件名结构

返回的CSV文件名是基于API查询生成的,具体的文件名结构如下表所示。

CSV文件名示例

cohort_aggregation_type_per_user_kpi_report_app_id_from_to_timezone_currency_hash.csv
CSV文件名结构取决于API查询
变量 可能出现的值
aggregation_type
  • on_day
  • cumulative
per_user
  • per_user 
  • false: Null 
kpi 如sessions
app_id 请求的应用ID
from from开始日期的格式为:yyyy-mm-dd
to to截止日期的格式为:yyyy-mm-dd
timezone 默认时区为UTC
currency 默认货币代码为USD
hash

含字母和数字的5字符哈希字符串

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参数之间的映射关系。API解决方案与面板相似,但仍有不同之处。

API方案提供以下附加选项:

  • 货币选项
  • 时区选项
  • period(归因后天数)筛选条件
CohortMapping.jpg Cohortmapping2.jpg

两种汇总类型之间的区别

CohortRevnueCumulative.jpg

特点和局限性

特点
特点 说明
广告平台访问权限

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

代理访问权限
代理数据透明化 不支持
应用层级指定时区
应用层级指定货币
大小限制
拉取频次限制

API调用频次限制:每个账户每分钟限60次。

自然量数据 可用
非自然量数据 可用
成本数据局限性
  • 只有带来过激活的广告系列才会有成本数据。
  • AppsFlyer的群组报告或群组API不上报包含大写字母的关键词成本数据。
  • 成本指标不能与某些分组维度相结合。如Facebook的数据可以按Geo(国家/地区)或Channel(流量入口)分组,但不能同时结合这两个维度进行分组。具体的可用分组维度组合取决于广告平台。
数据时效性

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

历史数据 最早可查看2019年1月1日的转化数据(激活或再营销)
账户用户权限 AF账户管理员可在面板中查看身份验证token
这篇文章有帮助吗?