AppsFlyer Cohort API
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Cohort API | API | Aggregated metrics | ✅ | ✅ | ✅ |
The Cohort API is also an aggregated data API. Compared with other aggregated data APIs, its metrics are closer to the results of the Cohort Dashboard in AppsFlyer and the Retention Analysis model in the AE system, that is, day N (or cumulative day N) metrics of new users.
Integration process
- Log in to the AppsFlyer dashboard and get the V2.0 API Token and App ID
- Log in to the AE backend, go to the Third-party Integration module, add an AppsFlyer Cohort API plan, and complete the related configuration
- Check whether the AE system receives the data successfully, and build reports
1. Get the API Token and App ID
1.1 Get the API Token
Get the V2.0 API Token for the Cohort API
1.2 Get the App ID
You can find your app's App ID under My Apps in the AppsFlyer dashboard. On Android, it starts with com., such as com.demoapp.ta; on iOS, it starts with id, such as id12345678
2. Plan configuration
After getting the AppsFlyer API Token and App ID, log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the configuration page of AppsFlyer Cohort API. Follow this section to create the plan:
2.1 Authorization information configuration
Click the Configure authorization information button under Authorization Information, and enter the API Token and App ID in the pop-up
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull AppsFlyer Cohort API data on a schedule. You can choose to pull data for a period of time at a specific time every day, with up to 31 days per pull. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Receive Settings
You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.
2.4 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the data type, the dimensions to pull, and the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable |
source | metrics | Metric dimension in the data; list type; customizable, but you can enter only one, and it cannot be empty |
| group_by | Grouping dimensions in the data; list type; customizable | |
transfer | fields_whitelist | Field filter; list type. If the list is not empty, the AE system stores only the fields in the list and discards fields that are not in the list |
double_columns | Numeric field definitions. Fields entered here are stored as numeric types. Enter the field names after ingestion | |
| extra_params | aggregation_type | Whether the data is cumulative, that is, whether the returned day-N data is the data on day N or the cumulative data through day N. Default value: . Valid values: cumulative, on_day |
| partial_data | Whether to return data for incomplete dates. The default is false, that is, only data for complete days is returned. If set to true, up to 180 days of data, including incomplete days, is returned. Available only when aggregation_type is cumulative |
- Grouping dimensions
Note that the Cohort API supports up to 7 analysis dimensions. The following are the default analysis dimensions. To adjust them, modify source.group_by using the field names
| Field name | Ingested name | Default |
|---|---|---|
| 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 | ✓ |
Note that if you need to pull Facebook (Meta) data, do not select both af_channel and geo as analysis dimensions. Otherwise, Facebook cost data cannot be obtained
- Metric fields
Note that the Cohort API returns 3 default metrics and one metric specified in source.metrics (revenue by default). The following are the default metric fields.
| Field name | Metric name | Description | Default |
|---|---|---|---|
| users (default metric) | users | Total users in the cohort (independent of the time window) | ✓ |
| ecpi (default metric) | ecpi | Total eCPI of the cohort (independent of the time window) | ✓ |
| cost (default metric) | cost | Total cost of the cohort (independent of the time window) | ✓ |
"event_name" (use the name of the custom event) | "event_name"_unique_users_day_N | Users who triggered the custom event on day N | |
| "event_name"_count_day_N | Completions of the custom event on day N | ||
| "event_name"_rate_day_N | Completion rate of the custom event on day N | ||
| "event_name"_sum_day_N | Revenue generated by the custom event on day N | ||
revenue | revenue_count_day_N | Revenue events triggered on day N | ✓ |
| revenue_sum_day_N | Revenue on day N | ✓ | |
| roas | roas_rate_day_N | ROAS on day N | |
| roi | roi_rate_day_N | ROI on day N | |
sessions | sessions_unique_users_day_N | Users who triggered a session on day N (not returned for cumulative metrics) | |
| sessions_count_day_N | Sessions on day N | ||
| sessions_rate_day_N | Retention rate on day N (users who triggered a session / total users in the cohort) | ||
| uninstalls | uninstalls_count_day_N | Uninstalls on day N | |
| uninstalls_rate_day_N | Uninstall rate on day N |
2.5 Change the metrics to pull
Because the Cohort API returns a large number of fields, the project's properties may grow excessively and affect your normal use if you do not restrict which fields are stored. Therefore, to change the metrics to pull, do the following:
- Change source.metrics: enter the field name of the metric to pull, that is, the first column of the table in the previous section, in source.metrics. Note that you can enter only one metric in source.metrics, and the three metrics pulled by default, that is, users, ecpi, and cost, do not need to be written in source.metrics. As shown in the image below, to pull the uninstalls metric, enter "uninstalls" in source.metrics
- Change transfer.fields_whitelist: to prevent too many properties from being created, we designed transfer.fields_whitelist to filter fields. Only the fields written in it are stored. The data returned by the Cohort API is similar to our Retention Analysis model. By default, it returns days 0~30, 60, 90, 180, and so on, of a metric, such as revenue_count_day_7 and roi_rate_day_30. The default integration configuration filters out all fields except the group-by fields, revenue_count_day_0, and revenue_sum_day_0. To change the metrics, or to store data for more days, add the metric names of the metrics to store (see the table in the previous section) to transfer.fields_whitelist. As shown in the image below, after changing the metric to pull to uninstalls, you need to add metric names such as "uninstalls_count_day_0" and "uninstalls_rate_day_0" to transfer.fields_whitelist so that they can be stored.
- Add the metric names to transfer.double_columns: finally, so that the metric fields can be stored as numeric types, you also need to add the metric names added in the previous step to transfer.double_columns, as shown in the image below:
2.6 Data ingestion rules
By default, we write the pulled data to the AE project as events:
- The date field in the data, that is, the user's attribution/conversion time, is used as the event's #event_time
- The event name is appsflyer_cohort_api
- All fields that remain after filtering are stored. Fields entered in transfer.double_columns are stored as numeric types, and other fields are stored as text
2.7 Standardized fields
The following event properties are standardized:
| Original field | Standardized field | Description |
|---|---|---|
| pid | te_ads_object.media_source | Media source |
| c | te_ads_object.campaign_name | Campaign name |
| af_c_id | te_ads_object.campaign_id | Campaign ID |
| af_adset | te_ads_object.ad_group_name | Ad group name |
| af_adset_id | te_ads_object.ad_group_id | Ad group ID |
| af_ad | te_ads_object.ad_name | Ad name |
| af_ad_id | te_ads_object.ad_id | Ad ID |
| app_name | te_ads_object.app_name | App name |
| app_id | te_ads_object.app_id | App ID |
| platform | te_ads_object.platform | Platform, such as Android or iOS |
| currency | te_ads_object.currency | Currency of the cost or revenue |
| geo | te_ads_object.country | Country or region code |
| users | te_ads_object.installs | Conversions (installs) |
| cost | te_ads_object.cost | Campaign cost |