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. Feel free to check it out:

Good to know: This page is about the Amplitude Segment destination, which receives data from Segment. There’s also a page about the Amplitude Engage Segment source, which sends data to Segment!

In addition to the docs below, Amplitude created a integration guide.

To delete users based on GDPR regulations, you must include a secret key in the Secret Key setting of every Amplitude destination. You can find your Secret Key on the General Settings of your Amplitude project.

Getting Started

Before you start, make sure Amplitude supports the source type and connection mode you’ve chosen to implement. You can learn more about connection modes here.

Web Mobile Server
📱 Device-mode
☁️ Cloud-mode
  1. From the Segment web app, click Catalog.
  2. Search for “Amplitude” in the Catalog, select it, and choose which of your sources to connect the destination to.
  3. 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.

Important: If you enable more than one of the following settings, Segment might send multiple events for the same call.

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.)

Setting Name When events are sent to Amplitude Amplitude Event Name Example for {"name": "Settings", "category": "Merchant" }
Track Named Pages A page/screen name is provided Loaded/Viewed (Category) (Name) Page/Screen “Loaded Merchant Settings Page”
Track Categorized Pages A page/screen category is provided Loaded/Viewed (Category) Page/Screen “Loaded Merchant Page”
Track All Pages Always Loaded/Viewed a Page/Screen “Loaded a Page”

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.

Tip: These settings also apply to mobile Cloud-mode connections.

Event Type settings for iOS

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

Setting Name When events will be sent to Amplitude Amplitude Event Name Example for {"name": "Settings", "category": "Merchant" }
Track All Pages Always Viewed (Name) “Viewed Settings”
Track All Screens Always Loaded a Screen “Loaded a Screen”

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.

Setting Name When events will be sent to Amplitude Amplitude Event Name Example for {"name": "Settings", "category": "Merchant" }
Track Named Pages A screen name is provided Viewed (Category) (Name) Screen “Viewed Merchant Settings Screen”
Track Categorized Pages A screen category is provided Viewed (Category) Screen “Viewed Merchant Screen”
Track All Pages Always If a screen name is provided: Viewed (Name) Screen. Otherwise Loaded a Screen “Viewed Settings Screen”
Track All Screens Always Loaded a Screen “Loaded a Screen”

You can learn more about Page calls from our Page spec and Screen calls from our 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.

Library Default Fallback
A.js Generated by Amplitude anonymousId
Server-side context.device.id anonymousId
iOS Generated by Amplitude n/a
Android Generated by Amplitude n/a

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.

Library Default Fallback
A.js anonymousId Generated by Amplitude
Server-side anonymousId context.device.id

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.

Library Default Fallback
iOS anonymousId Generated by Amplitude
Android anonymousId Generated by Amplitude

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.

Library Priority (highest to lowest)
A.js Prefer Anonymous ID for Device ID
Set Device ID From URL Parameter amp_device_id (Device-mode only)
Device ID Generated by Amplitude
Server-side Prefer Anonymous ID for Device ID
context.device.id
iOS Use AdvertisingId for Device ID (Device-mode only)
Device ID Generated by Amplitude
Android Use AdvertisingId for Device ID (Device-mode only)
Device ID Generated by Amplitude

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 example below:

// 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.

Amplitude Property Segment Property Description
productId productId An identifier for the product.
quantity quantity The quantity of products purchased. Note: revenue = quantity * price.
price price or revenue (or total for mobile, see note below) The price of the products purchased, and this can be negative.
revenueType revenueType The type of revenue (e.g. tax, refund, income).
receiptSignature receiptSignature (Android only) The receipt signature.
receipt receipt This is required if you want to verify the revenue event.
eventProperties Any remaining properties A NSDictionary or Map of event properties to include in the revenue event.

* 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.

Note: Amplitude does not currently support currency conversion. You should 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.

Amplitude Property Segment Property Description
productId productId An identifier for the product.
quantity quantity The quantity of products purchased. Note: revenue = quantity * price.
price price (or revenue or total, see note below) The price of the products purchased, and this can be negative.
receipt receipt (mobile only) This is required to verify the revenue event.
receiptSignature receiptSignature (Android only) The receipt signature.
revenueType revenueType (cloud-mode only) The type of revenue (such as tax, refund, income).
revenue revenue (cloud-mode only) The revenue collected.
eventProperties Any remaining properties (cloud-mode only) A NSDictionary or Map of event properties to include in the revenue event.

^ In Segment’s Analytics.js, iOS and Android sources, if properties.price is not 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.

Tip If your site allows users to perform a single transaction with multiple products (such as a shopping cart checkout), we recommend that you use an Order Completed event to track revenue with Amplitude.

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 are using 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.

Groups are an enterprise-only feature in Amplitude, and are only available if you’ve purchased the Accounts add-on.

The example below 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 the example below 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 both client-based and server-based Alias calls. Segment processes all Alias calls before sending them to Amplitude, so you won’t see a usermap request to Amplitude if you check your browser’s Network activity after making a Segment Alias call.

note “”
To use Alias, you must have the Amplitude Portfolio add-on enabled.

For more information, see the Segment Spec page for the Alias method and the Amplitude usermap documentation.

Segment identifier name Equivalent Amplitude identifier name
previousId user_id
userId global_user_id

Mapping Users

Mapping a Segment user’s previousId to the user’s userId in Amplitude is as simple as 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 or else 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. Be sure that you 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

Note: Segment will continue to support this behavior, however the preferred way to associate a user with a group in Amplitude is to use a Group call.

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) as documented here. 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 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.

Apple prohibits the use of advertisingIdentifier if you did not say that your app has advertising in your App Store application.

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 example below 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 do not need to aliasing 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.

Amplitude/Segment FAQ

Have a question about the Amplitude/Segment integration that’s already been answered? Take a look at Amplitude’s FAQ for common issues integrating Amplitude with Segment.

I Don’t See My Data In Amplitude

If you aren’t seeing your data arrive in Amplitude, we recommend you start by taking a look at our Analytics.js Guide on validating data being transmitted to your third-party destination.

Personas

You can send computed traits and audiences generated using Segment Personas to this destination as a user property. To learn more about Personas, contact us for 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, Personas 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), Personas sets that value to false.

When you first create an audience, Personas 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.

API Key

You can find your API Key on your Amplitude Settings page.

Append Fields To Event Properties

Web Device-mode only. Configure event fields to be appended to event_props for all track calls. For example, entering context.page.title on the left and pageTitle on the right will set the value of context.page.title at event_properties.pageTitle.

Batch Events

If true, events are batched together and uploaded only when the number of unsent events is greater than or equal to eventUploadThreshold or after eventUploadPeriodMillis milliseconds have passed since the first unsent event was logged.

Enable Alias

Server-Side Only. Enabling this setting allows your Amplitude destination instance to send alias events to Amplitude’s usermap endpoint. By default, Segment’s Amplitude integration does not support alias, so when this setting is disabled, your Segment Amplitude destination will reject alias events as unsupported.

Enable Location Listening

Mobile Only. If a user has granted your app location permissions, enable this setting so that the SDK will also grab the location of the user. Amplitude will never prompt the user for location permission, so this must be done by your app.

Event Upload Period Millis (for batching events)

Amount of time in milliseconds that the SDK waits before uploading events if batchEvents is true.

Event Upload Threshold (for batching events)

Minimum number of events to batch together per request if batchEvents is true.

Force Https

If true, the events will always be uploaded to HTTPS endpoint. Otherwise the SDK will use the embedding site’s protocol.

Group Type Trait

What trait Segment should use as your Amplitude “group type” in group calls. If, for example, you set this to be industry, then traits["industry"] will be sent as groupType to Amplitude.

Group Value Trait

What trait Segment should use as your Amplitude “group value” in group calls. If, for example, you set this to be plan, then traits["plan"] will be sent as groupValue to Amplitude.

Map Query Params to Custom Property

When sending data via server side or Cloud Mode, you can send the custom query params that are automatically collected by analytics.js (or whatever you manually send under context.page.search), by entering a custom property name you would like to map that under on the left hand side. On the right hand side, please choose whether you want the query params to be set on the user profile or event metadata level. Whatever you put on the left hand side we will map the entire query parameters string from the context.page.search.

Prefer Anonymous ID for Device ID

By default, Segment will use context.device.id as the Amplitude device_id, using anonymousId if context.device.id isn’t present.

Enable this setting to flip this behavior; anonymousId will be used as the device_id, falling back to context.device.id if it isn’t present.

In browsers, enabling this setting means the user’s anonymous ID, which you can set using analytics.user().anonymousId('ID_GOES_HERE'), will be set as the Amplitude device ID. Otherwise, Amplitude’s default logic for determining device IDs will be used.

Save Referrer, URL Params, GCLID Once Per Session

If true then includeGclid, includeReferrer, and includeUtm will only track their respective properties once per session. New values that come in during the middle of the user’s session will be ignored. Set to false to always capture new values.

Secret Key

Your Amplitude Secret Key (Only needed for user deletion)

Send Custom Language and Country Properties

Enable this option if you want to send additional ‘language’ and ‘country’ parameters inside of event_properties. This is separate from the language and country collected from your user’s context. (For example, you want to send the language that a video is played in). You can send these in your properties, for example: analytics.track('Video Played', {language: 'Japanese'});

Send To Batch Endpoint

Server-Side Only. If true, events are sent to Amplitude’s batch endpoint rather than to their httpapi endpoint. Because Amplitude’s batch endpoint throttles traffic less restrictively than the Amplitude httpapi endpoint, enabling this setting may help to reduce 429s - or throttling errors - from Amplitude. Amplitude’s batch endpoint throttles data only when the rate of events sharing the same user_id or device_id exceeds an average of 1,000/second over a 30-second period. More information about Amplitude’s throttling is available here in their docs: https://developers.amplitude.com/#429s-in-depth.

Set Device ID From URL Parameter amp_device_id

If true, the SDK will parse device ID values from url parameter amp_device_id if available.

Track All Pages to Amplitude

This will track Loaded a Page events to Amplitude for all page method calls. We keep this disabled by default, since Amplitude isn’t generally used for pageview tracking.

Track All Screens

Mobile only. Sends a “Loaded Screen” event and the screen name as a property to Amplitude. Moving forward, this is the preferred method of tracking screen events in Amplitude.

Track Categorized Pages to Amplitude

This will track events to Amplitude for page method calls that have a category associated with them. For example page('Docs', 'Index') would translate to Viewed Docs Page.

Track GCLID

If true, captures the gclid url parameter as well as the user’s initial_gclid via a set once operation.

Track Named Pages to Amplitude

This will track events to Amplitude for page method calls that have a name associated with them. For example page('Signup') would translate to Viewed Signup Page. Remember that name includes category, so page('Conversion', 'Signup') would translate to a Viewed Conversion Signup Page event in Amplitude.

Track Referrer to Amplitude

Enabling this will send referrer information as a user property to Amplitude when you call Segment’s page method.

Track Revenue Per Product

Client and server only. This setting allows you to specify whether you would like to track an Amplitude Revenue event per individual product in a user transaction or a single Revenue event for the combined revenue of all products. This setting is only relevant if you are using our eCommerce spec and passing us an Order Completed event with a list of products.

Track Session Events to Amplitude

(Optional) This enables the sending of start and end session events for mobile products. Amplitude’s libraries track sessions automatically and this option is not necessary for session tracking.

Track UTM Properties to Amplitude.

If Amplitude is connected in device-mode this will send the UTM properties found in the querystring. If Amplitude is connected in cloud-mode this will send the UTM properties found in the context.campaign object. (Note: The Analytics.js library automatically collects the context.campaign object)

Track products once

Beta feature Amplitude recently added support to submit an array of products on “Order Completed” events. If this setting is set to true, we will send all the products in one single event to Amplitude.

Traits To Increment

Configure trait to increment on identify. If the trait is present, it will increment the trait given the numerical value passed in when you call identify with the trait.

Traits to Append

Server-Side and Mobile Only. Configure values to be appended to the user property array via identify.traits.

Traits to Prepend

Server-Side and Mobile Only. Configure values to be prepended to the user property array via identify.traits.

Traits to Set Once

Server-Side and Mobile Only. Configure values to be set only once via identify.traits.

Unset Params Referrer On New Session

If false, the existing referrer and utm_parameter values will be carried through each new session. If set to true, the referrer and utm_parameter user properties, which include referrer, utm_source, utm_medium, utm_campaign, utm_term, and utm_content, will be set to null upon instantiating a new session. Note: This only works if Track Referrer or Track UTM Properties to Amplitude are set to true.

Use AdvertisingId for DeviceId

Mobile Only (will not work in cloud-mode). Allows users to use advertisingIdentifier instead of identifierForVendor as the Device ID.

Use Log Revenue V2 API

Use Amplitude’s logRevenueV2 API, which allows for the tracking of event properties with the revenue event. Track an event with “price” and “quantity” properties, and it will log total revenue = price * quantity. You may also set a revenueType property to designate the type of revenue (ex: purchase, refund, etc). Negative prices can be used to indicate revenue lost.

Version Name

Optional. You can assign a version name for your page, and we’ll send it to Amplitude for more detailed events.

This page was last modified: 18 Dec 2020



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account