Skip to main content

AppsFlyer Push API

Last updated 10/05/2026
tip

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

Summary​

Interface overview​

InterfaceTypeGranularityAttributionCostRevenueImpressionsClicksConversions
Push APICallbackUser level✅✅✅✅✅

Push API provides real-time AppsFlyer user-level data, including ad impression, click, install, and revenue data. Cost data may not be available due to AF platform data restrictions.

Before you start connecting AF data, make sure you have read the AE system user identification rules and understand how AE identifies a user by #distinct_id and #account_id

Integration process​

  1. Integrate the AppsFlyer client SDK and the AE SDK, and set the AE user identification ID in the AF SDK
  2. Log in to the AE backend, go to the Third-party Integration module, add an AppsFlyer Push API plan, and complete the related configuration
  3. Log in to the AppsFlyer dashboard and complete the callback configuration
  4. Check whether the AE system receives the data successfully, and build reports

1. Client SDK configuration​

The first step in integrating AppsFlyer data is to connect the AE SDK and the AF SDK on the client by setting the AE system's user identification ID in the AF SDK

1.1 Option 1 (automatic integration)​

  • If you integrate the Android or iOS SDK:

  • If you integrate Unity SDK 2.4.0 or later, or Unreal SDK 1.5.0 or later, you can use this option directly

tip

Note that the AE SDK initialization and the code that enables automatic integration must run before the AppsFlyer SDK is initialized. Follow these steps:

1. Initialize the AE SDK.

2. Call `enableThirdPartySharing` to set the distinct ID automatically.

3. Initialize the AppsFlyer SDK.

The following are code samples for the SDK on each platform:

// 1. Initialize the Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. Call the enableThirdPartySharing API to set ta_distinct_id in appsflyer events
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPS_FLYER);
// 3. We strongly recommend that you use setCustomerUserId() to set the distinct ID again
String distinctId = TDAnalytics.getDistinctId();
AppsFlyerLib.getInstance().setCustomerUserId(distinctId);
// 4. Initialize the Appsflyer SDK
//  ...
// 5. After registration or character creation, call login to set the account ID, then sync the data again (optional)
TDAnalytics.login("account_id");
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.APPS_FLYER);
tip

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

If you also need to call the setAdditionalData() method of the AF SDK, calling it multiple times overwrites the previous parameters. In this case, you can use the following code to pass the parameters to the AE SDK, which concatenates and merges them internally. The following code is an Android SDK integration sample.

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 AF's setAdditionalData() method internally and passing in the distinct ID and account ID of the AE project.

1.2 Option 2 (manual integration)​

For manual integration, you need to use the setAdditionalData() API in the AF SDK to set the distinct ID and account ID of the AE project.

tip

Note that the AE SDK initialization and the setAdditionalData call must be completed before the AF SDK is initialized. Follow these steps:

1. Initialize the AE SDK.

2. Call `setAdditionalData` to set the distinct ID.

3. Initialize the AF SDK.

The following are manual integration code samples for the SDK on each platform:

// 1. Initialize the Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. Get the AE distinct ID, which corresponds to #distinct_id in AE
String distinctId = TDAnalytics.getDistinctId();

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

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

// 5. Initialize the AppsFlyer SDK
...

// 6. After registration or character creation, call login to set the account ID, then sync the data again (optional)
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.

2. Plan configuration​

After completing the SDK configuration, log in to the AE system backend and configure AppsFlyer in the Third-party Integration module. The image below shows the AppsFlyer configuration page:

2.1 User identification fields​

Because AppsFlyer sends back user-level data, you need to set user identification rules for it, that is, the fields in the AF callback data that correspond to #distinct_id and #account_id. Based on this configuration, the AE system sets these fields as the user identification fields of the data when it converts the callback data.

If you configured the client SDK as described in the previous step of this document, use the following configuration:

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

2.2 Event Data Configuration​

After you turn on the Event Data Configuration switch, the data sent back (including activation events and in-app events) is written to the event table

We recommend that you enable event data ingestion. Note, however, that by default we receive all data sent back by AF. If too many event types are sent back, the event volume of the AE project grows excessively. Therefore, when you set up callbacks on the AF platform, we recommend that you select only the necessary events.

2.3 User Properties Configuration​

By default, the AE system automatically writes the attribution fields in the data returned by AF to standardized user properties. The following are the fields written to user properties and their meanings:

AppsFlyer fieldStandardized fieldDescription
media_sourcete_ads_object.media_sourceMedia source
campaignte_ads_object.campaign_nameCampaign name
af_adsette_ads_object.ad_group_nameAd group name
af_adte_ads_object.ad_nameAd name
tip

The default user property ingestion rules in earlier versions differ from the current ones, so be careful to distinguish them. To merge the old and new properties, you can use the custom property feature

To make changes, click Configure Rules to go to the ingestion rule configuration page, as shown below

Here, you can change which events user properties come from. If you don't want user properties to be written frequently, turn off Include all events and change Source event name to install. With this configuration, the AE system extracts the fields to write to user properties only from the install events sent back by AF. Integration method defaults to user_setOnce, which keeps only the first reported information.

Click the Property Mapping button to add fields to write to user properties. You can also click the Rule button on the left to add a new set of rules. For example, you may want to extract ad revenue from the monetization data returned by AF and write it to user properties with user_add to record each user's cumulative ad revenue.

To turn off user property ingestion, stop all rules:

2.4 End Point​

End Point shows the address where the AE system receives AppsFlyer callback data. Copy this address directly, and enter it when you configure AF callbacks in the next step:

If no address is shown here, go to Project Settings → Settings → Implementation in the upper-right menu to configure the public network address. You can also click the TE Receiver Host URL link in the tip bar on the configuration page to go there. This address is the receiver URL configured in the AE SDK. After configuring it, return to the AppsFlyer configuration page and copy the address from End Point.

2.5 Event ingestion rules​

  • The time and time zone information in the event_time_selected_timezone field of the data is used: the time is used as #event_time, and the time zone is written as #zone_offset. If event_time_selected_timezone 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.6 Standardized fields​

The following event properties are standardized:

Original fieldStandardized fieldDescription
media_sourcete_ads_object.media_sourceMedia source
monetization_network (ad monetization data)te_ads_object.media_sourceMonetization channel
campaignte_ads_object.campaign_nameCampaign name
af_c_idte_ads_object.campaign_idCampaign ID
af_adsette_ads_object.ad_group_nameAd group name
ad_unit (ad monetization data)te_ads_object.ad_group_nameUnit name of the monetization ad
af_adset_idte_ads_object.ad_group_idAd group ID
af_adte_ads_object.ad_nameAd name
af_ad_idte_ads_object.ad_idAd ID
placement (ad monetization data)te_ads_object.placementAd placement
af_cost_valuete_ads_object.costCampaign cost
af_cost_currencyte_ads_object.currencyCurrency of the user acquisition spend
event_revenuete_ads_object.revenueMonetization revenue
event_revenue_currency (ad monetization data)te_ads_object.currencyCurrency of the monetization revenue
country_codete_ads_object.countryCountry or region code
platformte_ads_object.platformPlatform, such as Android or iOS
app_idte_ads_object.app_idApp ID
app_namete_ads_object.app_nameApp name

3. AppsFlyer Push API configuration​

After completing the configuration in the AE backend, 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

    • Get the address from the End Point field on the AppsFlyer configuration page in the AE system backend and paste it directly

  • Event Messages

    • You need to select at least the Install event. If you want to send back other in-app events, select Install in-app events here and enter the names of the events to send back in In-app events

  • 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, such as app_version and platform
      • Event fields: event_time_selected_timezone

  • In-app events

    • Select the events to send back as needed. To send them back, select Install in-app events in Event Messages
tip

To send back Facebook data, you need to accept the Facebook data use agreement (Terms of Service) in the Facebook channel settings in the AF dashboard. Otherwise, Facebook user-level data can't be obtained.

4. Next steps​

4.1 Check data ingestion​

You can check on the Management page whether the callback events and user properties have been created.

You can also check whether the data has been stored by running analyses in analysis models, such as the Events Analysis model and the Composition Analysis model.

Here are a few suggestions for building reports:

  1. In the Events Analysis model, use the AF callback data to build core ad delivery and ad monetization metrics, and create ad analysis reports
  2. In the Retention Analysis model, combine ad monetization from callback data with in-game payment events to calculate LTV including ad monetization at granularities such as media source and campaign
  3. In the Funnel Analysis model, add the install event to the new user conversion funnel, and analyze the conversion of users from different sources at granularities such as media source and campaign
Was this page helpful?
On this page