AppsFlyer Cohort API
概要
接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Cohort API | API | 聚合指标 | ✅ | ✅ | ✅ |
Cohort API 同样也是聚合数据 API。相比其他聚合数据 API，数据指标的形态更类似于 AppsFlyer 的 Cohort Dashboard 以及 AE 系统的留存分析模型的数据结果，即新增用户的第 N 日（或累计第 N 日）指标。
集成流程
- 登录 AppsFlyer 后台，获取 V2.0 API Token 与 App ID
- 登录 AE 后台，进入三方集成模块，新增 AppsFlyer Cohort API 方案，并完成相关配置
- 查看 AE 系统是否成功接收数据，并完成报表搭建
一、获取 API Token 与 App ID
1.1 获取 API Token
获取用于 Cohort API 的 V2.0 API Token
1.2 获取 App ID
可以在 AppsFlyer 后台「My Apps」找到您的应用的 App ID，安卓端以com.开头，如 com.demoapp.ta，iOS 以id开头，如id12345678
二、方案配置
获取完 AppsFlyer 的 API Token 与 App ID 之后，您可以登录 AE 系统，在「三方集成」模块中完成新方案的配置。下图是 AppsFlyer Cohort API 的配置界面，请您按照本章节内容完成方案的创建：
2.1 授权信息配置
点击「授权信息」下的「配置授权信息」按钮，在弹出框内填写 API Token 与 App ID
2.2 定时拉取
您可以在「定时拉取」模块设置 AE 系统定时拉取 AppsFlyer Cohort API 数据的策略，可以选择在每天的某时拉取一段时间的数据，单次最多拉取 31 天。由于拉取的数据也会计入数据量，建议不要定时拉取太长时间的数据
2.3 入库设置
您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。
2.4 集成配置
最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的类型，拉取的维度，以及入库后的事件名等。
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_name | 入库后的事件名，可以自定义 |
source | metrics | 数据中的指标维度，列表类型，可以自定义，但只可填写一个，且不可为空 |
| group_by | 数据中的分组维度，列表类型，可以自定义 | |
transfer | fields_whitelist | 字段过滤，列表类型，如果列表不为空，则 AE 系统只会入库列表中的字段，不在列表中的字段会被抛弃 |
double_columns | 数值类型字段定义，写在此处的字段将会以数值类型入库，需填写入库后的字段名 | |
| extra_params | aggregation_type | 是否累计数据，即返回的 N 日数据是第 N 日数据还是累计第 N 日数据，默认值为：，可选 cumulative、on_day |
| partial_data | 是否返回缺省日期的数据，默认为 false，即只返回完整天的数据。设置为 true，则包含不完整日的最多 180 天的数据会返回。仅当 aggregation_type 为 cumulative 时可用 |
- 分组维度
需要注意的是，Cohort API 最多支持 7 个分析维度，以下是默认的分析维度，如果需要调整，可以修改 source.group_by，调整时请使用字段名
| 字段名 | 入库名 | 默认 |
|---|---|---|
| Ad | af_ad | ✓ |
| Ad ID | af_ad_id | |
| Campaign | c | ✓ |
| Campaign ID | af_c_id | |
| Channel | af_channel | ✓ |
| Media Source | pid | ✓ |
| Sub Param 1 | af_sub1 | |
| Keywords | af_keywords | |
| Agency | af_prt | |
| Conversion Type | cohort_type | |
| Site ID | site_id | |
| Attributed Touch Type | attributed_touch_type | |
| Adset | af_adset | ✓ |
| Adset ID | af_adset_id | |
| Country | geo | |
| Date | date | ✓ |
请注意，如果您需要拉取 Facebook(Meta) 的数据，则分析维度请不要同时选择 af_channel 与 geo，否则将无法获取 Facebook 的成本数据
- 指标字段
需要注意的是，Cohort API 会返回 3 个默认指标以及 source.metrics 中填写的一个指标（默认为 revenue），以下是默认的指标字段。
| 字段名 | 指标名 | 描述 | 默认 |
|---|---|---|---|
| users（默认指标） | users | 人群总用户数（与时间窗口无关） | ✓ |
| ecpi（默认指标） | ecpi | 人群总eCPI（与时间窗口无关） | ✓ |
| cost（默认指标） | cost | 人群总成本（与时间窗口无关） | ✓ |
"event_name"（使用自定义事件的名称） | "event_name"_unique_users_day_N | 第 N 日自定义事件触发用户数 | |
| "event_name"_count_day_N | 第 N 日自定义事件完成数 | ||
| "event_name"_rate_day_N | 第 N 日自定义事件完成率 | ||
| "event_name"_sum_day_N | 第 N 日由自定义事件产生的收益额 | ||
revenue | revenue_count_day_N | 第 N 日收益事件触发数 | ✓ |
| revenue_sum_day_N | 第 N 日收益额 | ✓ | |
| roas | roas_rate_day_N | 第 N 日 ROAS | |
| roi | roi_rate_day_N | 第 N 日 ROI | |
sessions | sessions_unique_users_day_N | 第 N 日 Session 触发用户数（如果是累计指标则不返回该数据） | |
| sessions_count_day_N | 第 N 日 Session 数 | ||
| sessions_rate_day_N | 第 N 日留存率（ Session 触发用户数 / 人群总用户数） | ||
| uninstalls | uninstalls_count_day_N | 第 N 日卸载数 | |
| uninstalls_rate_day_N | 第 N 日卸载率 |
2.5 调整拉取指标
由于 Cohort API 会返回大量字段，如果不做字段的入库限制，则可能导致项目的属性过度膨胀，影响您的正常使用，因此，如果您需要调整拉取的指标，则需要进行如下操作：
- 调整 source.metrics：将需要拉取的指标的字段名，即上一节中的表格的第一列填入到 source.metrics 中，请注意 source.metrics 仅可填入一个指标，默认拉取的三个指标，即 users、ecpi、cost 不需要写在 source.metrics 中。如下图所示，如果我们希望拉取 uninstalls 的指标，则需要将 "uninstalls" 填入 source.metrics 中
- 调整 transfer.fields_whitelist：为了避免过多属性被创建，我们设计了 transfer.fields_whitelist 来过滤字段，只有写入其中的字段才会入库。Cohort API 返回的数据类似于我们的留存分析模型，默认情况下，它将返回一个指标的第 0~30、60、90、180 天等，如 revenue_count_day_7、roi_rate_day_30 等等。默认的集成配置中过滤了除分组字段、revenue_count_day_0、revenue_sum_day_0 以外的所有字段，如果您需要调整指标，或者希望使更多天的数据入库，可以将需要入库的指标的指标名（详见上节表格）添加到 transfer.fields_whitelist 中。如下图所示，在修改了拉取的指标为 uninstalls 后，需要在 transfer.fields_whitelist 中添加 "uninstalls_count_day_0"、 "uninstalls_rate_day_0" 等指标名，使其可以入库。
- 将指标名加入 transfer.double_columns：最后，为了让指标字段可以以数值类型入库，您还需要将上一步中添加的指标名也加入 transfer.double_columns。如下图所示：
2.6 数据入库规则
默认情况下，我们会将拉取的数据以事件形式写入 AE 项目中：
- 使用数据中的 date 字段，即用户的归因/转化时间，作为事件的 #event_time
- 数据事件名为：appsflyer_cohort_api
- 经过过滤后的字段将全数入库，在 transfer.double_columns 填写的字段将以数值类型入库，其他字段将以文本类型入库
2.7 标准化字段
以下事件属性会进行标准化处理：
| 原始字段 | 标准化字段 | 含义 |
|---|---|---|
| pid | te_ads_object.media_source | 媒体渠道 |
| c | te_ads_object.campaign_name | 广告计划名 |
| af_c_id | te_ads_object.campaign_id | 广告计划 ID |
| af_adset | te_ads_object.ad_group_name | 广告组名 |
| af_adset_id | te_ads_object.ad_group_id | 广告组 ID |
| af_ad | te_ads_object.ad_name | 广告名 |
| af_ad_id | te_ads_object.ad_id | 广告 ID |
| app_name | te_ads_object.app_name | 应用名 |
| app_id | te_ads_object.app_id | 应用 ID |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| currency | te_ads_object.currency | 成本或收益的币种 |
| geo | te_ads_object.country | 国家地区编码 |
| users | te_ads_object.installs | 转化量（安装） |
| cost | te_ads_object.cost | 投放成本 |