Amplitude Destination

Send data from RudderStack to Amplitude.

Amplitude is a comprehensive product analytics service for web and mobile platforms. 12,000+ companies use Amplitude to get marketing insights that drive product strategy, conversion, and customer retention.

RudderStack provides native libraries for Amplitude integrations for the following languages:

Getting started

The Amplitude destination supports alias, group, identify, page, screen, and track calls.

Before configuring Amplitude as a destination in RudderStack, confirm that your source is supported by Amplitude by referring to the table below. See connection modes for details.

Connection ModeWebMobileServer
Device modeSupportedSupported-
Cloud modeSupportedSupportedSupported

Connection settings

  1. If you haven’t already, first create a source in your RudderStack dashboard. Your source will be where you intend on sending data from. See Sources to learn more.
  2. Connect your source to Amplitude. You can do this directly from your source by navigating to Overview > Add Destination > Create a New Destination. Or, you can create the Amplitude destination first by navigating to Destinations > New Destination in your dashboard.
  3. Verify that your desired source is supported by Amplitude by referencing the Connection Modes table above.
  4. In the Connection Settings modal, provide the following information:
  • Name: Choose a name for your destination that will be easily identifiable later. Often, users like to include suffixes such as -prod, -dev, -testing to differentiate connection environments.
  • API key: To find your API key, go to your project in Amplitude and look in the general tab.
  • Residency server: Choose whether you want to connect to Amplitude’s Standard Server (US) or EU-based residency server.
  1. Choose the connection mode for each of your sources. This determines how your data will be routed from your source to your destination. Learn more about cloud mode vs. device mode here. We recommend using cloud mode as you will have access to Transformations and more reliable performance (compared to device mode).
  2. Press Continue to create your connection.
  3. Review the Configuration settings to ensure that you are OK with all of the default settings and/or to customize your settings further.
  4. Once you are happy with your settings, toggle the Enable switch at the top of your Configurations page to begin sending events to Amplitude.
info
See RudderStack SDK settings for more information on the SDK-specific settings you can configure while sending events to Amplitude.

Adding device mode integration

Once you add Amplitude as a destination in the RudderStack dashboard, follow these steps to add it to your project depending on your integration platform:

Configuration settings

Configure how you want your events to be sent to Amplitude directly in your RudderStack dashboard without touching any code.

Page settings

This section allows you to set how you want your page calls to be sent to Amplitude.

warning
Checking your event volume setup with Amplitude prior to configuring this section is recommended.

The following settings are only applicable when you’ve connected a source in web device mode.

FieldDescription
Track all pagesToggling this on will send all page events to Amplitude as Loaded a page.
Track categorized pagesWhen this setting is turned on:

  • If useNewPageEventNameFormat is set to true in the integration options, RudderStack sends events to Amplitude as Viewed {category} Page.
  • Otherwise, it sends the events to Amplitude as Viewed page {category}.
Track named pagesWhen this setting is turned on:

  • If useNewPageEventNameFormat is set to true in the integration options, RudderStack sends events to Amplitude as Viewed {name} Page.
  • Otherwise, it sends the events to Amplitude as Viewed page {name}.
warning
If you enable more than one of the above settings, RudderStack may send multiple events to Amplitude for a single page event.

The following settings are only applicable when you’ve connected a source in mobile device mode:

FieldDescription
Track all pagesIf you toggle on this setting and name is present in your screen event properties, RudderStack sends the event to Amplitude as Viewed {name} Screen. Otherwise, it sends the event as Loaded a Screen.
Track categorized pagesWhen this setting is turned on, RudderStack sends the screen events to Amplitude as Viewed {category} Screen.
Track named pagesIf you toggle on this setting and name is present in your screen event properties, RudderStack sends the event to Amplitude as Viewed {name} Screen. If name is absent, RudderStack will not send the event.
warning
If you enable more than one of the above settings, RudderStack may send multiple events to Amplitude for a single screen event.

The following settings are only applicable when you’ve connected a source in cloud mode.

FieldDescription
Use Custom Page Event NameEnable this setting to set a specific event name format for your page calls. See Set custom page event names for more information.
Page Event Name FormatIf Use Custom Page Event Name is enabled, specify the event name format for your page calls. For example, Viewed a {{ name }}.

Screen settings

This section allows you to set how you want to send your screen calls to Amplitude.

The following settings are only applicable when you’ve connected a source in cloud mode:

FieldDescription
Use Custom Screen Event NameEnable this setting to set a specific event name format for your screen calls. See Set custom screen event names for more information.
Screen Event Name FormatIf Use Custom Screen Event Name is enabled, specify the event name format for your screen calls. For example, Viewed a {{ name }}.

Identify & Group settings

This section allows you to set how you want your Group or Identify call user properties to be sent to Amplitude:

FieldDescriptionNote
Group type traitSpecify the group type to send as groupType in your group calls to Amplitude. Examples of a group type could be: Org ID, Org Name, or Industry.-
Group value traitSpecify the group value to send as groupValue in your group calls to Amplitude. This would be a specific value of the group type. For example, if you set group_type: “industry”, group_value might be “retail”.-
Identify: traits to incrementSet the traits to increment on an identify call. These traits will then be incremented by the numerical value associated with the trait in your identify call.-
Identify: traits to set onceSpecify the traits where you want to set values only once, which prevents overriding the property value.-
Identify: traits to appendAppend a value or multiple values to a user property array. If the corresponding trait does not have a value set yet, it will be initialized to an empty list before the new values are appended. If the corresponding trait has an existing value and it is not a list, it will be converted into a list with the new value appended.Supported for all connection modes except for web device mode
Identify: traits to prependPrepend a value or multiple values to a user property array. If the corresponding trait does not have a value set yet, it will be initialized to an empty list before the new values are prepended. If the corresponding trait has an existing value and it is not a list, it will be converted into a list with the new value prepended.Supported for all connection modes except for web device mode

Destination settings

The following sections detail the advanced destination-specific settings you can configure in the dashboard.

Amplitude IT

FieldDescriptionNote
Secret keySee Amplitude docs for more information on obtaining this key.Secure your secret key if you plan on deleting users for GDPR purposes.
Version nameAssign a version name for your page, and we’ll send it to Amplitude for more detailed events.Only supported for web device mode
Map device brandCapture brand, manufacturer, and model information for mobile devices. Amplitude computes device_family as device_family: {device_brand} {device_manufacturer} {device_model}.Only supported for mobile sources in device mode.

Ecommerce settings

These settings allow you to define how you want your Order Completed events to be passed to Amplitude.

info
These settings are applicable for the events sent in cloud mode and web device mode.
FieldDescription
Track products as single eventTurn this on to track an array of products as a single event. The event will be passed as the original event name, and all products as properties. Otherwise, each product is tracked as a separate event with the name Product purchased.
Track revenue per productTurn this on to track the revenue of each product in an event individually. Otherwise, the event will be sent as an aggregate revenue of all products.

Other settings

Client-side events filtering

RudderStack’s client-side event filtering feature lets you specify which events should be discarded or allowed to flow through by allowlisting or denylisting them.

info
This is only applicable for destinations that are connecting in device mode and implementing track calls. For mobile SDKs, it also applies to the following application lifecycle events: installed, opened, backgrounded, updated.
  1. Select whether you would like to turn on events filtering.
    • The default setting is No events filtering, meaning that no filters are applied and RudderStack will allow all events to flow through.
    • Select Allowlist if you would like to be able to specify the names of the events that you want RudderStack to allow to flow through to the destination. Any events you do not list in the subsequent modals will be blocked.
    • Select Denylist if you would like to be able to specify the names of the events that you want RudderStack to block from flowing to the destination. Any events you do not list in the subsequent modals will be allowed to flow through to the destination.
  2. Input event names to Allowlist (only possible if Allowlist was selected above): provide the event name(s) you would like to allow to flow through to the destination. Input one event name per line, and click add more for each additional event name you would like to add to the list. Note that any event names that you do not add to this list will be blocked.
  3. Input event names to Denylist (only possible if Denylist was selected above): provide the event name(s) you would like to block from flowing to the destination. Input one event name per line, and click add more for each additional event name you would like to add to the list. Note that any event names that you do not add to this list will be allowed to flow through to the destination.

OneTrust is a popular consent management platform that provides data governance, privacy management, and security solutions to thousands of businesses worldwide.

RudderStack’s JavaScript SDK integrates seamlessly with the OneTrust SDK. It lets you map the OneTrust cookie/consent groups to RudderStack’s consent purposes. RudderStack, in turn, uses this consent information to enable/disable tracking and sending the data.

To use this feature, ensure that you have activated the integration by following the steps outlined in the OneTrust Consent Manager integration for the JavaScript SDK.

FieldDescriptionNote
Category nameInput the consent category name(s) defined when you set up OneTrust for your JavaScript source.Insert one category name per line.

See OneTrust Consent Manager in our JavaScript SDK docs to learn more.

RudderStack SDK settings

You can also define the following settings in your RudderStack SDK while sending events to Amplitude:

FieldDescriptionNote
residencyServerSets the Amplitude server zone.

Default value: AMPServerZone.US
Configurable values are AMPServerZone.US and AMPServerZone.EU.
useBatch
Applicable only for the Android SDK.
Determines whether to use the batch API.

Default value: True
The value for Batch event upload threshold dashboard setting should be greater than 0.

Amplitude SDK settings

The following settings let you customize the Amplitude SDK when sending events via the device mode. Make sure to add the Amplitude SDK to your project before configuring these settings.

Web

If you are connecting to Amplitude in web device mode, these settings allow you to configure Amplitude’s native web SDK.

FieldDescriptionNote
Proxy server URLUse this setting to send data to Amplitude using a domain proxy to relay event requests.Make sure that the proxy server URL is of a secure protocol type (HTTPS). Otherwise, RudderStack drops the proxy domain information and sends the data to Amplitude directly, without using the proxy domain.
Replace Device ID with Anonymous IDWhen turned on, RudderStack uses anonymousId instead of the device ID.RudderStack’s JavaScript SDK generates the anonymousId. To set your own anonymousId, use the setAnonymousId() method.
Disable AttributionWhen turned on, RudderStack does not track attribution using the GCLID, UTM parameters, and referrer information.-
Save Referrer, URL params, GCLID only once per sessionWhen turned on, RudderStack tracks referrer, UTM parameters, and GCLID only once per session and ignores any new values that may enter a user’s session.-
Batch event upload period (ms)Set the time limit (in ms) between batch uploads.-
Batch event upload thresholdSet the minimum number of events to be sent in a batch.-
warning

With the latest Amplitude SDK updates, the following configuration settings are now removed from the RudderStack dashboard:

  • Force HTTPS
  • Track GCLID
  • Track referrer information
  • Track UTM properties
  • Reset referrer or UTM params for new sessions
  • Batch events prior to upload

For older Amplitude web device mode configurations, the above settings will still be applicable. However, you will not be able to modify/update them. To do so, contact RudderStack support.

RudderStack will continue to support the above settings for the next two months, after which they will be set to the following default values:

  • Force HTTPS: false
  • Track GCLID: false
  • Track referrer information: false
  • Track UTM properties: false
  • Reset referrer or UTM params for new sessions: false
  • Batch events prior to upload: false

iOS

If you are connecting to Amplitude in mobile device mode, these settings allow you to configure Amplitude’s native iOS SDK.

FieldDescriptionNote
Track session eventsTurning this on will send start and end session events.Mobile device mode only
Use IDFA for device IDTurning this on will send the IDFA instead of device ID to Amplitude.Mobile device mode only
Batch event upload period (ms)Set the time limit (in ms) between batch uploads.Mobile device mode only
Batch event upload thresholdSet the minimum number of events to be sent in a batch.Mobile device mode only

Android

If you are connecting to Amplitude in mobile device mode, these settings allow you to configure Amplitude’s native Android SDK.

FieldDescriptionNote
Enable location listeningWhen on, capture user location information for anyone who has granted app location permission.Mobile device mode only
Track session eventsTurning this on will send start and end session events.Mobile device mode only
Use advertising ID for device IDTurning this on will send Advertising ID instead of Device ID to Amplitude.Mobile device mode only
Batch event upload period (ms)Set the time limit (in ms) between batch uploads.Mobile device mode only
Batch event upload thresholdSet the minimum number of events to be sent in a batch.Mobile device mode only

Identify

The identify call lets you associate a user with their actions and capture all relevant traits about them. This information includes unique userId as well as any optional information such as name, email address, etc.

info
When sending events from your Reverse ETL sources using the Visual Data Mapping feature, you can also pass a custom user ID in your identify calls. RudderStack adds this ID under context.externalId.0.identifierType before sending it to Amplitude.

A sample identify call looks like the following:

rudderanalytics.identify(
  "userId", {
    email: "name@surname.com",
    name: "John Doe",
    profession: "Student",
  })

A sample dashboard after making the above identify, page, and track calls is as follows:

Adjust connection settings
Adjust connection settings

info

Applicable for mobile only: If a trait has a name optOutOfSession with a value of true, then this identify call will be opted out of the current session if it exists or won’t start a new session if there isn’t any active session.

Opting out of sessions: You can opt out of an identify call (of a current session) by passing a trait named optOutOfSession as true. When there is no active session, passing optOutOfSession does not start a new session.

Unset user properties

To unset the user traits set in the traits/context.traits object or userProperties in Amplitude, specify them in the integrations.Amplitude.fieldsToUnset object.

info

When you unset fields using fieldsToUnset, RudderStack notifies Amplitude to delete the fields along with their schema (if they exist). For more information, see the following Amplitude documentation:

Page

The page call allows you to record information whenever a user sees a web page, along with the associated optional properties of that page. This method must be called at least once per page load.

A sample page call looks like the following:

rudderanalytics.page({
  userId: "user_id",
  category: "Category",
  name: "Sample",
})

In the above sample, we capture information related to the page being viewed such as the category of the page (Category), as well as the name of the page (Sample) along with the unique user ID.

Set custom page event names

You can set custom event names for your page calls.

warning
This feature is available only in cloud mode.

To use this feature, enable the Use Custom Page Event Name dashboard setting and specify the event name format in the Page Event Name Format field.

Set custom page event names

For example, if you set the event name format as Viewed a {{ name }} and pass the following event:

rudderanalytics.page("Home")

In this case, RudderStack sets the event name as Viewed a Home before sending it to Amplitude.

Screen

The screen method allows you to record whenever a user sees the mobile screen, along with any associated optional properties. This call is similar to the page call, but is exclusive to your mobile device.

A sample screen call looks like the following code snippet:

rudderanalytics.screen({
  userId: "user_id",
  category: "Category",
  name: "Sample",
})

In the above snippet, we capture information related to the screen being viewed, such as screen’s name and category.

Set custom screen event names

You can set custom event names for your screen calls.

warning
This feature is available only in cloud mode.

To use this feature, enable the Use Custom Screen Event Name dashboard setting and specify the event name format in the Screen Event Name Format field.

Set custom screen event names

For example, if you set the event name format as Viewed a {{ name }} and pass the following event:

[[RSClient sharedInstance] screen:@"Main"
                properties:@{
                  @"title" : "Home | RudderStack",
                  @"url" : @"http://www.rudderstack.com"}
                ];

In this case, RudderStack sets the event name as Viewed a Main before sending it to Amplitude.

Group

The group call lets you associate a particular identified user with a group, such as a company, organization, or an account.

RudderStack supports sending group calls in cloud mode. When sending events via device mode, group is supported only by the web (JavaScript) SDK.

warning
Groups are an enterprise-only feature in Amplitude and you need to purchase the Accounts addon to use them.
info
This feature is only available for cloud and web (JavaScript) device mode.

To use the Amplitude Groups feature with RudderStack, you need to define the Group name trait and Group value trait in the dashboard settings. To send the events, see below:

  • Cloud mode: Pass the above fields as traits while making a group call.
  • Device mode: RudderStack triggers a group call even for a groupId by mentioning groupType as '[RudderStack] Group' and value as groupId.

Even if you don’t have an enterprise account or the Groups add-on, RudderStack adds groups as a user property in the user’s profile with Group Name Trait as its type and Group Value Trait as its value.

Suppose you have defined the Group Name Trait as RS and Group Value Trait as RudderStack and made the group call. The user would then be associated with the Group name: RS and the Group Value: RudderStack.

RudderStack does not support associating a user to more than one group per group call sent to Amplitude. To send more than one group per user, you must call the group API multiple times with the relevant group information specified in the group settings.

Track

The track call lets you record the user’s actions along with any properties associated with them.

A sample track call looks like the following:

rudderanalytics.track("Track me")
info
Applicable for mobile only: If you set a property with the name optOutOfSession and value true then this track call will be opted out of the current session if it exists or does not start a new session if there isn’t any active session.

Revenue events

Revenue events are available in web device mode only. To track revenue events, we use Amplitude’s logRevenueV2() API which expects revenue as a top level attribute.

To track a revenue event, you must include a revenue key in the event, like so:

rudderanalytics.track("Item Purchased", {
  revenue: 30,
  revenue_type: "add-on purchase",
})

If you send a price and quantity with the revenue key, the revenue will be calculated in Amplitude as price * quantity

You may also set a product_id, but only if revenue has been set.

If a products array is present in the event payload, then to track products individually at each product level, price or revenue must be present or revenue will not be tracked, as logRevenueV2 uses both price and quantity to calculate revenue.

If no quantity is present, we will assume a quantity of 1 as default as 1.

Order Completed

A sample Order Completed ecommerce event looks like this:

rudderanalytics.track("Order Completed", {
  checkoutId: "ABCD1234",
  orderId: "order1234",
  revenue: 50,
  products: [
    {
      productId: "product1",
      sku: "45790-32",
      name: "Monopoly: 3rd Edition",
      price: 20,
      quantity: 1,
      category: "Games",
    },
    {
      productId: "product2",
      sku: "46493-32",
      name: "Uno Card Game",
      price: 15,
      quantity: 2,
      category: "Games",
    },
  ],
})

The above call will generate one Order Completed event, 2 individual Product purchased events and 2 revenue events (one with $price as 15 and $quantity as 2 and the other one with $price as 20 and $quantity as 1 ) at Amplitude, provided that in the destination settings dashboard: Track revenue per product settings is enabled. The two separate revenue events are generated for device mode. For cloud mode, revenue will be tracked along with the 2 Product purchased events.

Multi-product purchases

Amplitude allows you to define how you want to track multi-product purchases. This feature is available in web device mode only.

If you enable “Track revenue per product” in your ecommerce settings, you will then be able to track each product’s revenue as a separate event. Otherwise, the event will be sent as an aggregate revenue of all products.

If you enable “Track products once”, then an array of products will be tracked as a single event. The event would be passed as the original event name, with all products as properties.

Alias

info
This feature is currently only available when sending events through the JavaScript SDK in cloud mode.
warning
To use Alias, you must enable the Amplitude Portfolio add-on.

Refer to the JavaScript SDK documentation for information and examples on how to call the alias event.

Mapping

Amplitude’s alias call simply creates a mapping or link between the user_id specified in the from parameter to the global_user_id specified in the to parameter of the alias call.

rudderanalytics.alias("user_id", "global_user_id", options, callback)

Unmapping

With Amplitude, it is possible to unmap an already established link, or alias. In order to trigger Amplitude to unmap a connection, follow the code snippet template below.

rudderanalytics.alias("user_id_to_unmapped", {
  integrations: {
    Amplitude: {
      unmap: true,
    },
  },
})

In the snippet above, user_to_be_unmapped, will be unmapped or unlinked from the global_user_id it is currently linked to.

info
For the unmapping call, it is not necessary to provide global_user_id in the to parameter of the alias call. If it is included, RudderStack will dismiss this field.

For more information on how the alias call works for Amplitude, refer to this Amplitude support page.

Advanced Features

Reset

info
This feature is currently available as a part of RudderStack Mobile SDKs only.

The reset method resets the previously identified user and related information.

Sending event_id

RudderStack supports sending event_id to Amplitude in device mode. You can include it under the integrations object and it is supported for all above-mentioned API calls, namely, identify, track, page, screen, and group.

A sample identify call with event_id is as follows:

rudderanalytics.identify(
  "1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
    name: "Alex Keener"
  }, {
    integrations: {
      Amplitude: {
        event_id: 1234
      }
    }
  }
);

Skip user properties sync

When you send an event to Amplitude via RudderStack, Amplitude updates the existing user properties and appends any new ones. However, you can change this behavior by sending the skip_user_properties_sync property as true in the integrations object:

"integrations": {
        ...
        ...
        "Amplitude": {
            "skipUserPropertiesSync": true
        }
        ...
        ...
    }

This ensures that the event in Amplitude includes only the user properties sent with it, does not modify the user properties table, and does not include any pre-existing user properties. See Amplitude documentation for more information.

GDPR and user suppression

Deleting a user

You can delete a user in Amplitude using Suppression with Delete regulation in the RudderStack User Suppression API.

To delete a user, you must specify their userId in the event. Optionally, you can specify a custom identifier.

A sample regulation request body for deleting a user in Amplitude is shown below:

{
  "regulationType": "suppress_with_delete",
  "destinationIds": [
    "2FIKkByqn37FhzczP23eZmURciA"
  ],
  "users": [{
    "userId": "1hKOmRA4GRlm",
    "<customKey>": "<customValue>"
  }]
}

FAQ

Why are all my session IDs -1 in Amplitude?

You will see the session IDs as -1 in Amplitude if you are sending events in cloud mode and:

  • You are not including the session ID in your event’s context.sessionId.
  • If the sessionId is not an integer (ideally, a Unix timestamp)

See Amplitude’s documentation for more information on how Amplitude tracks user sessions.

Can I send more than one group per user to Amplitude?

RudderStack does not support associating a user to more than one group per group API call sent to Amplitude. To send more than one group per user, you need to call the group API multiple times with the relevant group information specified in the group settings.

How does RudderStack send the operating system information to Amplitude?

RudderStack sends the following contextual fields that capture the operating system details:

RudderStack fieldAmplitude propertyData typeDescription
os.nameos_nameString
  • Web SDK: Browser name (Example: Chrome)
  • Mobile SDKs: Mobile operating system (Example: iOS)
os.versionos_versionString
  • Web SDK: Browser version
  • Mobile SDKs: OS version
info
  • To send the OS-related information differently, you can write a transformation according to your requirements.

  • Amplitude combines the above fields to set the OS property as:

    OS = os_name + os_version

    For example, iOS 9.1, Chrome 45.

Why am I getting 429 errors in Amplitude?

You might be sending too many requests at a time for a given user. Amplitude has a limit of 10 events per second per user. It is recommended to stop sending events for some time (at least 30 seconds) before retrying.

For more information on the common API error codes, see this Amplitude support page.



Questions? Contact us by email or on Slack