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.

Our Amplitude destination code is open sourced on Github. Feel free to check it out: iOS, Android and JS. Our server-side integration is not open-source.

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

This document was last updated on March 28, 2018. If you notice any gaps, outdated information or simply want to leave some feedback to help us improve our documentation, please let us know!

Getting Started

The first step is to make sure Amplitude supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.

1. From your Segment UI’s Destinations page click on “Add Destination”.

2. Search for “Amplitude” within the Destinations Catalog and confirm the Source you’d like to connect to.

3. Drop in your Amplitude API key.

   You can find the your Amplitude API key from the Amplitude project settings. Find the project you want to send data to. The API key you should add to your Segment destination settings is the API key of the project you want to send data to. It should be a randomized, 32-character long string of numbers and letters.

4. If you’ve included Segment’s snippet on your page, then Amplitude’s SDK will be loaded on your page. You can use Segment’s client-side SDK to begin sending events right away.

   On server-side, you can begin sending events to Segment right away; they will appear in your Amplitude project.

Page and Screen

If you haven’t had a chance to review our spec, please take a look to understand what the Page and Screen method does. By default, Segment won’t send these standard calls to Amplitude. However, you can enable them with the destination settings outlined below, which you can find under the “Optional Settings” tab. An example call would look like:

// On server-side -- on client-side, you can leave out the `userId`.
analytics.page({
  userId: "some_user_id",
  category: "Merchant",
  name: "Settings",
})

// Also server-side -- `screen` calls are not possible from the client-side.
analytics.screen({
  userId: "some_user_id",
  category: "Merchant",
  name: "Settings",
})

page and screen calls have two important properties: a name, such as “Settings”, and a category, such as “Merchant”. How you pass these properties will depend on the Segment library you’re using. Segment will determine when to send events to Amplitude based on the settings you’ve enabled, and whether the call has a name or category included.

If you enable more than one of the following settings, multiple events may be sent for the same call.

Client and Server

On the client and server, you can use the following settings:

iOS

On iOS, you can use these settings:

The difference between “Track All Pages” and “Track All Pages V2” is that “Track All Pages V2” will include the scren name and category as event properties. You probably want to use “Track All Pages V2”.

Android

These settings are available for Android sources:

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

Identify

If you haven’t had a chance to review our spec, please 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@sivers.org",
    "name": "Derek Sivers",
    "industry": "Music"
  }
})

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

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.

Caveats about Amplitude Device IDs

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() {
  // Instead of console.log(...), you probably want to do upload_to_server(...)
  // or something to that affect.
  console.log(amplitude.options.deviceId);
});

Similarly, when a user logs in, be sure to send the same Amplitude device_id along the process. Otherwise, Amplitude will create two separate users: one for your anonymous user, and another for your logged-in user. This will be handled automatically on mobile.

On client-side, “Prefer Anonymous ID for Device ID” will set the Amplitude device_id from the current user’s anonymousId; otherwise, Amplitude’s default behavior will determine the device_id.

On server-side, Segment uses context.device.id as the Amplitude device_id. If there is no context.device.id, Segment will use anonymousId. You can use the optional setting “Prefer Anonymous ID for Device ID” to flip this behavior.

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

Track

If you haven’t had a chance to review our spec, please take a look to understand what the Track method does. Amplitude supports a number of 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 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"
    }
  }
})

Many of these properties will automatically be sent for you if you use one of Segment’s browser or mobile libraries such as Analytics.js, iOS, or Android.

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

Revenue

If you use the Track method 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.

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

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

If the “logRevenueV2” option 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

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.

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.

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

Please ensure you are 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.

Group

If you haven’t had a chance to review our spec, please take a look to understand what the Group method does. Note that groups are an enterprise-only feature in Amplitude, and are only available if you’ve purchased the Accounts add-on. An example call would look like:

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

// 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 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. They 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 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". On client-side, that’s all that happens. On server-side, the traits you pass will (in this case, industry, name, employees, and email) will be provided as group_properties of that group.

What you provide as group ID doesn’t matter, but Segment requires that all .group() calls provide a group ID; 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 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.

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

Advanced Functionality

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 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 you disable location listening, Amplitude’s server side ingestion layer will attempt to determine the user’s location from their 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. This is useful for tying together data from advertising campaigns to analytics data. Note that Apple prohibits the use of advertisingIdentifier if your app does not have advertising.

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 server-side, 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. The trait should have a numerical value to increment on.

Set trait once

Supported via our server-side, 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);

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.

Personas

You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.

For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true, and when this user no longer satisfies we will set that value to false.

When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.

Supported Sources and Connection Modes

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.

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

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)

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.

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

Traits To Increment

Server-Side and 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.

Traits to Set Once

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

Use AdvertisingId for DeviceId

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!