Skip to main content

AppsFlyer FAQ (self-help)

Last updated 10/07/2026

1. Push Api​

1.1 SDK initialization order (must read)​

warning

The ThinkingData & AF SDKs must be initialized and their APIs called strictly in the following order

  • Initialize the ThinkingData client SDK
  • Call the automatic or manual integration API to set distinct_id in third-party events (for the code, see the official documentation AppsFlyer Push API; it isn't repeated here)
  • Initialize the AF SDK

1.2 AE configuration - empty endpoint URL under the data source​

  • In the AE backend, go to Project Settings — Implementation — TE Receiver Host URL and add the server address that uses port 8991. You can confirm the address with your company's operations team. The AppsFlyer platform endpoint URL is then synced automatically.

1.3 Callback plan statuses explained​

1.3.1 Status 1: Error​

  • Causes of the Error status

    • No data is sent back within 2 hours after the AF callback plan is created or updated.
    • Data was received within the last 72 hours, but some of it failed to convert, or no new events have been sent back for more than 72 hours.

  • Analyzing why conversion failed

    • To find out why data failed to convert, click the Details icon in the upper-right corner of the plan and view the reasons for the failed conversions in the data details

    • Scenario: Failed to transform, reason: Neither #account_id nor #distinct_id can be associated

1.3.2 Status 2: Connected​

  • If the platform connection status is Connected, data has been received from the platform and ingested. You can click Detailed data on the integration page or on each platform's configuration page to view the latest 1000 records received:

1.3.3 Status 3: Waiting for integration​

  • No events have been sent back to AE since the configuration was completed, or no new data has been sent back to AE since the plan was modified

1.4 Mismatch between the number of AF install events and AE ta_app_install events​

  • This is usually because install events are collected under different rules. ta_app_install is triggered every time the app is newly installed or uninstalled and reinstalled, while af sdk install has an attribution window, and uninstalling and reinstalling within the window doesn't report the install event again. For details about AF attribution windows, see the following documentation: Re-attribution window explained

  • Besides the inherent differences, troubleshoot other data differences with the following steps (we recommend checking them in the order 1, 2, 3):

    API usedInstall differencesIn-app event differences

    Push API

    1. Check whether the sampling period of the comparison is too short and whether the time zones being compared match

    2. Check whether some app versions don't integrate the AE SDK or the AppsFlyer SDK

    3. Check whether the install events that the AE server receives from AppsFlyer contain the Custom Data/Customer User Id field with a normal, non-empty value

    4. Check whether the key names of the Custom Data/Customer User Id field in the raw data downloaded from the AppsFlyer dashboard are ta_account_id and ta_distinct_id

    5. Check whether the Custom Data/Customer User Id field has missing values in the raw data downloaded from the AppsFlyer dashboard

    5.1 If it isn't empty, Custom Data/Customer User Id wasn't selected in the Push API push settings;

    5.2 If it's empty, the client SDK didn't report Custom Data/Customer User Id

    6. Check whether the AppsFlyer SDK has a high failure rate when reporting ta_account_id or ta_distinct_id through setAdditionalData() or setCustomerUserId()

    7. Check the inbound authorization object settings of the server's security group. You can also add all AppsFlyer IP addresses to the allowlist

    1. Check whether the AppsFlyer event table data ingestion configuration is turned on
    2. Check whether the sampling period of the comparison is too short and whether the time zones being compared match
    3. Check whether some app versions don't integrate the AE SDK or the AppsFlyer SDK
    4. Cost differences: check whether you've connected SRN channels such as Facebook and Google, whose cost data can't be obtained through Push API;
    5. Revenue differences: check the name of the event that carries revenue, and determine whether AppsFlyer gets that event in batches or in real time

1.5 Why can't I find the data even though all callback events were converted successfully?​

  • Check whether Strict Verification mode is enabled for the project. If it is, we recommend that you turn it off first and turn it back on after a batch of data has been sent back.
  • To check whether Strict Verification mode is enabled: click the settings button in the upper-right corner, click Project Settings, and then check Data Processing Rules.

1.6 Other​

1.6.1 Channel media_source shows restricted, or user properties contain only media_source after conversion​

  • See the solution for getting AppsFlyer Android FB user-level data based on Google Install Referrer.

1.6.2 AppsFlyer channel media_source is empty, but the campaign name has a value​

  • This is usually related to agency transparency. Turn on agency transparency and observe again. For details, see the documentation.

1.6.3 How to connect and convert S2S data​

  • When you connect AppsFlyer S2S data, report the customer_user_id or custom_data field obtained from the client SDK so that the data can later be bound to AE users. For details about reporting S2S fields, see the AppsFlyer S2S events API for mobile (S2S-mobile)

1.6.4 How to download AppsFlyer Push API raw data​

  • Log in to the AppsFlyer dashboard, go to Export - Raw Data Export in the left navigation bar, select the organic and non-organic events, click create, then select customize, select the custom_data field, and then download the data

1.6.5 What does the te_ads_object property mean, and can other fields be stored in it?​

  • te_ads_object is a standardized object field. It stores fields that have different names but the same meaning on different third-party platforms in one object, to make later analysis easier.
  • Yes. You can configure this in the User Properties Configuration module: set the source data name to the field name before conversion, and set Target Property to the field name to ingest
    • For example, map the raw data field idfa sent back by AF to the te_ads_object object.

2. Pull/Master/Cohort Api​

2.1 Recommended pull frequency settings​

APISame-day data supportedHow to choose the pull frequency
Pull API

Yes

If you don't need real-time data, we recommend pulling the last 3-7 days of AppsFlyer data at 12:00 noon (UTC) every day. If you need near-real-time data, pull every hour.

Master API

No

If you don't need real-time data, we recommend pulling the past 3-7 days of AppsFlyer data at 12:00 noon (UTC) every day. If you need near-real-time data, pull every hour.
Cohort APINoIf you don't need real-time data, we recommend pulling the past 3-7 days of AppsFlyer data at 12:00 noon (UTC) every day. If you need near-real-time data, pull every hour.

2.2 How do I configure multiple App IDs in the same plan?​

  • Separate multiple App IDs with English commas (,), as shown below

2.3 Does pulling data for the same time range repeatedly create duplicate data?​

  • Pulling data for the same time range multiple times doesn't create duplicates. The data for that time range is entirely overwritten by the new data

2.4 How do I change the names of pulled events?​

  • Pull Api

    • If you pull partner data, change the value of partner in the event_mapping object.
    • If you pull geo data, change the value of geo in the event_mapping object.

  • Master Api

    • Change the value of event_name

  • CohortApi

    • Change the value of event_name

2.5 How to check whether a data pull succeeded or failed​

  • After the configuration succeeds, click Single pull task in the upper-right corner of the plan. You're notified of the pull result through Notifications.
  • Example of a successful pull
  • Example of a failed pull

2.6 Configure AF data pulls in a specified time zone​

  • Add the extra_params - timezone configuration. A complete example follows

    tip
    • Explanation on the AF website
    • Example 
      • {
          "extra_params": {
            "timezone": "China%2FShanghai"
          },
          "sink_event": {
            "event_mapping": {
              "geo": "appsflyer_geo_data",
              "partner": "appsflyer_partner_data"
            }
          },
          "sink_user": [],
          "source": {
            "report_types": [
              "partner"
            ]
          },
          "transfer": {
            "fields_whitelist": [
             " 。。。。"
            ],
            "double_columns": [
             " 。。。。"
            ]
          }
        }

2.7 Are SKAN data callbacks supported?​

  • Not supported yet: because of iOS platform restrictions, the AE user identifier can't currently be set in SKAN events

2.8 Common pull errors and solutions​

  • Create event and props failed!

    • This error usually occurs when you pull data for the first time or add fields to pull in a plan. Server overload may cause the creation of new fields to fail. Wait about 10 minutes and try pulling the data again. If the problem persists, report it to the ThinkingAI customer success manager (CSM) or ThinkingAI technical contact in your support group.
    Missing image：img-7250795c0df5

  • Get thirdparty data failed! The possible error is: AppsFlyer - Page Not Found

    • Possible cause 1: AF Cohort & Master API are paid AF APIs. Make sure the related permissions are enabled.
    • Possible cause 2: the AppID entered may be wrong. Check whether the AppID configured in the AE plan matches the one provided in the AF admin dashboard.
    • Possible cause 3: the App ID isn't live on the AppsFlyer side yet and is still in test status.
    • If none of the above causes applies, report it to the ThinkingAI customer success manager (CSM) or ThinkingAI technical contact in your support group.
    Missing image：img-504127009267

2.9 Other​

2.9.1 Pulled data doesn't match the data in the AppsFlyer dashboard​

  • Check whether the metrics you compare in AppsFlyer are the same as the metrics you compare in the AE backend;

    • Analyze whether the difference is caused by different dimensions or parameter settings
    • The selected apps or cost channels are different

  • Check whether the time zone of the AppsFlyer dashboard data matches the time zone the plan uses to pull data (by default, the plan pulls data in UTC)

  • AppsFlyer API data is subject to delays and updates. If the data for a few dates is inaccurate, click Single pull task in the upper-right corner of the plan to pull it again;

  • If the issue persists after you check all of the above, contact ThinkingAI technical support for help.

2.9.2 Revenue data in the AppsFlyer dashboard cohort report doesn't match the data pulled by Master API​

  • As shown below, the revenue data in the AppsFlyer cohort dashboard is cumulative since install. To compare, pull the data with Cohort API.
    Missing image：img-e47832d7ddef

2.9.3 No cost value for the FB channel in data pulled through Cohort API​

  • Because cost isn't aggregated data, different grouping items can cause data differences. For example, when Geo and Channel are both used as grouping items, the FB cost value is 0. AF official documentation: cost metrics can't be combined with certain grouping dimensions. For example, Facebook data can be grouped by Geo (country/region) or Channel (traffic source), but not by both at the same time. The available combinations of grouping dimensions depend on the ad network. For details, contact ThinkingAI technical support.

2.9.4 No cost value for the applovin channel in data pulled through Cohort API​

  • Set group_by to "date","c","pid" and check whether there's cost data.

2.9.5 AppsFlyer Master API cost data for the last 7 days doesn't match the overview dashboard in the AF backend​

More questions​

Some data shows without_id​

  • Check whether the App version of the without_id data is consistent
  • Check whether the latest app version also has without_id data
  • Check the client ID binding logic and make sure the order is: initialize the ThinkingData SDK → pass the ID to AF → initialize the AF SDK

What to note when switching from AF to Adjust​

  • Assign the distinct ID to Adjust (requires a new app release)
  • For cost data, we recommend connecting Adjust Report API
  • If you run Facebook campaigns, configure detailed Facebook ad information by referring to the Adjust real-time callbacks appendix

AE shows more FB channel users than the AF backend​

  • Reason: both the install event and the af_app_install event are data sent back from the AF platform to AE. In AF, these two events are different data sources for the same kind of behavior
  • Solution: distinguish between the event definitions

AF revenue raw data pull fails​

  • Reason: a group by configuration issue
  • Solution: check the group by configuration and make sure it includes required fields such as gp_install_begin, campaign_type, att, keyword_match_type, and conversion_type

AF pull raw data doesn't support the timezone field​

  • The Pull API raw data interface doesn't support time zone settings

Pulling AF retargeting spend​

  • Use Cohort API to pull retargeting spend, or spend that includes retargeting

AF meta data pulls country as 0​

  • Reason: event_mapping is missing from the configuration
  • Solution: replace it with the standard configuration, save the plan, and pull again. Pull today's data first, and after that succeeds, pull historical data

AF master FB spend doesn't match​

  • Reason: the documentation states that geo and channel can't be passed at the same time
  • Solution: remove both to match the AF backend

Configuration notes​

How to add a whitelist of fields to ingest (fields_whitelist)​

Add fields_whitelist to transfer in the format ["field_1", "field_2"] to control which fields are ingested:

"transfer": {
  "double_columns": ["impressions", "installs", "loyal_users"],
  "fields_whitelist": ["agency_pmd_af_prt", "app_id", "arpu"]
}

How to set the Master API time zone​

Master API uses the UTC time zone by default. You can set timezone to preferred (the app time zone) through extra_params:

"extra_params": {"timezone": "preferred"}

How to set the Cohort API time zone​

preferred_timezone defaults to true (the app time zone). To use the UTC time zone, set preferred_timezone to false through custom_properties (Base64-encoded):

"extra_params": {
    "custom_properties": "eyJwcmVmZXJyZWRfdGltZXpvbmUiOmZhbHNlfQ"
}

How to get total spend through Cohort​

To get total spend (including retargeting cost data), set {"cohort_type":"unified"}:

"extra_params": {
    "custom_properties": "eyJjb2hvcnRfdHlwZSI6InVuaWZpZWQifQ=="
}

How to set the Cohort aggregation type​

When aggregation_type=on_day, unique session data is returned (such as sessions_unique_users_day_*). In this case, partial_data must be set to false:

{"extra_params": {"aggregation_type": "on_day", "partial_data": "false"}}

Error notes​

AF Pull API error 403 Limit reached for partners-report​

  • AF limits how often the API can be pulled, so keep the pull frequency under control.

AF pull raw data revenue request fails​

  • To remove invalid fields such as campaign_type, att, keyword_match_type, and conversion_type, check and adjust the group by configuration.
Was this page helpful?
On this page