Troubleshooting: Missing mobile attribution (install/ uninstall) events

Context:

Mobile attribution partners identifies events using advertising ids like IDFA / IDFV / ADID. But as you know, Amplitude identifies users based on a combination of user_id, device_id, and amplitude_id. So, because the identifiers between mobile attribution partners and Amplitude are different, how do we get the events mapped to the right users in Amplitude? 

That's where Attribution API comes in - a special endpoint that will map attribution events to existing users in Amplitude by matching non-traditional Amplitude identifiers aka advertising ids. Here's the workflow: 

1. Instrument Amplitude first with advertising ids enabled so that you are already collecting data.
2. Mobile attribution partners like Appsflyer / Adjust / Branch / Singular use the Attribution API to send their non-custom, standard data with the advertising ids as the identifier.
3. Amplitude store unmapped attribution events for 72 hours.
4. Within that 72 hours, Amplitude will check to see if there is a matching IDFA, IDFV, or ADID on an already existing user in an Amplitude project. 
5. If there is a matching IDFA, IDFV, or ADID on an already existing user, Amplitude will route that attribution event to that user. 
6. If there isn't and 72 hours has passed since the attribution event was ingested, the attribution event will get dropped. 

The flowchart below show how mapping is based on reconciling the Amplitude event with the attribution event via matching the advertising ID. 

To sum up, there are 2 requirements needed in order for Amplitude to ingest attribution events:

• An existing user in Amplitude with the matching IDFA, IDFV, or ADID
• Mapping completed within 72 hours

Potential reasons for missing mobile attribution events

Given the previous section, the most common reasons why attribution events do not appear in Amplitude are:

1. No existing user in Amplitude with the matching IDFA, IDFV, or ADID
2. Mapping was not completed within 72 hours

We'll get into how to troubleshoot these common reasons in the next section. But before doing so, there are a couple other potential reasons you might not be seeing your attribution events in Amplitude, including: 

1. The attribution events were not successfully sent to Amplitude. Make sure the attribution partner is receiving 200 success response when sending events
2. Your project has reached the instrumentation limit. You may need to delete event types or properties in order for new event types and properties to be ingested. 
3. The event type has been blocked or deleted in the Amplitude project. Please restore the event type or property via Data.

If 200 responses are received, limits are not reached, and events/properties are not blocked or deleted, then please move to the next section. 

Troubleshoot: No existing user in Amplitude with the matching IDFA, IDFV, or ADID

The number one reason for why mobile attribution events don't get ingested by Amplitude is because you do not have existing users in Amplitude with the matching fields. This does mean that you do need to instrument Amplitude first before you can send over mobile attribution events. 

How to tell if you are tracking advertising ids?

Advertising IDs are IDFA, IDFV, or ADID. If you are tracking advertising ids in your Amplitude events, Amplitude will capture the value in the respective property field. However, for security and PII reasons, IDFA, IDFV, or ADID will not appear as a useable property and will be removed from RAW data after it has been captured (unless you instrument this as a custom property). 

Amplitude does store a hashed version of the advertising ids under a field called "amplitude_attribution_ids". You can use this field to identify whether or not you are instrumenting advertising ids. 

If you see "amplitude_attribution_ids": null like the example below, this means no advertising ids was captured for this user. 

This can mean two things: 

1. 1. Your instrumentation is not capturing advertising ids. 

   2. The end user has opted out of advertising id tracking. 

User opt-out must be honored. There is nothing that can be done here other than asking the end user to not opt-out. If you know advertising ids are tracked properly and want to confirm "amplitude_attribution_ids" is null because of user opt-out, please reach out to Support.

Solution: Tracking advertising ids

To solve for your instrumentation not capturing advertising ids, make sure advertising id tracking is enabled, as described in the Track Advertising ID documentation.

If you are using Javascript or React Native SDk which does not have the possibility to track the advertising ids automatically, you will have to send an Amplitude event with the advertising id via the HTTP API (these events should be sent with the same device_id/user ID so that these user’s activities can be merged).

Troubleshoot: Mapping was not completed in 72 hours

Amplitude will hold the attribution event for 72 hours. If within those 72 hours a match is not made, then the attribution event will get dropped.

This can be possible especially if your user doesn't use your app until 4 days later. For example, User A downloads a game app on December 1 but does not open the app until December 7. 

• Mobile attribution partners would list an Install Event for User A on December 1 and send that event to Amplitude on December 1. 
• User A does not record their first event in Amplitude until they open the app on December 7. User A is considered a new user on December 7 in Amplitude. 

User A's Install Event will be dropped because User A did not exist in Amplitude first or within 72 hours of the attribution event. User A only existed in Amplitude 7 days after the Install event which is longer than the 72 hour holding period. 

How to check if attribution event came too early?

As mentioned, mobile attribution partners have very different identifiers compared to Amplitude. Additionally, captured IDFA, IDFV, or ADID values in Amplitude are not visible in the UI. So how to check if an attribution event came too early? 

Luckily, Amplitude's iOS SDKs captures IDFV as device_id by default. If you use the default setting for iOS SDKs, you can use an iOS example to troubleshoot this. 

1. Identify an iOS SDK user in Amplitude that does not have an Install event even though there is a value for "amplitude_attribution_ids"
2. Copy the device_id aka IDFV of that user
3. With your mobile attribution provider, look for the Install event of the IDFV
4. Check the date on the Install event
5. Compare that date to the New User date in Amplitude

You will likely see that the date of the Install event was sent more than 72 hours before the user existed in Amplitude. 

Alternatively, you can also see whether a user doesn't exist in Amplitude yet by following a similar process.

1. Identify an iOS Install event from the mobile attribution provider that does not appear in Amplitude yet
2. Grab the IDFV on that payload 
3. Input the IDFV in User Look-up as device_id

You will likely see that the IDFV is not associated to a profile in Amplitude which means Amplitude has not seen the user yet. There is still 72 hours after the attribution event is sent to Amplitude for matching to occur. After 72 hours and there is still no existing user, then the attribution event will be dropped. 

Solution: Creating users before real user activity

An end user exists in Amplitude when their first event is fired to Amplitude. If you do not want to wait on your end user's own actions to trigger a profile creation, you can create a profile in their stead. You can do so by either:

• Sending a dummy event with advertising id and device_id/user_id through the HTTP API 
• Creating a profile with advertising id and device_id/user_id through Identity API 

This is only possible if you can capture advertising id on your own and make sure you maintain the right device_id/user_id so that real user activity falls into the right profile.