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

By default Segment doesn’t send standard page calls to Amplitude. However, if you include a name argument in the call we do generate an event.

Learn more about page settings for Amplitude. You can adjust these settings under the Advanced Options tab inside the Amplitude destination settings.

Also, named page calls like analytics.page('Home') will show up in Amplitude as an event called Viewed Home Page.

Screen

Screen calls work very similarly to page calls. By default Segment doesn’t send standard screen calls to Amplitude. However, if you include a name argument in the call we do generate an event.

Learn more about screen settings for Amplitude. You can adjust these settings under the Advanced Options tab inside the Amplitude destination settings.

Also, named screen calls like analytics.page('Home') will show up in Amplitude as an event called Viewed Home Screen.

Identify

The next thing you’ll want to do is identify and track your users, so that Amplitude can give you more user-centric data and insights into what your users are really doing.

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

Important: If you’re using a server-side library or the Segment HTTP API to send events or traits about anonymous visitors using an anonymousId Amplitude won’t be able to connect the dots between that anonymous visitor and an identified visitor automatically. To connect the dots, the first time you call identify with a userId you’ll need to include both the userId and the anonymousId you were using to record data about that user before they had a userId.

If you’re using our HTTP API the request will look like this:

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

Note: Amplitude first associates users based on context.device.id and if one is not present, by 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 by calling this method within the ready function on the client-side to send server-side:

analytics.ready(amplitude.options.deviceId);

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

Setting User Groups

Amplitude supports assigning users to groups and performing queries on those groups (please see the Amplitude docs for more info). Segment integrates with this functionality via the identify method.

To begin assigning users to groups, please pass an destination specific option called groups that is a dictionary of key/value pair(s) where each key is a groupType with the value being either a string or a list/array of strings representing the groupName(s).

Here is an example using Analytics.js:

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.

Group

You can use the group call to send group data to Amplitude. We will use pass the groupId as the value for “[Segment] << GROUPID >>”.

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

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.

Set Event Level Groups

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 unless you explicitly set it with setGroup. Please see the Amplitude docs for more info on this.

You can integrate with this functionality the same way you would if you were using our identify method to set a group at the user level. Simply pass an destination specific option called groups to the track event with a dictionary of key/value pair(s).

Please see our identify documentation for more specifics.

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.

Amplitude has two different ways to track revenue associated with a multi-product purchase:

You can log a single revenue event with the total amount purchased.
You can log a single revenue event for each product that was purchased.

We allow you to define this behavior using the Track Revenue Per Product integration setting.

Either way, please ensure you are closely adhering to our event spec and pass at minimum a revenue property and a price and quantity property for each product in the products list.

Finally, we will also trigger an Amplitude event called Product Purchased for each product in the products list. This will allow you to run product level reporting in Amplitude. Important: please check to ensure you are not already tracking your own Product Purchased event as these could conflict.

deviceId

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

analytics.ready(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 again, pass it through the context.device.id.

You can see here that we are setting Amplitude’s device_id to the context.device.id value, or the anonymousId when one is not present.

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 option property 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 the start time of a session passed as <timestamp>.

Supported Sources and Connection Modes

	Web	Mobile	Server
📱 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:

Server-side `identify` calls do not populate geolocation or timestamp (first and last seen) data. Amplitude has acknowledged and is developing a fix for this issue. In the interim, making a `track` call against an identified user will populate this data.
Amplitude's JavaScript SDK automatically generates `[Amplitude] Revenue` and `[Amplitude] Revenue (Unverified)` events in the Amplitude UI for all e-commerce `track` calls; server-side `track` do not automatically generate these events. Amplitude has acknowledged and is developing a fix for this issue. In the interim, be aware that analysis workflows that depend on these events may not work as expected with a disabled JavaScript SDK.
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.

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 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 Revenue Per Product

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 Referrer to Amplitude

Enabling this will send referrer information as a user property to Amplitude.

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.

Event Upload Period Millis (for batching events)

Amount of time in milliseconds that the SDK waits before uploading events 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.

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.

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 UTM Properties to Amplitude.

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

Event Upload Threshold (for batching events)

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

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 Session Events to Amplitude

This will enable the sending of start and end session events to Amplitude, which are no longer sent by default (only for mobile libraries).

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!