Amplitude Destination

Amplitude is an event tracking and segmentation platform for your web and mobile apps. By analyzing the actions your users perform, you can gain a better understanding to drive retention, engagement, and conversion.

Segment’s Amplitude destination code is open source and available on GitHub. You can view these repositories:

• Android
• iOS
• JavaScript
• Kotlin
• Swift

In addition to Segment’s Amplitude documentation, Amplitude provides a Segment integration guide, as well.

Getting Started

1. From the Segment web app, navigate to Connections > Destinations and click Add Destination.
2. Search for Amplitude select it.
3. Choose which sources to connect the destination to.

4. In the destination settings, enter your Amplitude API key.

   You can find your Amplitude API key in the Amplitude project settings . It is a 32-character string of numbers and letters. Locate the project you want to receive your Segment data, copy that project’s API key, and paste it into your Amplitude destination settings in Segment.

If you included Segment’s JavaScript snippet on your page, then Amplitude’s SDK loads on your page automatically and you can use Segment’s to begin sending events right away.

Page and Screen

If you’re not familiar with the Segment Specs, take a look to understand what the Page and Screen methods do. By default, Segment does not send these standard calls to Amplitude. However, you can enable them with the destination settings below, which you can find under the “Optional Settings” tab.

The example below shows a Page call from a server library.

analytics.page({
  userId: "some_user_id", // if using A.js client-side, you can leave out the `userId`
  category: "Merchant",
  name: "Settings",
})

The next example shows a call from a mobile library, which uses the Screen call instead of the Page call.

// Note: screen calls are only for mobile. you can't make them from A.js client-side.
analytics.screen({
  userId: "some_user_id",
  category: "Merchant",
  name: "Settings",
})

Page and Screen calls have two important properties: a page name, such as “Settings”, and a category, such as “Merchant”. How you pass these properties depends on which Segment library you use. Segment determines when to send events to Amplitude based on the settings you enable, and whether the call has a name or category included.

Event type settings for cloud-mode and Analytics.js

If you use Analytics.js (in either device- or cloud-mode), a mobile library in cloud-mode, or a Segment server library, the following settings are available. (Additional settings are available only for iOS and Android sources that send in device-mode.)

Before you choose a setting, read about the Amplitude event type volume considerations.

When you use the Track Named Pages or Track Categorized Pages settings, Segment sends a Page or Screen call that includes the name or category. This option stores the page and screen name as a top-level event type. However, Amplitude limits the number of distinct event types per project. Each unique Page and Screen name, Page and Screen category, and Track event counts towards the event type limit. Anything past the instrumentation limit is not visualized in Amplitude.

When you use the Track All Pages setting, Segment sends a Loaded a Page event type to Amplitude. When you use the generic event name, it is applied to all Page and Screen calls, so you don’t hit the event type limit in your project in Amplitude. The page or screen name is still available as an attribute of the Loaded a Page event, and you can query it as an event property. The Loaded a Page event is counted as one event type, and Amplitude does not place any limits on the number of unique event property values in Amplitude.

Event Type settings for iOS

The following settings are available on iOS for device-mode connections.

When enabled, the “Track All Screens” setting includes the screen name and category as event properties, where the “Track All Pages” omits them. Most iOS implementations should use “Track All Screens”.

Event Type settings for Android

The following settings are available on Android for device-mode connections.

You can learn more about Page calls from the Page spec and Screen calls from the Screen spec.

Identify

If you’re not familiar with the Segment Specs, take a look to understand what the Identify method does. An example call would look like:

// On server-side
analytics.identify({
  "userId": "123",
  "anonymousId": "a80b66d5-b86d-41bd-866f-fe04ee7841af",
  "traits": {
    "email": "derek@example.com",
    "name": "Derek Sivers",
    "industry": "Music"
  }
})

// On client-side
analytics.identify({
  "email": "derek@example.com",
  "name": "Derek Sivers",
  "industry": "Music"
})

When you make an Identify call, Segment uses the userId you provide to set the User Id in Amplitude, and sets any traits you provide as Amplitude custom user_properties.

Merging users with Anonymous ID and User ID

To have Amplitude recognize an anonymous user and a known or logged-in user, make sure you include both the user’s userId and the anonymousId they had before that in your Identify call. If you don’t include the anonymousId, Amplitude can’t tell that the anonymous user is the same person as the logged-in user.

If you’re using a Segment server library or the Segment HTTP API, you must explicitly include both anonymousId and userId. If you’re using Analytics.js in device-mode, or a bundled SDK, Segment automatically includes anonymousId for you.

Amplitude Device ID

You can set the Device ID in slightly different ways depending on the library and connection mode you’re using (Device-mode vs Cloud-mode).

Default library behavior for Device ID

The table below represents default behavior.

Prefer Anonymous ID for Device ID

If you’re using the “Prefer Anonymous ID for Device ID” setting in client-side, server-side, or a mobile library with Cloud-mode enabled, the following rules apply.

Prefer Advertising ID for Device ID

This option is not currently available for mobile libraries using cloud-mode.

If you’re using the “Prefer Advertising ID for Device ID” setting with one of our bundled mobile SDKs, the following rules apply.

Device ID priority

If you have multiple settings enabled, one setting or value can take priority of another. This table lists which settings, if enabled, take priority over other settings or values.

Using Device ID to merge users

For Amplitude to associate both device-mode and cloud-mode activity with the same user, you must pass the same deviceID to Amplitude. Otherwise, Amplitude creates two users - one for each of the deviceID’s set per the functionality outlined in the tables above.

You can get the deviceID from Amplitude in device-mode so you can return it on cloud-mode calls. The example method below shows how you could log the deviceId in the ready function on the device, so you could send it to the server.

analytics.ready(function() {
  // Instead of console.log(...), you probably want to do upload_to_server(...)
  // or something to that effect.
  console.log(amplitude.getInstance().options.deviceId);
});

When a user logs in, be sure to send the same Amplitude deviceID in your Identify call. Otherwise, Amplitude creates two separate users: one for your anonymous user, and another for your logged-in user. This is handled automatically on mobile.

Track

If you’re not familiar with the Segment Specs, take a look to understand what the Track method does. Amplitude supports several special properties, all of which are included in the following example:

// On server-side
analytics.track({
  "userId": "123",
  "event": "Subscription Started",
  "properties": {
    "plan": "Basic",
    "revenue": "32"
  },
  "context": {
    "ip": "8.8.8.8",
    "device": {
      "id": "2b6f0cc904d137be2e1730235f5664094b831186",
      "model": "iPhone 10",
      "brand": "Apple",
      "manufacturer": "Apple"
    },
    "os": {
      "name": "iOS",
      "version": "9.1"
    },
    "network": {
      "carrier": "T-Mobile"
    },
    "app": {
      "version": "3.5.1"
    },
    "location": {
      "country": "United States",
      "region": "California",
      "city": "San Francisco",
      "latitude": "37.7672319",
      "longitude": "-122.4021353"
    },
    "locale": {
      "language": "en-us"
    }
  }
})

Segment sends many of these properties automatically if you use Analytics.js, Segment’s iOS source, or Segment’s Android source.

For a complete list of special context keys see Segment’s Common fields spec.

Log Revenue V2

Segment’s iOS and Android sources can send revenue using Amplitude’s preferred logRevenueV2 method. Segment sets Amplitude’s special revenue properties, such as revenueType and productIdentifier, which are used in Amplitude’s Revenue Analysis and Revenue LTV charts. Segment uses the Amplitude eventProperties field to send any properties not mapped to Amplitude’s special properties.

* If properties.price is not present, Segment uses revenue instead, and sends that as price. In Segment’s iOS and Android components, if revenue isn’t present either, Segment does an additional fallback and sends the total.

Property names should be camelCase for Android implementations, and snake_case for iOS implementations.

Normalize all revenue data to your currency of choice before sending it to Amplitude.

Revenue

For Segment’s Analytics.js (device-mode), iOS, and Android sources, if you do not enable the preferred logRevenueV2 setting, Segment sends the data using the deprecated logRevenue methods (which still work). If you record events using this old setting, fields such as revenueType aren’t recorded in your events. This can reduce your ability to segment on those revenue events in the Amplitude platform.

In Segment’s Analytics.js, iOS and Android sources, if properties.price isn’t present, Segment falls back to revenue and sends that as price. The Segment iOS and Android sources also do an additional fallback to total, if revenue isn’t present either.

Order Completed

Segment recommends that you use the Order Completed event to track revenue with Amplitude. This event allows you to define a list of products that a user purchased in a single transaction, which is the best way to track purchases for sites that have a shopping cart system.

You can currently use this event only for data coming from a server or web source. An Order Completed event from mobile using our bundled Amplitude integration will work the same as our standard track event documented above.

Here’s an example of how you’d create an “Order Completed” event:

analytics.track({
  "userId": "e953c39d2597f0b8a79dd3c407baeb13bb58523a",
  "event": "Order Completed",
  "properties": {
    "checkoutId": "6727142daf49b93a601d3a31bc3d53aeae1d15ab",
    "orderId": "50314b8e9bcf000000000000",
    "affiliation": "Google Store",
    "total": 30,
    "revenue": 25,
    "shipping": 3,
    "tax": 2,
    "discount": 2.5,
    "coupon": "hasbros",
    "currency": "USD",
    "products": [
      {
        "productId": "507f1f77bcf86cd799439011",
        "sku": "45790-32",
        "name": "Monopoly: 3rd Edition",
        "price": 19,
        "quantity": 1,
        "category": "Games"
      },
      {
        "productId": "505bd76785ebb509fc183733",
        "sku": "46493-32",
        "name": "Uno Card Game",
        "price": 3,
        "quantity": 2,
        "category": "Games"
      }
    ]
  }
})

When you send an “Order Completed” event, an “Order Completed” event appears in Amplitude for that purchase. An Amplitude event called “Product Purchased” is also created for each product in the purchase. All event properties, except products, are sent as event_properties of the Amplitude “Order Completed” event. Information about each product is present only on the individual “Product Purchased” events.

Track Revenue Per Product

Amplitude has two different ways to track revenue associated with a multi-product purchase. You can choose which method you want to use using the Track Revenue Per Product destination setting.

If you disable the setting (“off”), Segment sends a single revenue event with the total amount purchased. Revenue data is added to the Amplitude “Order Completed” event. The “Product Purchased” events do not contain any native Amplitude revenue data.

If you enable the setting (“on”), Segment sends a single revenue event for each product that was purchased. Revenue data is added to each “Product Purchased” event, and the “Order Completed” event does not contain any native Amplitude revenue data.

Make sure you’re formatting your events using the Track method spec, and pass at minimum a revenue property, as well as a price and quantity property for each product in the products list.

Group

If you’re not familiar with the Segment Specs, take a look to understand what the Group method does.

The following example shows a Group call made from a server library:

// On server-side
analytics.group("some_group_id", {
  userId: "some_user_id",
  traits: {
    email: "the_group_email",
    some_other_property: "some_other_value",
  }
})

And this example shows a call made from a device-mode library that sends directly from the client:

// On client-side
analytics.group("some_group_id", {
  email: "the_group_email",
  some_other_property: "some_other_value",
})

Even if you don’t have an enterprise Amplitude account, or don’t have the Accounts add-on, Segment always adds groups as user_properties on a user record. As long as you specify the destination settings below, Segment adds a “group type” user property with a value of the “group value”.

To use Amplitude’s groups with Segment, you must enable the following destination settings and make sure you’re sending them the data values they need to function. These settings act as a mapping from Segment group traits to Amplitude group types and values.

• “Amplitude Group Type Trait”: This specifies what trait in your Group calls contains the Amplitude “group type”. In other words, it’s how you tell Segment which trait to use as the group type.

• “Amplitude Group Value Trait”: This specifies what trait in your Group calls contains the Amplitude “group value”. It’s how you tell Segment which trait to use as the group value.

For example, if you specified group_type as the “Amplitude Group Type Trait”, and name as the “Amplitude Group Value Trait”, then the example call below…

analytics.group("082108c8-f51e-485f-9d2d-b6ba57ee2c40", {
  group_type: "Organization",
  name: "ExampleCorp, LLC",
  employees: "20",
  email: "hello@example.com"
});

Associates the current user with the group with type "Organization" and value "ExampleCorp, LLC". On the device-mode version of the destination, that’s all that happens. On Android, and in cloud-mode, Segment sends the traits you pass (in this case, group_type, name, employees, and email) as group_properties of that group.

Segment requires that all Group calls provide a group ID. What you provide as group ID doesn’t matter, but you cannot leave group ID empty.

Legacy Group Behavior

If you do not provide “Amplitude Group Type/Value Trait”, or one of the traits was not provided in your Group call, then Segment associated the user with a group with the type “[Segment] Group” and with the value “(Group Id)”. No properties are associated with that group.

For example, the previous group call would associate the user with a group of type “[Segment] Group” and value “082108c8-f51e-485f-9d2d-b6ba57ee2c40”.

Alias

Segment’s Alias method maps to Amplitude’s usermap endpoint. Making a Segment Alias call allows you to associate a Segment user’s previousId with the user’s userId, or what Amplitude refers to, respectively, as a user_id and a global_user_id.

By default, Segment does NOT send Alias events to Amplitude. To forward Alias events from Segment, go to your Amplitude destination settings in the Segment web app, and set the Enable Alias setting to “on”.

Once enabled, Segment forwards Alias events from Segment’s servers only. This means that Alias events reach Amplitude only when you’re sending events from the client and have set your Amplitude instance’s connection mode to “Cloud Mode”, or are sending Alias events from a Segment server-side library (such as Node).

For more information, see the Segment Spec page for the Alias method.

Mapping Users

You can map a Segment user’s previousId to the user’s userId in Amplitude by invoking a Segment Alias method with an argument for each value.

The example Alias call below maps the previousId with the value of 123 to the userId with a value of 456 in Amplitude. Both user 123 and 456 still have separate user profiles, but the profiles get merged together when you look at the user’s behavior in Amplitude’s Cross Project view.

This kind of mapping is useful for users who have different ids across different Amplitude projects. The user’s user_ids act as child ids, and can all be mapped to a single global_user_id in Amplitude. This allows you to analyze the user’s aggregate behavior in Amplitude’s Cross Portfolio view.

analytics.alias({
  previousId: '123',
  userId: '456'
})

If you make an Alias call from the user’s device, you don’t need to explicitly pass a previousId. Segment device-mode Amplitude library sets the value of oldId to the value of the current user’s previous userId. The example calls below show how to make an Alias call to map the userId oldUserId to the new userId, finalUserId:

analytics.identify('oldUserId')
analytics.alias('finalUserId')
// remember to identify with the new `userId`
analytics.identify('finalUserId')

Unmapping Users

You can also unmap users, for example if you aliased them in error. To unmap a user, pass the user’s previousId as an integration-specific option. The example Alias call below sends a request to Amplitude that unlinks user 123 from all global_user_ids it was previously associated with.

analytics.alias({
  userId: '456',
  integrations: {
    Amplitude: {
      unmap: '123'
    }
  }
})

Advanced Amplitude features

sessionId

Segment doesn’t have a concept for a session.

Device-mode calls to Amplitude include session information because Segment bundles Amplitude’s SDK. To set up the same sessionId for cloud-mode calls to Amplitude, you must explicitly set the session_id as an integration-specific option, as in the example below.

{
  "userId": "1234",
  "traits": {
    "email": "someone@somewhere.com",
    "name": "Some Person",
    "industry": "Technology"
  },
  "context": {
    "ip": "00.0.00.00"
  },
  "timestamp": "2016-10-17T00:30:08.276Z",
  "integrations": {
    "Amplitude": {
      "session_id": "<Timestamp>"
    }
  }
}

You must pass the start time of a session as <Timestamp>.

When you pass a timestamp value from the session_id it must be in Unix format, otherwise it generates an error when it is delivered to Amplitude. For example, a date of January 1, 2020 and 9:30am UTC would be written as 2020-12-07T19:33:44+00:00 in ISO 8601, but 1577871000 in Unix epoch time. There are many tools and libraries available to help you convert your timestamps.

Setting event-level groups using Track calls

You can use Amplitude to set event-level groups. This means the group designation only applies for the specific event you are recording, and doesn’t persist on the user. To specify these groups, provide an integration-specific groups property with key-value pairs corresponding to the groupType-groupValue pairs you want to appear in Amplitude.

analytics.track("Clicked Benefits Dropdown", {
  dropdownColor: "blue"
},
{
  integrations: {
    Amplitude: {
      groups: {
        onboarding_cohort: "Summer 2016"
      }
    }
  }
});

Setting Amplitude Version User Property using Identify calls

If you are sending event data to Amplitude in cloud-mode (through the Segment servers) and want to use the Amplitude Release objects feature, you can set the app version user property as in the example below. Make sure to send the version details in the context object and not as a standard user trait.

analytics.identify('testUser', {
  email: 'john@example.com',
  name: 'John Doe'
}, {
  context: {
    app: { 'version': "<value_here>", }
  }
});

Legacy group assignment using Identify calls

You can associate a user with a group by providing an integration-specific groups property, with the keys being Amplitude “group type” and the values being Amplitude “group value”:

analytics.identify('user-id', {
  email: 'bill@example.com',
  country: 'USA'
}, {
  integrations: {
    Amplitude: {
      groups: {
        sports: ['basketball', 'tennis']
      }
    }
  }
});

This Identify event creates a new user (or updates an existing user) in Amplitude and sets their sport groups as basketball and tennis.

Location Tracking

This feature is only supported when you use the Segment iOS and Android sources, with Amplitude in device-mode.

This feature defaults to enabled. If a user granted your app location permissions, enable this setting so that the SDK will also grab the location of the user. Amplitude does not prompt the user for location permission, so your app must explicitly prompt to ask permission.

On iOS, the user’s location is only recorded once per session. If you need to force update the location in Amplitude, you can use the native method updateLocation (iOS only) referenced in Amplitude’s iOS SDK documentation . When you call enableLocationListening on the iOS SDK, it forces the SDK to update (and overwrite) the initial location that was cached during app startup.

On Android, when enabled, this setting adds a latitude and longitude property to each Track call, which reflecte where geographically the event was triggered.

Even if you disable location listening, Amplitude’s ingestion layer attempts to determine the user’s location from their IP address. To prevent tracking of any location information, contact your Amplitude CSM to disable all location tracking.

Set AdvertisingId for DeviceId

This feature is only supported when you use the Segment iOS and Android sources, with Amplitude in device-mode.

Segment supports Amplitude’s useAdvertisingIdForDeviceId method. For iOS, this allows you to use the advertisingIdentifier instead of identifierForVendor as the Device ID in Amplitude. This is useful for tying together data from advertising campaigns to analytics data.

On Android, this setting relies on Google’s Advertising ID. This method can return null if a Device ID has not been generated yet.

Increment Traits

This increments a user property by some numerical value. If the user property does not have a value set yet, Segment initializes it with a value of 0 before being incremented.

When you configure this setting (under traitsToIncrement), Segment calls Amplitude’s add method on the Amplitude identity instance for each trait passed in an Identify call. The trait must have a numerical value so it can be incremented.

Set trait once

Supported on all components.

This sets the value of a user property only once. Subsequent operations on that user property will be ignored. Configure the trait you would like to setOnce in the integration settings pane. Segment then checks the traits object for the configured trait when identify is called.

Log out of sessions

This feature is only supported when you use the Segment iOS and Android sources, with Amplitude in device-mode.

Out-of-session events have a session_id of -1, and are not considered part of the current session. This means they do not extend the current session. This might be useful if you are logging events triggered by push notifications, for example. To set an out of session event, send the a Track call with an integration option property outOfSession set to true.

The example below shows how you might set this on iOS:

[[SEGAnalytics sharedAnalytics]
  track: @"Push Notification Viewed"
  properties: nil
  options: @{
    @"integrations": @{
      @"Amplitude": @{
        @"outOfSession": @YES
      }
    }
  }
];

The following example shows how you might set this on Android:

Properties properties = new Properties();
Map<String, Object> amplitudeOptions = new HashMap<>();
amplitudeOptions.put("outOfSession", true);

Options options = new Options().setIntegrationOptions("Amplitude", amplitudeOptions);
Analytics.with(context).track("Push Notification Viewed", properties, options);

Flush

The Segment mobile device-mode bundles for Amplitude map Segment’s flush method to Amplitude’s uploadEvents method.

Reset

The Segment mobile device-mode bundles for Amplitude support logging out users in Amplitude using Segment’s reset method. You don’t need to alias users, as Amplitude merges user data on the backend so that any events up to that point from the same client are tracked under the same user.

Segment logs the user out by setting the userId to nil and calling Amplitude’s method to regenerate a new deviceId.

Troubleshooting

Instrumentation Explorer

Amplitude offers a robust Instrumentation Explorer/Debugger. This is a helpful Chrome extension that shows each page interaction that sends an event to Amplitude.

I Don’t See My Data In Amplitude

If you don’t your data arrive in Amplitude, see the Analytics.js guide to validating data being transmitted to your third-party destination.

Also, Amplitude doesn’t support fields with a value of an array with nested arrays.

For more information on the Amplitude/Segment integration, view Amplitude’s Import Segment Data documentation.

Engage

You can send computed traits and audiences generated using Engage to this destination as a user property. To learn more about Engage, schedule a demo.

For user-property destinations, an identify call is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property order_completed_last_30days: true. When the user no longer satisfies this condition (for example, it’s been more than 30 days since their last order), Engage sets that value to false.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.