AppsFlyer Pull Raw Data
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Pull API Raw Data | API | User level | ✅ | ✅ | ✅ |
Pull API Raw Data can pull user-level data for a period of time. This integration method lets you get detailed user data when real-time delivery isn't required, and it's also well suited to pulling historical user-level data.
Integration process
- Integrate the AppsFlyer client SDK and the AE SDK, and set the AE user identification ID in the AF SDK
- 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 Pull Raw Data plan, and complete the related configuration
- 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 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 integrated is 2.8.2 or later, you also need to install the third-party data plugin. For details, see Android SDK third-party data and iOS SDK third-party data
// Initialize the AE SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// Enable AppsFlyer ID association
TDAnalytics.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 = TDAnalytics.GetDistinctId();
AppsFlyerLib.getInstance().setcustomerUserId(distinctId);
// After calling login to set the account ID, sync the data again (optional)
TDAnalytics.login("account_id");
TDAnalytics.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");
TDAnalytics.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.
1.2 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:
// Get the AE distinct ID, which corresponds to #distinct_id in AE
String distinctId = TDAnalytics.GetDistinctId();
// Your account ID (or character ID), which corresponds to #account_id in AE
String accountId = "your_account_id";
// Deploy at activation
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.
2. Get the API token and App ID
2.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.
2.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. Plan configuration
After getting the AppsFlyer API token and App ID, you can 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 Pull Raw Data. Follow this section to create the plan:
3.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
3.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull AppsFlyer Pull Raw Data data on a schedule. You can choose to pull data for a period of time at a specific time every day, with a maximum of 31 days per pull. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
3.3 Pull time zone
You can also set the time zone of the pulled data. The default is UTC+0
3.4 User identification fields
Because AppsFlyer Pull Raw Data returns user-level data, you need to set user identification rules for it, that is, the fields in the data returned by AF 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 returned 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
3.5 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.
3.6 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 field | Standardized field | Description |
|---|---|---|
| media_source | te_ads_object.media_source | Media source |
| campaign | te_ads_object.campaign_name | Campaign name |
| adset | te_ads_object.ad_group_name | Ad group name |
| ad | te_ads_object.ad_name | Ad name |
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:
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:
3.7 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_mapping | Event name after ingestion; customizable |
| source | report_types | The type of data to pull; customizable. The default is installs, ad_revenue, that is, install and monetization events |
| group_by | Grouping dimensions in the data; list type; customizable | |
| extra_params | double_columns | Numeric field definitions. Fields entered here are stored as numeric types. Enter the field names after ingestion |
By default, Pull API Raw Data supports pulling the following data:
You can also see the AppsFlyer official documentation for more supported fields, and enter the fields you need in source.group_by
3.7.1 Default metrics
| Field | Display name |
|---|---|
| event_value | Event value |
| event_revenue | Event revenue |
| event_revenue_usd | Event revenue (USD) |
| cost_value | Cost value |
3.7.2 Default dimension fields
| Field | Display name |
|---|---|
| attributed_touch_time | Attribution time |
| install_time | Activation time |
| event_time | Event time |
| event_name | Event name |
| event_value | Event value |
| event_revenue | Event revenue |
| event_revenue_currency | Event revenue currency |
| event_revenue_usd | Event revenue (USD) |
| event_source | Event source |
| is_receipt_validated | Whether the receipt has been validated |
| partner | Partner |
| media_source | Media source |
| channel | Sub-channel |
| keywords | Keywords |
| campaign | Campaign name |
| campaign_id | Campaign ID |
| adset | Ad group name |
| adset_id | Ad group ID |
| ad | Ad creative name |
| ad_id | Ad creative ID |
| ad_type | Ad type |
| site_id | Site ID |
| sub_site_id | Sub-site ID |
| sub_param_1 | Sub-parameter 1 |
| sub_param_2 | Sub-parameter 2 |
| sub_param_3 | Sub-parameter 3 |
| sub_param_4 | Sub-parameter 4 |
| sub_param_5 | Sub-parameter 5 |
| cost_model | Cost model (CPC/CPI/CPM/Other) |
| cost_value | Cost value |
| cost_currency | Cost currency |
| contributor_1_partner | Contributor 1 partner |
| contributor_1_media_source | Contributor 1 media source |
| contributor_1_campaign | Contributor 1 campaign |
| contributor_1_touch_type | Contributor 1 attribution type |
| contributor_1_touch_time | Contributor 1 attribution time |
| contributor_2_partner | Contributor 2 partner |
| contributor_2_media_source | Contributor 2 media source |
| contributor_2_campaign | Contributor 2 campaign |
| contributor_2_touch_type | Contributor 2 attribution type |
| contributor_2_touch_time | Contributor 2 attribution time |
| contributor_3_partner | Contributor 3 partner |
| contributor_3_media_source | Contributor 3 media source |
| contributor_3_campaign | Contributor 3 campaign |
| contributor_3_touch_type | Contributor 3 attribution type |
| contributor_3_touch_time | Contributor 3 attribution time |
| region | Region |
| country_code | Country code |
| state | State/Province |
| city | City |
| postal_code | Postal code |
| dma | DMA code |
| ip | IP address |
| wifi | Whether Wi-Fi is on |
| operator | Mobile operator |
| carrier | Mobile carrier |
| language | Language |
| appsflyer_id | AppsFlyer ID |
| advertising_id | Advertising ID |
| idfa | IDFA |
| android_id | Android ID |
| customer_user_id | Customer User ID |
| imei | IMEI |
| idfv | IDFV |
| platform | Platform |
| device_type | Device Type |
| os_version | OS |
| app_version | App version |
| sdk_version | SDK version |
| app_id | App ID |
| app_name | App name |
| bundle_id | Bundle ID |
| is_retargeting | Is retargeting |
| retargeting_conversion_type | Retargeting conversion type |
| 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 |
3.7.3 Extra fields added in the default configuration
You can adjust these fields in source.group_by of the configuration
| Field | Display name |
|---|---|
| device_model | Device model |
| keyword_id | AF keyword ID |
| store_reinstall | App store at reinstall |
| deeplink_url | Deeplink URL |
| oaid | OAID |
| install_app_store | App store at install |
| contributor1_match_type | Contributor 1 match type |
| contributor2_match_type | Contributor 2 match type |
| contributor3_match_type | Contributor 3 match type |
| match_type | Attribution match type |
| device_category | Device category: phone, laptop, other |
| gp_referrer | Google Play URL referrer |
| gp_click_time | Ad click time recorded by Google Play |
| gp_install_begin | Install time recorded by Google Play |
| amazon_aid | Amazon device ID |
| keyword_match_type | Keyword match type |
| att | ATT status on iOS 14+ |
| conversion_type | Turn into |
| campaign_type | Campaign type |
| is_lat | Whether the user limits ad tracking. When true, the IDFA or GAID is replaced with all zeros |
| custom_data | Custom Data, used to get the user identification fields |
3.8 Data ingestion rules
The Pull Raw 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 events with the event name af_install
- The event_time in the data, that is, the time the event occurred, is used as the event's #event_time
- The default user property ingestion rules write some fields of the Installs data to the user table
- 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. Fields in double_columns are ingested as numeric values, and other fields are ingested as strings
-
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. Fields in double_columns are ingested as numeric values, and other fields are ingested as strings
3.9 Standardized fields
The following event properties are standardized:
| Original field | Standardized field | Description |
|---|---|---|
| media_source | te_ads_object.media_source | Media source |
| monetization_network (ad monetization data) | te_ads_object.media_source | Monetization channel |
| campaign | te_ads_object.campaign_name | Campaign name |
| campaign_id | te_ads_object.campaign_id | Campaign ID |
| adset | te_ads_object.ad_group_name | Ad group name |
| ad_unit (ad monetization data) | te_ads_object.ad_group_name | Unit name of the monetization ad |
| adset_id | te_ads_object.ad_group_id | Ad group ID |
| ad | te_ads_object.ad_name | Ad name |
| ad_id | te_ads_object.ad_id | Ad ID |
| segment (ad monetization data) | te_ads_object.placement | Ad placement |
| cost_value | te_ads_object.cost | Campaign cost |
| af_cost_currency | te_ads_object.currency | Currency of the user acquisition spend |
| event_revenue | te_ads_object.revenue | Monetization revenue |
| event_revenue_currency (ad monetization data) | te_ads_object.currency | Currency of the monetization revenue |
| country_code | te_ads_object.country | Country or region code |
| platform | te_ads_object.platform | Platform, such as Android or iOS |
| app_id | te_ads_object.app_id | App ID |
| app_name | te_ads_object.app_name | App name |