On this page

Integrations and source troubleshooting

These sections cover problems specific to data sources and integrations: Segment, mobile attribution, and third-party site builders.

Segment-Amplitude integration

Missing events

Why don't I see any data in Amplitude?

If the event isn't in Segment, then it isn't in Amplitude. Confirm that your requests from Segment received a successful response before considering an event missing.

After you confirm that the event is in Segment and got a successful response, confirm these three things:

  1. Is Amplitude enabled as a destination?

  2. Is the correct API Key entered?

    Verify the Amplitude API Key value in project settings in your Amplitude UI matches the one in Segment.

  3. Is the syntax correct?

    Instrumentation errors aren't always obvious. Check the code for syntax errors (the browser Console tab can help).

    After you confirm these requirements, send data to Amplitude by calling track. Data appears after you track your first event.

Are you over the event-type instrumentation limit?

If you went over the limit, Amplitude doesn't ingest any data sent after that. To ingest more event types, delete events to get back under the limit.

Is the event deleted or blocked from Amplitude?

Check your deleted and blocked events. Deleting event types also blocks all future instances of events with the same name. If you send data to a deleted or blocked event name in Amplitude, the data doesn't come through.

Are there any errors in Segment's debugger?

Check your Debugger tab for errors. If the missing event doesn't appear in the Debugger, send a test event of that event type. If the event doesn't reach Segment, it won't appear in Amplitude.

Does the event exist in Segment?

For track calls, you can choose to send only certain events to certain integrations. Verify that the event is sending and that Amplitude is enabled.

You can also enable or disable specific integrations directly in the instrumentation code. Check that Amplitude isn't disabled in the code.

For page and screen calls, you can't see all the individual page names, but the activity shows whether Segment is receiving page calls.

You can also check the raw JSON of the requests to verify whether the Amplitude integration is turned off:

json
"integrations": {
    "Amplitude": false
}

Missing properties

What is the difference between an event property and a user property?

The article on user properties and events explains the difference between the two types of properties.

Why don't I see any user properties or only [Amplitude] user properties?

To send user properties through Segment, call identify and include your user properties in the traits field. Refer to the Segment documentation for more on the identify call.

Are you over the event property type instrumentation limit?

If you went over the limit, properties may be missing in Amplitude. Amplitude doesn't ingest any data sent after you exceed the limit. Delete properties to get back under the limit and ingest new properties.

Is the property deleted or blocked from Amplitude?

Check your deleted and blocked properties. Deleting properties also blocks all future instances of properties with the same name. If you send data to Amplitude with a deleted or blocked property name, the data doesn't come through.

Did the property come through in the raw payload to Segment?

If the property isn't in Segment, it won't be in Amplitude. Check Segment's debugger to confirm that the property appeared in Segment first.

Does the property exist in Segment's schema?

Check your tracked properties and confirm they exist in Segment.

Spot any syntax code errors or other instrumentation errors?

Instrumentation errors aren't always obvious. Check the code for syntax errors (the browser Console tab can help).

Refer to Segment's specs for how to format your data.

Amplitude has a limit of 1024 characters. If the property value is too long, the property won't appear in Amplitude.

Why does the location information (city or country) from Segment's data differ from the location information in Amplitude's data?

Amplitude tries to determine the user's location from the user's IP address, if available. This location may differ from the location information Segment recorded.

Incorrectly-tracked sessions

What is the definition of a session?

A session is a period of time when the user has the application open in the foreground. If session tracking is available, events logged within the same session share the same session ID. A new session starts when the application enters the foreground after being in the background or closed for more than five minutes.

Why do all of my events have a sessionId of -1?

If you use the Amplitude Classic integration in Cloud mode, Segment doesn't provide session tracking by default, so Session ID appears as -1 in Amplitude. Segment doesn't have a concept for a session. You must pass in the sessionId for your server-side calls from Segment to Amplitude. For more details, refer to Segment's Amplitude integration docs.

If you use Segment's client-side bundled integration, the integration uses Amplitude's native SDKs, which track Session IDs for you. Segment provides these options:

Why are there no session length calculations in Amplitude Dashboard?

When Session ID is -1 (see the previous answer), Amplitude can't calculate session length.

What if Segment's SDK doesn't support feature X? [device-mode]

The Segment SDK might not have all the APIs the Amplitude SDK provides. You can still access features by directly calling Amplitude's SDKs.

Still have questions?

Submit a Support ticket with the following details:

  • What type of connection are you using? (cloud-mode or device-mode).
  • Do you have any destination filters enabled?
  • Do you see any errors in the Event Delivery tab?
  • Confirm that you're using the correct API Key for the Amplitude destination.

Also share the raw data for an event that should have been in Amplitude but is missing. Amplitude needs a full payload of the event, including the endpoint used, header, and body.

iOS 14 changes

At WWDC 2020, Apple announced that iOS 14 requires users to opt in to tracking. The IDFA is only present for users who explicitly opt in, and the percentage of users who do so is likely to be low.

This article covers frequently asked questions about Apple's iOS 14 IDFA changes.

Does Amplitude accept IDFA (Identifier for Advertisers) as the device identifier on iOS?

By default, Amplitude's iOS SDK uses IDFV (Identifier for Vendor) for the device ID. You can change this and use any value as the device identifier. The SDK includes an option to use IDFA as the device ID, but this option only works if the user has permitted the application to use IDFA.

What are the implications of Apple's IDFA changes on user tracking?

For logged-in users, there's no impact. Even if the device ID changes, events continue to merge from devices when Amplitude receives a common user ID. Anonymous users have some potential for impact.

For anonymous users, there are no changes in most cases, because most Amplitude customers don't set IDFA as the device ID. For customers who do set IDFA as the device ID, Amplitude stores the device ID when the SDK initializes, and the SDK continues to send Amplitude the same ID as long as the application remains installed on the device.

If a user deletes and reinstalls an application that uses IDFA for device ID, the former device ID isn't retained. Instead, the SDK generates a new random device ID, unless the user grants the application permission to use IDFA.

For all new application installs, the SDK accepts IDFA if the user has opted in and the application chooses to use IDFA.

Does Amplitude require IDFA on attribution events?

No. Amplitude's attribution API accepts both IDFA and IDFV, and tries to match those IDs to user events Amplitude receives later. In some cases, IDFV is enough to make a match, but some Amplitude customers' attribution providers only send IDFA. For these customers, Amplitude can no longer match attribution events unless the user has explicitly opted in to both the referring and installed application.

Some attribution vendors are likely to stop sending individual attribution events. Vendors are unlikely to send aggregated data to Amplitude (because of the nature of the platform), unless customers or attribution vendors can segment that data and use it to set user properties.

How does this affect outbound integrations?

If you send data to outbound integrations, you see a lower match rate when using IDFA to match devices between Amplitude and the integration. Amplitude recommends switching to IDFV or another common identifier instead.

Missing mobile attribution events

Mobile attribution partners identify events using advertising IDs like IDFA, IDFV, or ADID. Amplitude identifies users based on a combination of user_id, device_id, and amplitude_id.

Amplitude's Attribution API reconciles these differences and maps attribution events to existing users in Amplitude. Some mobile attribution partners (Appsflyer, Adjust, Branch, and Singular) use this API to send their non-custom, standard data with the advertising IDs as the identifier.

Amplitude stores unmapped attribution events for 72 hours. During that time, Amplitude looks for a matching IDFA, IDFV, or ADID on an existing user in an Amplitude project. If a match exists, Amplitude routes the attribution event to that user. If no match exists, Amplitude drops the attribution event after 72 hours.

To support this process, instrument Amplitude with advertising IDs enabled.

Why mobile attribution events may be missing

You can resolve some causes quickly:

  • The attribution events didn't successfully send to Amplitude. Confirm that the attribution partner receives a success response (for example, a 200) when sending events.
  • Your project has reached the instrumentation limit. Delete event types or properties to allow Amplitude Analytics to ingest new event types and properties.
  • You blocked or deleted the event type in the Amplitude project. Restore the event type or property through Amplitude Data to fix the issue.

Other causes require more investigation:

  • No existing user in Amplitude with the matching IDFA, IDFV, or ADID.
  • Amplitude didn't complete mapping within 72 hours.

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

This is the top reason why Amplitude Analytics doesn't ingest mobile attribution events. You must instrument Amplitude before you can send mobile attribution events.

Determine if you're tracking advertising IDs

Advertising IDs are IDFA, IDFV, or ADID. If you track advertising IDs in your Amplitude events, Amplitude Analytics captures their value in the respective property field. For security and PII reasons, advertising IDs don't appear as a usable property, and Amplitude removes advertising IDs from your raw data after capture (unless you instrument advertising IDs as a custom property).

Amplitude stores a hashed version of the advertising IDs in a field called amplitude_attribution_ids. Use this field to determine whether you're instrumenting advertising IDs. If the value is null, Amplitude captured no advertising IDs for this user.

A null value generally means either that you haven't instrumented Amplitude Analytics to capture advertising IDs, or that the end user has opted out of advertising ID tracking.

You must honor user opt-outs. If you know advertising IDs are tracked properly and want to confirm amplitude_attribution_ids = null because of user opt-out, contact Amplitude Support.

Solution: Tracking advertising IDs

If you use JavaScript, which can't track advertising IDs automatically, send an Amplitude event with the advertising ID through the HTTP API.

Troubleshoot: Mapping didn't happen within 72 hours

Amplitude holds an attribution event for 72 hours. If Amplitude doesn't make a match during that time, Amplitude drops the event.

For example, User A downloads a game app on December 1 but doesn't open the app until December 7:

  • Mobile attribution partners list an Install event for User A on December 1 and send that event to Amplitude on December 1.
  • User A doesn't record their first event in Amplitude until they open the app on December 7. Amplitude considers User A a new user on December 7.

Amplitude drops User A's Install event because User A didn't exist in Amplitude within 72 hours of the attribution event. User A only existed in Amplitude seven days after the Install event, which is longer than the 72-hour holding period.

Determine if the attribution event came too early

Amplitude's iOS SDKs capture IDFV as device_id by default. If you use the default setting for iOS SDKs, use this process to troubleshoot:

  1. Identify an iOS SDK user in Amplitude who doesn't have an Install event, even though there is a value for amplitude_attribution_ids.
  2. Copy the device_id (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.

The Install event was likely sent more than 72 hours before the user existed in Amplitude.

You can also check whether a user already exists in Amplitude by following a similar process:

  1. Identify an iOS Install event from the mobile attribution provider that doesn't appear in Amplitude yet.
  2. Get the IDFV on that payload.
  3. Enter the IDFV in the user look-up feature as the device ID.

The IDFV likely doesn't associate with a profile in Amplitude Analytics, which means Amplitude hasn't seen the user yet.

Solution: Create users before real user activity

An end user exists in Amplitude when Amplitude receives the user's first event. If you don't want to wait on the end user's actions to trigger profile creation, create a profile yourself by either:

  • Sending a placeholder event with advertising ID and device_id or user_id through the HTTP API.
  • Creating a profile with advertising ID and device_id or user_id through the Identity API.

Creating a profile is only possible if you can capture the advertising ID on your own. Maintain the correct device_id or user_id so you connect real-world user activity to the right profile.

Instrument on third-party site builders

These instructions may become outdated as the third-party platforms covered here make changes and upgrades. Amplitude's Support team provides support for the instructions and processes in this article only; they can't provide recommendations for anything not included here.

How do I instrument Amplitude on a third-party website builder?

If your site is built on a third-party website builder like Wix or Squarespace, most builders have an underlying code base you can use. Add Amplitude's JavaScript SDK to that space, as if you were adding the SDK to a natively-built website. Add the JavaScript SDK snippet to the header, and the rest of the JavaScript SDK code in the body.

If you don't have access to the header or underlying source code, you can use webhooks to combine a trigger or automation with an HTTP target to Amplitude's server-side endpoint, HTTP v2.

How do I instrument Amplitude on Wix?

Wix has a Tracking Tools & Analytics feature, which you can use to embed Amplitude's JavaScript SDK snippet and code in your site.

To do so, follow these steps:

  1. Go to Settings in your site's dashboard.
  2. Click the Tracking & Analytics tab, under Advanced Settings.
  3. Click + New Tool and select Custom.
  4. Set up your custom code:
    1. Enter your custom code.
    2. Select the relevant domain. This option appears only if you have multiple domains.
    3. Enter a name for your custom code.
    4. Add Code to Pages: Select which pages to add your code to:
      • All Pages: Click the dropdown and select either Load code once, or Load code on each new page.
      • Choose specific pages: Begin typing the name of the relevant pages. Then click the checkbox next to the relevant page.
    5. Place Code in: Select where to place the code snippet in your site's code.
  5. Click Apply.

Some customers have reported that Wix lets you add header scripts but not call functions from them. One workaround is to put the necessary script in the Public folder.

Further reading on Wix

How do I instrument Amplitude on Squarespace?

Squarespace's Code Injection and Code Block features let you embed Amplitude's JS SDK snippet and code in your site.

These features may be premium features, only available in Business and Commerce plans.

Code Injection

Use Code Injection to add Amplitude's JavaScript SDK install snippet and other scripts that enhance specific parts of your site, like an order confirmation page.

To add JavaScript to a Code Injection field, surround the code with <script></script> tags. Site-wide and per-page code injection options are both available. For the per-page code injection option, refer to Squarespace's Code Injection article. If you add code to Code Injection, Squarespace may ask you to disable the code while editing your site.

To add the JavaScript SDK install snippet with Code Injection:

  1. Open Code Injection. In the Home menu, navigate to Settings > Advanced > Code Injection.
  2. Add JavaScript SDK code into the appropriate Code Injection fields for the header, footer, lock page, or order confirmation page.
    • Header: Code added here goes into the <head> tag on every page in your site. The Amplitude JavaScript SDK install snippet belongs here.
    • For information on the other three options, refer to Squarespace's Code Injection article.
  3. After adding your code, click Save.

Code Block

Use Code Block to set up logEvent, user properties, and similar calls. To add JavaScript to a Code Block field, surround the code with <script></script> tags.

To add a Code Block, follow these steps:

  1. Edit a page or post, click an insert point, and select Code from the menu. For help, refer to Adding content with blocks.
  2. Add your code in the text field. For event and property calls, refer to the Browser SDK 2 documentation.
  3. If you're using the Code Block to display code snippets, check Display Source.
  4. Click Apply to save your changes.

Was this helpful?