# AppsFlyer Cohort API

# 概要

接口名	类型	粒度	归因	成本	收益	展示	点击	转化
Cohort API	API	聚合指标		✅	✅			✅

Cohort API (opens new window) 同样也是聚合数据 API。相比其他聚合数据 API，数据指标的形态更类似于 AppsFlyer 的 Cohort Dashboard 以及 TE 系统的留存分析模型的数据结果，即新增用户的第 N 日（或累计第 N 日）指标。

请您登录管理员账号，并在 AppsFlyer 侧边栏菜单中找到「API Access」，并且获取用于 Cohort API 的 V2.0 API Token。

可以在 AppsFlyer 后台「My Apps」找到您的应用的 App ID，安卓端以com.开头，如 com.demoapp.ta，iOS 以id开头，如id12345678

获取完 AppsFlyer 的 API Token 与 App ID 之后，您可以登录 TE 系统，在「三方集成」模块中完成新方案的配置。下图是 AppsFlyer Cohort API 的配置界面，请您按照本章节内容完成方案的创建：

点击「授权信息」按钮，在弹出框内填写 API Token 与 App ID

您可以在「定时拉取」模块设置 TE 系统定时拉取 AppsFlyer Cohort API 数据的策略，可以选择在每天的某时拉取一段时间的数据。由于拉取的数据也会计算再数据量中，建议您在不要定时拉取太长时间的数据

您可以控制数据是否以事件的形式写入，如果关闭，则数据将不会写入事件表，因此请不要关闭该配置。

最后，您可以在集成配置模块对数据拉取的细节配置进行控制。包括数据的类型，拉取的维度，以及入库后的事件名等。

集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：

模块	名称	含义
sink_event	event_name	入库后的事件名，可以自定义
source	metrics	数据中的指标维度，列表类型，可以自定义，但只可填写一个，且不可为空
source	group_by	数据中的分组维度，列表类型，可以自定义
transfer	fields_whitelist	字段过滤，列表类型，如果列表不为空，则 TE 系统只会入库列表中的字段，不在列表中的字段会被抛弃
transfer	double_columns	数值类型字段定义，写在此处的字段将会以数值类型入库，需填写入库后的字段名
extra_params	aggregation_type	是否累计数据，即返回的 N 日数据时第 N 日数据还是累计第 N 日数据，默认值为：，可选 `cumulative`、`on_day`
extra_params	partial_data	是否返回缺省日期的数据，默认为 false，即只返回完整天的数据。设置为 true，则包含不完整日的最多 180 天的数据会返回

- 分组维度

需要注意的是，Cohort API 最多支持 7 个分析维度，以下是默认的分析维度，如果需要调整，可以修改 source.group_by，调整时请使用字段名

::: tip 请注意，如果您需要拉取 Facebook(Meta) 的数据，则分析维度请不要同时选择 af_channel 与 geo，否则将无法获取 Facebook 的成本数据 :::

需要注意的是，Cohort API 会返回 3 个默认指标以及一个额外指标，以下是默认的指标字段。

字段名	指标名	描述	默认
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	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	uninstalls_rate_day_N	第 N 日卸载率

由于 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 中将上一步中添加的指标名。如下图所示：

默认情况下，我们会将拉取的数据以事件形式写入 TE 项目中：

以下事件属性会进行标准化处理：