Amplitude Destination

Segment makes it easy to send your data to Amplitude (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Amplitude in the format they understand. Learn more about how to use Amplitude with Segment.

Our Amplitude destination code is open sourced on Github. Feel free to check it out: iOS, Android, JS.

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

Getting Started

Once you’re tracking data to one of our sources, toggle Amplitude on in your Segment destination catalog, and add your application’s Amplitude API Key in the Segment destination settings. You can find your Amplitude API Key in your Amplitude app settings.


Page and Screen

By default, Segment won’t send standard page or screen calls to Amplitude. However, you can enable sending page and screen calls with the following destination settings, which you can find under the “Advanced Options” tab.

Important Note: If you enable more than one of the following settings, multiple events may be sent for the same page or screen call.

  • “Track All Pages V2”: Supported via our iOS and Android components.

    When enabled, this setting will override any other page settings and will trigger a “Loaded a Screen” event to Amplitude on each screen view. We’ll also pass in the screen name as a property so you can create funnels in Amplitude using the screen name.

  • “Track Named Pages to Amplitude”: Supported via our Android, Server and Web components.

    Any time you call page and provide a name, an event will be sent. In Amplitude, the event type will be “Loaded (Category) (Name) Page” (e.g. “Viewed Customer Settings Page”) or “Loaded (Name) Screen” when you trigger screen.

    On Web, if you don’t provide a category, the type will be “Loaded (Name) page”, so a call to analytics.page("home") will create a “viewed home page” event.

  • “Track Categorized Pages to Amplitude”: Supported via our Android, Server, and Web components.

    Any time you call page or screen and provide a category, an event will be sent. The event type will be “Viewed (Category) Page”, or “Viewed (Category) Screen” on Android.

  • “Track All Pages to Amplitude”: Supported via our iOS, Android, Server, and Web components.

    Any time you call page, an event will be sent to Amplitude. The event type will be “Loaded a Page”.

    On Android, a screen event will trigger a “Viewed (name) Screen” event.

    Note: Our iOS component does not behave like the others. Rather, it will send a track named page to Amplitude in the format of “Viewed (Screen Name)”. For this reason, we recommend using the Track All Pages V2 setting.

You can learn more about page calls from our page spec and screen calls from our screen spec.

Identify

When you call identify, we’ll set the userId as the Amplitude user ID, and set any traits you provide as Amplitude custom user_properties.

Important: If you’re using a server-side library or the Segment HTTP API to send events or traits about anonymous visitors, Amplitude won’t automatically be able to identify that anonymous user as being the same person when they log in. To have Amplitude connect the dots, when you call .identify() on user log-in, you should include both the anonymousId you were using before the user logged in, as well as their userId.

(If you’re using the Segment client-side JavaScript or our bundled SDK, the previous note is irrelevant to you, because Segment will automatically handle anonymousId for you.)

If you’re using our HTTP API, the request for an identify call will look like this:

{
  "userId": "123",
  "anonymousId": "a80b66d5-b86d-41bd-866f-fe04ee7841af",
  "traits": {
    "email": "derek@sivers.org",
    "name": "Derek Sivers",
    "industry": "Music"
  }
}

Note: On server-side, Segment will send device_id as context.device.id or, if one is not present, as anonymousId as shown in our Amplitude destination code.

For Amplitude to associate both client-side and server-side activity with the same user, you will need to pass the same deviceId to Amplitude. Otherwise, Amplitude will create two users - one associated with your deviceId and another user associated with your Segment anonymousId.

You can grab deviceId from Amplitude on the client-side to send server-side by calling this method within the ready function on the client-side to send server-side:

analytics.ready(function() {
  console.log(amplitude.options.deviceId);
});

For server-side libraries check out the identify section in the sources you’re using.

Group

You can use the group call to associate users with Amplitude groups. Note that groups are an enterprise-only feature in Amplitude, and are only available if you’ve purchased the Accounts add-on.

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

To use Amplitude’s groups with Segment, you must enable the following destination settings and provide them with the appropriate values:

  • “Amplitude Group Type Trait”: This specifies what trait in your .group() calls will contain the Amplitude “group type”. In other words, it’s how you tell Segment which trait should be used as the group type.

  • “Amplitude Group Value Trait”: This specifies what trait in your .group() calls will contain the Amplitude “group value”. It’s how you tell Segment which trait should be used as the group value.

For example, if you specified industry as the “Amplitude Group Type Trait”, and name as the “Amplitude Group Value Trait”, then the following call:

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

Would associate the current user with the group with type "Placeholding" and value "ExampleCorp, LLC". industry, name, employees, and email will be provided as group_properties of that group. What you pass as the group ID doesn’t matter in this case, but Segment requires that all .group() calls provide a group ID.

Legacy Group Behavior

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

Track

Amplitude’s main goal is to help you understand your user’s behavior. To accomplish that, you’ll want to track your user’s actions.

Special Properties

Amplitude supports a bunch of special properties, all of which are included in the example Segment track call below. The example shows the JSON object you’d need to use our HTTP API, but the same structure applies for any of our server-side libraries.

Note: For the special properties below you don’t need to manually map them if you use the out-of-the-box bundled client-side tracking in Analytics.js, iOS, or Android.

{
  "userId":"123",
  "event":"Subscription Started",
  "properties":{
    "plan":"Basic",
    "revenue":"32"
  },
  "context":{
    "ip":"8.8.8.8",
    "device":{
      "id":"2b6f0cc904d137be2e1730235f5664094b831186",
      "model":"iPhone 6",
      "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"
    }
  }
}

For a complete list of special context keys see our common fields spec.

Revenue

If you call track from the client side, with a property labeled revenue, we’ll call Amplitude.logRevenue with that amount (assuming the value is a number). On iOS and Android, total, if present, will be sent via logRevenue if revenue isn’t provided. See Log Revenue V2 below for more.

From the server, revenue is simply mapped to revenue as Amplitude expects.

Note: If your site allows for users to perform a single transaction with multiple different products (such as a shopping cart checkout), we recommend using an Order Completed event to track revenue with Amplitude.

Log Revenue V2

Our iOS and Android components support sending revenue via Amplitude’s preferred trackLogRevenueV2 method. Segment will set Amplitude’s special revenue properties, such as revenueType and productIdentifier which are used in Amplitude’s Revenue Analysis and Revenue LTV charts. Any properties not mapped to Amplitude’s special properties will be sent via the Amplitude eventProperties field.

Amplitude PropertySegment PropertyDescription
productIdproductIdAn identifier for the product.
quantityquantityThe quantity of products purchased. Note: revenue = quantity * price.
pricerevenue or total^The price of the products purchased, and this can be negative.
revenueTyperevenueTypeThe type of revenue (e.g. tax, refund, income).
receiptreceiptThis is required if you want to verify the revenue event.
eventPropertiesAny remaining propertiesA NSDictionary or Map of event properties to include in the revenue event.

^ If properties.price is not present, Segment will look for either revenue or total and send this as the price in Amplituide. If both revenue and total are passed in, Segment will send revenue over total as the price.

Keep in mind that property names should be camelCase for Android implementations and snake_case for iOS implementations.

If logRevenueV2 is not enabled, the existing logRevenue methods still work but are deprecated. Fields such as revenueType will be missing from events logged with the old methods, so the ability to segment on those revenue events will be limited in the Amplitude platform.

Note: Amplitude currently does not support currency conversion. All revenue data should be normalized to your currency of choice, before being sent to Amplitude.

Order Completed

Note: This event’s functionality is currently only available for data originating 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.

To track revenue with Amplitude, we recommend using our Order Completed event. This event allows you to define a list of products that a user purchased in a transaction. The need for this functionality is most applicable to sites that have a shopping cart experience.

When you send an “Order Completed” event, an “Order Completed” event will appear in Amplitude for that purchase. In addition, an Amplitude event called “Product Purchased” will be created for each product in the purchase. All event properties, except products, will be event_properties of the Amplitude “Order Completed” event. Information about each product will be present only on the individual “Product Purchased” events.

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

  1. You can log a single revenue event with the total amount purchased. If “Track Revenue Per Product” is turned off, then this method will be used. Revenue data will be added to the Amplitude “Order Completed” event. The “Product Purchased” events will not have any native Amplitude revenue data.

  2. You can log a single revenue event for each product that was purchased. If “Track Revenue Per Product” is turned on, then this method will be used. Revenue data will be added to each “Product Purchased” event, and the “Order Completed” event will not have any native Amplitude revenue data.

Note: The event_properties for “Order Completed” and “Product Purchased” will be unaffected by whether per-product revenue tracking is enabled. You can always find properties you specified as per the “Order Completed” e-Commerce spec in the event_properties of the “Product Purchased” event if it’s specific to a product, or in “Order Completed” if it’s related to the entire purchase. But Amplitude will not natively recognize these event_properties as being related to revenue.

Either way you set “Track Revenue Per Product”, please ensure you are closely adhering to our event spec and pass at minimum a revenue property, as well as a price and quantity property for each product in the products list.

Flush

Our mobile components map Segment’s flush method to Amplitude’s uploadEvents method.

Reset

Our mobile components support logging out users in Amplitude via Segment’s reset method. There is no need to worry about aliasing users, as Amplitude will merge user data on the backend so that any events up to that point from the same client will be tracked under the same user.

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

Advanced Functionality

deviceId

To grab the value for the deviceId from Amplitude, you can use a ready function on the client like so:

analytics.ready(function() {
  console.log(amplitude.options.deviceId);
});

You will then pass this to the context.device.id property. If you need to set this server-side, you will need to send in the value for the deviceId to your server and have the server pass it through the context.device.id.

When sending device_id to Amplitude, Segment will use context.device.id if it’s available. If it isn’t, then anonymousId will be used instead.

sessionId

Segment doesn’t have a concept for a session. Client-side calls to Amplitude will include session information since we are bundling Amplitude’s SDK. To set up the same sessionId for server-side calls to Amplitude, you will have to explicitly set the session_id as an integration-specific option like so:

{
  "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 will need to pass the start time of a session as <Timestamp>.

Setting groups via .track() or .identify()

Setting event-level groups via .track()

Amplitude supports setting event-level groups, meaning the group designation only applies for the specific event being logged and does not persist on the user. To specify these groups, provide an integration-specific groups property with key-value pairs corresponding to groupType-groupValue pairs you want to appear in Amplitude:

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

Legacy group assignment via .identify()

Note: While this behavior will continue to be supported, the recommended 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 would create or update a new user in Amplitude and set basketball and tennis as their sport groups.

Location Tracking

Supported via our iOS and Android components.

Defaults to enabled. 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.

The user’s location is only fetched once per session on iOS. If you need to force update the location in Amplitude, you can leverage the native method updateLocation (iOS only) as documented here. Also note that calling enableLocationListening on the iOS SDK forces the SDK to update the initial location that was cached during app startup.

On Android, when enabled, this setting adds a latitude and longitude property to each track event reflecting where geographically the event was triggered.

Please take note that even if the you disable location listening, Amplitude’s server side ingestion layer will reverse look up location info using the ip address. If you would like to block all location information from being tracked, please reach out to your CSM at amplitude to disable all location tracking.

Set AdvertisingId for DeviceId

Supported via our iOS and Android components.

Segment supports Amplitude’s useAdvertisingIdForDeviceId method. For iOS, this will allow you to use the advertisingIdentifier instead of identifierForVendor as the Device ID in Amplitude. Apple prohibits the use of advertisingIdentifier if your app does not have advertising. 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

Supported via our iOS and Android components.

This will increment a user property by some numerical value. If the user property does not have a value set yet, it will be initialized to 0 before being incremented.

For each trait passed in identify, if it is configured in the settings panel under traitsToIncrement, Segment calls Amplitude’s add method on the Amplitude identity instance. Keep in mind that the trait should have a numerical value to increment on.

Set trait once

Supported via our iOS and Android 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

Supported via our iOS and Android components.

Out-of-session events have a session_id of -1 and are not considered part of the current session, meaning 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, pass in true for the key outOfSession on a track call via the integration specific option.

iOS Example:

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

Android Example:

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

Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

We offer an optional Cloud-based Connection Mode for Web data with Amplitude. As a reminder, this removes the Amplitude javascript library from your site, improving performance. However, there are a few disparities between the Cloud-based and Device-based connection modes to keep in mind brefore enabling it in the Segment app. When you enable the Cloud-based destination mode, here’s what happens:

  • Segment's server-side Amplitude integration now respects "Track Named/Categorized/All Pages to Amplitude" settings (accessible in the Advanced Settings pane). This makes for a more consistent tracking experience across all platforms. If you are analyzing on page and screen views in Amplitude, be sure to enable these options before upgrading.

Segment offers an optional Device-based Connection Mode for Mobile data with Amplitude. If you’d like to use those features that require client-based functionality, follow the steps above to ensure you have packaged the Amplitude SDK with Segment’s.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

API Key

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

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.

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.

enableLocationListening

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.url. NOTE: Do not add more than one row. Adding more than one row in this setting will have no effect.

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.

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.

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.

trackAllPagesV2

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.

Track Revenue Per Product

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.

This will track UTM properties found in the querystring to Amplitude (only for browser).

traitsToIncrement

Mobile Only. 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.

traitsToSetOnce

Mobile Only. Configure values to be set only once via identify.traits.

useAdvertisingIdForDeviceId

Mobile Only. Allows users to use advertisingIdentifier instead of identifierForVendor as the Device ID.

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'});

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.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!