AppsFlyer data integration solution

Last updated 10/05/2026

Last updated: 2023-04-04

1. Integration plan overview

tip

Note that data generated by third-party data integration counts toward the cluster's data consumption

Summary

This document describes how to send AppsFlyer data back to Agentic Engine (hereinafter the AE system). This solution supports multiple AppsFlyer data integration methods. The following table shows the features and data types of each method. You can click a name to jump to the corresponding section:

Interface	Data granularity	API type	Productized	Data update frequency	Request limits
Push API user data	User level	Push	Yes	Real time	No limit
Pull API user-level data API	User level	Pull	No	Real time	Up to 1M rows per request Up to 24 requests per app per day Up to 120 requests per account per day
Pull API aggregated data	Aggregated data	Pull	No	Real time	Up to 1 request per minute Pull time range within 0-2 days: no limit Pull time range of 3 days or more: Up to 24 requests per app per day Up to 120 requests per account per day
Master API	Aggregated data	Pull	No	By day	No row limit per request No limit on daily requests
Cohort API	Aggregated data	Pull	No	By day	No limit
Data Locker	User level / aggregated data	Pull	-	By day/hour	Subject to the limits of the cloud storage used for the export

warning

Note that some platforms restrict some fields of user-level data from being sent back, including attribution information, revenue data, and cost data

tip

Some of the APIs are paid AppsFlyer features. Before you use them, ask your account manager at AppsFlyer about your access to these APIs.

2. Push API user-level data API (productized)

Basic interface information

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Push API	Push	Yes	User level	Yes		Yes	Yes	Yes	Yes

Push API gets AppsFlyer user-level data in real time, including impression, click, install, and revenue data. Cost data may not be available because of data restrictions on the AF platform.

tip

Note that Push API integration has been productized in the AE system backend. We recommend that you follow the related product documentation and configure the integration in the UI.

Before you connect Push API user-level data, make sure you have read the AE system user identification rules and understand how the AE system identifies a user through #distinct_id and #account_id. The data integration process of the AppsFlyer Push API is shown in the image below:

View original image

2.1 Configure the client SDK

To connect Push API user-level data with the user data of the AE project, you need to report the account ID and distinct ID of the AE project in the AppsFlyer SDK. The following describes how to configure the client SDK.

Option 1 (automatic integration):

tip

If the AE SDK version you integrated is 2.8.0~2.8.1, you can use this option directly

If the AE SDK version you integrate is 2.8.2 or later, you also need to install the third-party data plugin

This option is an automatic integration. After you initialize the AE client SDK, call the following code to enable it. For details, see Android SDK third-party data and iOS SDK third-party data

// Initialize the AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);

// Enable AppsFlyer ID association in the AE SDK
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

// We strongly recommend that you use setCustomerUserId() to set the distinct ID again
String distinctId = instance.getDistinctId();
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);

// Initialize the AppsFlyer SDK
AppsFlyerLib.getInstance().init("appid", null, this);
AppsFlyerLib.getInstance().start(this);

// After calling login in the AE SDK to set the account ID, sync the data to the AF SDK again
instance.login("account_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

If you call the login() or identify() method of the AE SDK, call enableThirdPartySharing() again to sync the data.

Note: If you also need to call the setAdditionalData() method of the AppsFlyer SDK, calling it multiple times overwrites the previous parameters. In this case, you can pass the parameters to the AE SDK, which concatenates and merges them internally.

Map<String, Object> additionalData = new HashMap<>();
additionalData.put("af_test_key1", "test1");
additionalData.put("af_test_key2", "test2");
instance.enableThirdPartySharing(
    TDThirdPartyShareType.TD_APPS_FLYER,
    additionalData
);

This option works by automatically calling AppsFlyer's setAdditionalData() method internally and passing in the distinct ID and account ID of the AE project.

Option 2 (manual integration):

For manual integration, you need to use setAdditionalData in the AppsFlyer SDK to configure the distinct ID and account ID of the AE project. The following is a Java code sample:

// Initialize the AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);

// Get the AE distinct ID, which corresponds to #distinct_id in AE
String distinctId = instance.getDistinctId();

// Set the distinct ID in the AF SDK through setAdditionalData()
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id",distinctId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

// We strongly recommend that you use setCustomerUserId() to set the distinct ID again
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);

// Initialize the AppsFlyer SDK
AppsFlyerLib.getInstance().init("appid", null, this);
AppsFlyerLib.getInstance().start(this);
...

// After calling login in the AE SDK to set the account ID, sync the data to the AF SDK again
String accountId = "your_account_id";
instance.login(accountId);
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id", distinctId);
CustomDataMap.put("ta_account_id",accountId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

After these settings, custom_data in the returned data carries the two fields ta_distinct_id and ta_account_id, and customer_user_id equals the distinct ID.

Note: If you use the productized configuration method to connect AppsFlyer Push API data, enter the following in the association fields:

• Account ID association field: custom_data.ta_account_id
• Distinct ID association field: customer_user_id,custom_data.ta_distinct_id

2.2 Configure the callback URL

Next, log in to the AppsFlyer dashboard with an admin account, find the Push API section under Integration - API Access, and set the callback URL as follows:

• Push API Version

  • Select version 2.0

• HTTP method

  • The AE system supports both POST and GET callbacks. We recommend POST

• Endpoint URL

  • ThinkingAI staff will provide you with the endpoint address for receiving data

• Event Messages

  • You need to select at least Install and Install in-app events. If you have other event data to send back, select it as needed

• Message Fields

  • The message fields must include at least the following:

    • Mobile attribution fields: media_source, channel, af_adset, af_ad, and so on
    • User identification ID fields: custom_data, customer_user_id, event_value, and so on
    • Fields to use as event properties or user properties
    • Event fields: event_time_selected_timezone

• In-app events

  • Select the events to send back as needed, such as the ta_registration event reported by the client

warning

Note that if you need Facebook data, you must accept the Facebook data use agreement (Terms of Service) in the Facebook channel settings in the AF dashboard. Otherwise, you can't get Facebook user-level data.

2.3 Data ingestion

2.3.1 User identification rules

Based on the logic of the user identification fields you set in the client SDK earlier, you need to determine the corresponding user identification rules so that the user-level data sent back by Push API can be associated with the corresponding users in the AE project.

By default, we look for user identification fields in the callback data according to the following rules:

• Step 1: Check whether the custom_data field contains ta_account_id / ta_distinct_id, that is, the fields set by setAdditionalData()
• Step 2: Check whether the event_value field contains ta_account_id / ta_distinct_id, that is, the fields set in AppsFlyer custom events
• Step 3: If the event is an Install event (event_name: install), check the customer_user_id field. If it exists, customer_user_id is used as #distinct_id, that is, the field set by setCustomerUserId()

At each step, if any valid ID is obtained, the remaining steps are skipped. If no valid user ID is obtained after all 3 steps, by default the record is treated as invalid and discarded. If you want to keep this data, contact ThinkingAI staff to configure it. This data is then recorded in the event table with the fixed distinct ID "without_id", and no user properties are stored for it

If the user identification fields you set differ from the above, note them in the data integration configuration template.

2.3.2 Data ingestion rules

By default, the data sent back is not written as event data. If you need it written as event data, all received events are written as event data. The following are the ingestion rules for event data:

• Event data is attributed to the corresponding AE user based on the user identification rules
• The time and time zone are taken from the event_time_selected_timezone field in the data: the time is used as #event_time, and the time zone is written as #zone_offset. If this field is empty, event_time is used as #event_time, and the time zone #zone_offset is set to 0
• The event name of the data is the event's name in AppsFlyer
• All other fields are stored

2.3.3 User property ingestion settings

By default, we read the values of the following four fields from the data and set them as user properties:

AppsFlyer field	AE standardized field	Description
media_source	te_ads_object.media_source	Channel
campaign	te_ads_object.campaign_name	Campaign
af_adset	te_ads_object.ad_group_name	Ad group
af_ad	te_ads_object.ad_name	Ad

In addition, you can customize the user properties to ingest, including their ingestion rules (that is, whether to use user_set or user_setOnce). If you need to customize user properties, note them in the data integration configuration template.

2.4 Data integration configuration template

After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:

Interface: AppsFlyer Push API
--------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
User identification rule: XXX as the distinct ID/account ID (leave blank to use the default)
Ingest events: No/Yes
Keep data without a user identification ID: No/Yes (takes effect only when events are ingested)
Ingested user properties: XXX, XXX (leave blank to use the default)

3. Pull API user-level data

Basic interface information

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Pull API Raw Data	Pull	No	User level	Yes	Yes	Yes			Yes

Pull API Raw Data is a pull-based user-level data API that is well suited to pulling historical user-level data.

3.1 Before you begin

3.1.1 Get the API Token

Log in with an admin account, find API Access in the AppsFlyer sidebar menu, and get the V2.0 API token for Pull API Raw Data.

3.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

3.1.3 Configure the client SDK

To connect Pull API user-level data with the user data of the AE project, you need to report the account ID and distinct ID of the AE project in the AppsFlyer SDK. The following describes how to configure the client SDK.

Option 1 (automatic integration):

tip

If the AE SDK version you integrated is 2.8.0~2.8.1, you can use this option directly

If the AE SDK version you integrate is 2.8.2 or later, you also need to install the third-party data plugin

This option is an automatic integration. After you initialize the AE client SDK, call the following code to enable it. For details, see Android SDK third-party data and iOS SDK third-party data

// Initialize the AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// Enable AppsFlyer ID association
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

// Initialize the AppsFlyer SDK
AppsFlyerLib.getInstance().init("appid", null, this);
AppsFlyerLib.getInstance().start(this);

// We strongly recommend that you use setCustomerUserId() to set the distinct ID again
String distinctId = instance.getDistinctId();
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);

// After calling login to set the account ID, sync the data again (optional)
instance.login("account_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_APPS_FLYER);

If you call the login() or identify() method of the AE SDK, call enableThirdPartySharing() again to sync the data.

Note: If you also need to call the setAdditionalData() method of the AppsFlyer SDK, calling it multiple times overwrites the previous parameters. In this case, you can pass the parameters to the AE SDK, which concatenates and merges them internally.

Map<String, Object> additionalData = new HashMap<>();
additionalData.put("af_test_key1", "test1");
additionalData.put("af_test_key2", "test2");
instance.enableThirdPartySharing(
    TDThirdPartyShareType.TD_APPS_FLYER,
    additionalData
);

This option works by automatically calling AppsFlyer's setAdditionalData() method internally and passing in the distinct ID and account ID of the AE project.

Option 2 (manual integration):

For manual integration, you need to use setAdditionalData in the AppsFlyer SDK to configure the distinct ID and account ID of the AE project. The following is a Java code sample:

// Initialize the AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);

// Get the AE distinct ID, which corresponds to #distinct_id in AE
String distinctId = instance.getDistinctId();
// Your account ID (or character ID), which corresponds to #account_id in AE
String accountId = "your_account_id";

// Deploy at install
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id",distinctId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

// We strongly recommend that you use setCustomerUserId() to set the distinct ID again
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);
...

// Deploy at registration
HashMap<String,Object> CustomDataMap = new HashMap<>();
CustomDataMap.put("ta_distinct_id", distinctId);
CustomDataMap.put("ta_account_id",accountId);
AppsFlyerLib.getInstance().setAdditionalData(CustomDataMap);

After these settings, custom_data in the returned data carries the two fields ta_distinct_id and ta_account_id, and customer_user_id equals the distinct ID.

3.2 Included fields

By default, Pull API Raw Data supports pulling the following data:

Field	Display name	Retrieved by default	Type
Attributed Touch Type	Attribution type (impression, click)	Yes
Attributed Touch Time	Attribution time	Yes	Time
Install Time	Activation time	Yes	Time
Event Time	Event time	Yes	Time
Event Name	Event name	Yes
Event Value	Event value	Yes
Event Revenue	Event revenue	Yes	Numeric
Event Revenue Currency	Event revenue currency	Yes
Event Revenue USD	Event revenue (USD)	Yes	Numeric
Event Source	Event source	Yes
Is Receipt Validated	Whether receipt validation is enabled
Partner	Partner	Yes
Media Source	Media source	Yes
Channel	Sub-channel	Yes
Keywords	Keywords	Yes
Campaign	Campaign name	Yes
Campaign ID	Campaign ID	Yes
Adset	Ad group name	Yes
Adset ID	Ad group ID	Yes
Ad	Ad creative name	Yes
Ad ID	Ad creative ID	Yes
Ad Type	Ad type	Yes
Site ID	Site ID	Yes
Sub Site ID	Sub-site ID	Yes
Sub Param [1-5]	Sub-parameter [1-5]
Cost Model	Cost model (CPC/CPI/CPM/Other)	Yes
Cost Value	Cost value	Yes	Numeric
Cost Currency	Cost currency	Yes
Contributor [1-3] Partner	Contributor [1-3] partner
Contributor [1-3] Media Source	Contributor [1-3] media source
Contributor [1-3] Campaign	Contributor [1-3] campaign
Contributor [1-3] Touch Type	Contributor [1-3] attribution type
Contributor [1-3] Touch Time	Contributor [1-3] attribution time		Time
Region	Region	Yes
Country Code	Country code	Yes
State	State/Province	Yes
City	City	Yes
Postal Code	Postal code
DMA	DMA code
IP	IP address	Yes
WIFI	Whether Wi-Fi is on	Yes
Operator	Mobile operator	Yes
Carrier	Mobile carrier	Yes
Language	Language	Yes
AppsFlyer ID	AppsFlyer ID	Yes
Advertising ID	Advertising ID	Yes
IDFA	IDFA	Yes
Android ID	Android ID	Yes
Customer User ID	Customer User ID	Yes
IMEI	IMEI	Yes
IDFV	IDFV	Yes
Platform	Platform	Yes
Device Type	Device Type	Yes
OS Version	OS	Yes
App Version	App version	Yes
SDK Version	SDK version	Yes
App ID	App ID	Yes
App Name	App name	Yes
Bundle ID	Bundle ID	Yes
Is Retargeting	Is retargeting	Yes
Retargeting Conversion Type	Retargeting conversion type	Yes
Attribution Lookback	Attribution lookback
Reengagement Window	Re-engagement window
Is Primary Attribution	Is primary attribution
User Agent	User agent
HTTP Referrer	HTTP Referrer
Original URL	Original URL	Yes

3.3 API parameters

• Time:

  • Data is pulled by day (only data from the last 90 days can be pulled)
  • The default time zone of the data is UTC

3.4 Data ingestion rules

The Pull API user-level data API ingests several types of data. The processing rules for each type are as follows:

• Installs data

  • Pulls Installs data that contains only user acquisition (UA), and Organic Installs data
  • Data is written as user properties by default
  • Data can also be written as events, with the event name af_install
  • User identification fields are determined by the user identification field configuration. If no user identification rule is configured, customer_user_id in the data is used as the distinct ID by default. If no user identification field is found, the record is discarded.
  • All fields are ingested

• Ad Revenue

  • Pulls Attributed ad revenue and Organic ad revenue. Attributed ad revenue pulls both user acquisition (UA) and retargeting data
  • Data is written as events with the event name af_ad_revenue_raw
  • The Event Time in the data, that is, the time the event occurred, is used as the event's #event_time
  • User identification fields are determined by the user identification field configuration. If no user identification rule is configured, customer_user_id in the data is used as the distinct ID by default. If no user identification field is found, the record is discarded.
  • All fields are ingested

3.5 Data integration configuration template

After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:

Interface: AppsFlyer Pull API Raw Data
--------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
User identification rule: XXX as the distinct ID/account ID (leave blank to use the default)
Data to connect: Install, Ad Revenue
Install event properties to write to user properties: xxx, xxx (leave blank to use the default) 

Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd (only data from the last 90 days can be pulled)
Scheduled pull: pull the previous day's data at X:00 every day

4. Pull API aggregated metrics API

Basic interface information

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Pull API aggregated metrics	Pull	No	Aggregated data		Yes	Yes	Yes	Yes	Yes

The AppsFlyer Pull API aggregated metrics API provides different types of aggregated metric data. The AE system currently supports the Partners (by date) and Geo (by date) data types.

4.1 Before you begin

4.1.1 Get the API Token

Log in with an admin account, find API Access in the AppsFlyer sidebar menu, and get the V2.0 API token for Pull API.

4.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

4.2 Included fields

4.2.1 Partner (by date) data

This section describes data of the Partner (by date) type. This report is based on LTV data, that is, it pulls the subsequent data of new users who installed within the specified time period.

Because Facebook's data format differs from that of other media sources, the AE system pulls Facebook-only data and data from all platforms separately. The following fields are available from Partner (by date):

Field name	Ingested name	Facebook data only	All-platform data
Date	#event_time	✓	✓
Agency/PMD (af_prt)	agency_pmd_af_prt	✓	✓
Media Source (pid)	media_source_pid	✓	✓
Campaign	campaign_name (Facebook) campaign_c (all platforms)	✓	✓
Campaign ID	campaign_id	✓
Adgroup ID	adgroup_id	✓
Adgroup Name	adgroup_name	✓
Adset ID	adset_id	✓
Adset Name	adset_name	✓
ARPU	arpu	✓	✓
Average eCPI	average_ecpi	✓	✓
Clicks	clicks	✓	✓
Conversion Rate	conversion_rate	✓	✓
CTR	ctr	✓	✓
{your event name}(Unique users)	{your_event_name}_unique_users	✓	✓
{your event name} (Event counter)	{your_event_name}_event_counter	✓	✓
{your event name} (Sales in XXX)	{your_event_name}_sales_in_usd	✓	✓
Impressions	impressions	✓	✓
Installs	installs	✓	✓
Loyal Users	loyal_users	✓	✓
Loyal Users/Installs	loyal_users_installs	✓	✓
ROI	roi	✓	✓
Sessions	sessions	✓	✓
Total Cost	total_cost	✓	✓
Total revenue	total_revenue	✓	✓

4.2.2 Geo (by date) data

This section describes data of the Geo (by date) type. This report is based on LTV data, that is, it pulls the subsequent data of new users who installed within the specified time period.

Because Facebook's data format differs from that of other media sources, the AE system pulls Facebook-only data and data from all platforms separately. The following fields are available from Geo (by date):

Field name	Ingested name	Facebook data only	All-platform data
Country	country	✓	✓
Date	#event_time	✓	✓
Agency/PMD (af_prt)	agency_pmd_af_prt	✓	✓
Media Source (pid)	media_source_pid	✓	✓
Campaign	campaign_name (Facebook) campaign_c (all platforms)	✓	✓
Campaign ID	campaign_id	✓
Adgroup	adgroup_id	✓
Adgroup Name	adgroup_name	✓
Adset ID	adset_id	✓
Adset Name	adset_name	✓
ARPU	arpu	✓	✓
Clicks	clicks	✓	✓
Conversion Rate	conversion_rate	✓	✓
{your event name}(Unique users)	{your_event_name}_unique_users	✓	✓
{your event name} (Event counter)	{your_event_name}_event_counter	✓	✓
{your event name} (Sales in XXX)	{your_event_name}_sales_in_usd	✓	✓
Installs	installs	✓	✓
Loyal Users	loyal_users	✓	✓
Sessions	sessions	✓	✓
Total revenue	total_revenue	✓	✓

4.3 API parameters

• Time:

  • Data is pulled by day
  • The default time zone of the data is UTC

4.4 Data ingestion rules

By default, we write the pulled data to the AE project as events:

• Because the Pull API aggregated metrics API returns aggregated data, we use a fixed value as the user identifier. You can think of all the data as attached to one virtual user

• The Date field in the data, that is, the user's install date, is used as the event's #event_time

• The event names in the data are:

  • Partner (by date)

    • appsflyer_facebook_partner_by_date (Facebook data)
    • appsflyer_partner_by_date (all-platform data)

  • Geo (by date)

    • appsflyer_facebook_geo_by_date (Facebook data)
    • appsflyer_geo_by_date (all-platform data)

• All other fields are ingested

4.5 Data integration configuration template

After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:

Interface: AppsFlyer Pull API aggregated data API
--------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
Data pull time zone: XXX (UTC by default)
Data pull type: Partner (by date)/Geo (by date)

Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Scheduled pull: pull the previous day's data at X:00 every day

5. Master API

Basic interface information

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Master API	Pull	No	Aggregated data		Yes	Yes	Yes	Yes

Master API supports custom analysis dimensions and aggregated metrics, and is more flexible than the Pull API aggregated metrics API.

5.1 Before you begin

5.1.1 Get the API Token

Log in with an admin account, find API Access in the AppsFlyer sidebar menu, and get the V2.0 API token for Master API.

5.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

5.2 Included fields

Master API includes many types of metrics. The commonly used metric categories are LTV KPIs, Retention KPIs, and Cohort KPIs. Because Cohort KPIs support fewer analysis dimensions than the other metric categories, the AE system pulls data with and without Cohort KPIs separately. The following are the fields covered by these two types of data:

• Analysis dimensions

Field name	af_groupings	Ingested name	Excluding Cohort KPIs data	Including Cohort KPIs data
App ID	app_id	app_id	✓	✓
Media Source	pid	media_source	✓	✓
Agency	af_prt	partner	✓
Campaign	c	campaign	✓	✓
Adset	af_adset	adset	✓
Ad	af_ad	ad	✓
Channel	af_channel	channel	✓
Publisher ID	af_siteid	publisher_id_af_siteid	✓	✓
Keywords	af_keywords	keywords
Is Primary Attribution	is_primary	is_primary_attribution
Campaign ID	af_c_id	campaign_id
Adset ID	af_adset_id	adset_id
Ad ID	af_ad_id	ad_id
Install Time	install_time	install_time	✓	✓
Touch Type	attributed_touch_type	touch_type	✓
GEO	geo	geo	✓	✓

• Metric fields

The following lists some commonly used fields of Master API. For the full list of fields, see the AppsFlyer documentation:

tip

New metric fields are added to Excluding Cohort KPIs data. To add metrics, specify them in the data integration configuration template

Ingested name	Description	Excluding Cohort KPIs data	Including Cohort KPIs data
impressions	Impressions	✓	✓
clicks	Clicks	✓	✓
installs	Installs	✓	✓
cr	Conversion rate	✓	✓
sessions	Sessions	✓	✓
loyal_users	Loyal user installs	✓	✓
loyal_users_rate	Loyal user rate	✓	✓
cost	Total cost	✓	✓
revenue	Total revenue	✓	✓
roi	ROI	✓	✓
arpu_ltv	Average lifetime value	✓	✓
average_ecpi	Average eCPI	✓	✓
uninstalls	Uninstalls	✓	✓
uninstalls_rate	Uninstall rate	✓	✓
retention_day_[x]	Retained users on day N (N = 0,1,2,3,4,5,6,7,15,30)	✓
retention_rate_day_[x]	Retention rate on day N (N = 0,1,2,3,4,5,6,7,15,30)	✓
cohort_day_[x]_total_revenue_per_user	Cumulative revenue on day N (N = 1,2,3,4,5,6,7,15,30,40,50,60,70,80,90)		✓
cohort_day_[x]_revenue_per_user	Same-day revenue on day N (N = 1,2,3,4,5,6,7,15,30,40,50,60,70,80,90)		✓
cohort_[x]_days_total_revenue_per_user	Same as cumulative revenue on day N (N = 1,2,3,4,5,6,7,15,30,40,50,60,70,80,90)		✓

5.3 API parameters

• Time:

  • Data is pulled by day
  • The default time zone of the data is UTC

5.4 Data ingestion rules

By default, we write the pulled data to the AE project as events:

• Because the Master API aggregated metrics API returns aggregated data, we use a fixed value as the user identifier. You can think of all the data as attached to one virtual user

• The install_time field in the data, that is, the user's install time, is used as the event's #event_time

• The event names in the data are:

  • Including Cohort KPIs data
    • appsflyer_master_ltv_act_cohort_kpis
  • Excluding Cohort KPIs data
    • appsflyer_master_ltv_act_retention_kpis

• All other fields are ingested

5.5 Data integration configuration template

After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:

Data pull interface: AppsFlyer Master API aggregated data API
--------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
Data pull time zone: XXX (UTC by default)
New metrics: XXX, XXX (for event-related activity metrics, you can specify the names of the events whose metric data to pull; new metrics are added to the Excluding Cohort KPIs data, that is, the appsflyer_master_ltv_act_retention_kpis event)

Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Scheduled pull: pull the previous day's data at X:00 every day

6. Cohort API

Basic interface information

Interface	API type	Productized	Data granularity	Attribution	Cost	Revenue	Impressions	Clicks	Conversions
Cohort API	Pull	No	Aggregated data		Yes	Yes			Yes

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.

6.1 Before you begin

6.1.1 Get the API Token

Log in with an admin account, find API Access in the AppsFlyer sidebar menu, and get the V2.0 API token for Cohort API.

6.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

6.2 Included fields

• Analysis dimensions

Note that the Cohort API supports up to 7 analysis dimensions. The following are the default analysis dimensions. To change them, specify the changes in the data integration configuration template:

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 (1)	cohort_type
Site ID	site_id
Attributed Touch Type (3)	attributed_touch_type
Adset	af_adset	✓
Adset ID	af_adset_id
Country	geo
Date	date	✓

warning

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 types of default metrics and one additional metric. The following are the default metric fields. To change them, specify the changes in the data integration configuration template:

Metric type	Ingested name	Description	Default
users (always returned)	users	Total users in the cohort (independent of the time window)	✓
ecpi (always returned)	ecpi	Total eCPI of the cohort (independent of the time window)	✓
cost (always returned)	cost	Total cost of the cohort (independent of the time window)	✓
"event_name" (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

Note: In the table above, N in the ingested name column represents the day-N metric. The default value range is 0-30

6.3 API parameters

• Time:

  • Data is pulled by day
  • The default time zone of the data is UTC
  • You can choose whether the data is independent for each day (that is, it shows the metrics of that day) or cumulative (that is, accumulated from day 0 to day N)
  • You can choose whether to allow data for incomplete days (for example, when the calculated day N is today) to be sent back

6.4 Data ingestion rules

By default, we write the pulled data to the AE project as events:

• Because the Cohort API aggregated metrics API returns aggregated data, we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
• 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 other fields are ingested

6.5 Data integration configuration template

After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:

Data pull interface: AppsFlyer Cohort API aggregated data API
--------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
AppsFlyer API Token: xxxxxxxx
AppsFlyer App ID: xxxxxxxx
---------
Data pull time zone: XXX (UTC by default)
Allow data for incomplete days: Yes/No (default: "Yes")
Time aggregation type of the data: Same day/Cumulative (default: cumulative)

Group-by dimensions: XXX, XXX (default: date,pid,geo,c,af_adset,af_ad,af_channel)
Metric field: XXX (default: revenue; only one can be set)

Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Scheduled pull: pull the data of the previous N days at X:00 every day

7. Data Locker and Cost ETL

Data Locker is AppsFlyer's data export service. It can export multiple types of data to AWS or GCS cloud storage.

Cost ETL is AppsFlyer's cost data export service. It can export campaign cost data from each media source to AWS or GCS cloud storage.

The AE system currently supports integrating data from AWS S3 and GCS. Depending on the type of cloud storage you export to, see the following documents:

• AWS S3
  • DataX integration for S3 data: use the DataX plugin to connect the data
• GCS
  • Firebase-Bigquery-GCS data migration technical solution: clean the data and transfer it to the AE system through code (the GCS library). See sections 2.2.2 and 2.2.3 of that document

8. Integration testing and data usage after integration

1. Integration testing

1.1 Push API

You can view the related attribution data on the Management > User properties page. If the related user properties exist, the integration is successful.

AppsFlyer callback field	User property name in AE	Data type
media_source	#appsflyer_media_source	Text
campaign	#appsflyer_campaign	Text
af_adset	#appsflyer_adset	Text
af_ad	#appsflyer_ad	Text

If you have enabled event table ingestion, view the related event data on the Management > Events page. The event names are the same as those defined in AppsFlyer.

1.2 Pull API and Master API aggregated data APIs

You can view the related events on the Management > Events page. If the related events exist, the integration is successful.

Interface	Report name	Event name in AE	Data type
Pull API	Delivery report for all media sources - daily	appsflyer_partner_by_date	Text
Pull API	Facebook delivery report - daily	appsflyer_facebook_partner_by_date	Text
Master API	LTV, Activity, and Retention KPIs	appsflyer_master_ltv_act_retention_kpis	Text
Master API	LTV, Activity, and Retention plus Cohort KPIs	appsflyer_master_ltv_act_retention_cohort_kpis	Text

2. Data usage

2.1 Analysis based on attribution information

2.2 Compare installs, cost, revenue, and ROAS across media by channel, ad group, campaign, and ad creative

2.3 View marketing data and user behavior data on one platform, with less switching between platforms

2.4 Linked data analysis, such as connecting with monetization data and data from other media sources

2.5 Calculate the ROAS of different media sources through revenue / cost

2.6 Analyze the quality of non-organic users through their key behaviors (such as an event before payment, like retention in a core gameplay feature), shortening the time from analysis to decision

2.7 Data types of event properties after integration

For data pulled through the AppsFlyer Pull API, event properties are ingested as strings by default. You can use the custom property feature of the AE system to convert string fields to other types, for example:

• Convert the install property to a numeric type: "af_install_number" (select numeric as the data type)
• Convert the total_cost property to a numeric type: "af_total_cost_number" (select numeric as the data type)

9. FAQ

See the AppsFlyer FAQ