Amplitude destination

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:

• Android
• iOS: Obj-C
• iOS: Swift

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

5. 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).
6. Press Continue to create your connection.
7. Review the Configuration settings to ensure that you are OK with all of the default settings and/or to customize your settings further.
8. Once you are happy with your settings, toggle the Enable switch at the top of your Configurations page to begin sending events to Amplitude.

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:

pod 'Rudder-Amplitude'
pod 'Amplitude', '~> 7.2.0'

#import <rudder>
#import "RudderAmplitudeFactory.h"
// for using IDFA as device id, location listening only
#import <amplitude>

RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[builder withFactory:[RudderAmplitudeFactory instance]];
[RSClient getInstance:WRITE_KEY config:[builder build]];

// for using IDFA as device id only
[Amplitude instance].adSupportBlock = ^{
    return [[ASIdentifierManager sharedManager] advertisingIdentifier];
};

[Amplitude instance].locationInfoBlock = ^{
        return @{
                @"lat" : @37.7,
                @"lng" : @122.4
              };
};

pod 'RudderAmplitude', '~> 1.0.0'

import RudderAmplitude

@import RudderAmplitude;

let config: RSConfig = RSConfig(writeKey: WRITE_KEY)
            .dataPlaneURL(DATA_PLANE_URL)

RSClient.sharedInstance().configure(with: config)
RSClient.sharedInstance().addDestination(RudderAmplitudeDestination())

RSConfig *config = [[RSConfig alloc] initWithWriteKey:WRITE_KEY];
[config dataPlaneURL:DATA_PLANE_URL];

[[RSClient sharedInstance] configureWith:config];
[[RSClient sharedInstance] addDestination:[[RudderAmplitudeDestination alloc] init]];

implementation 'com.rudderstack.android.sdk:core:1.+'
implementation 'com.rudderstack.android.integration:amplitude:1.+'
implementation 'com.google.code.gson:gson:2.8.6'

// Amplitude
implementation 'com.amplitude:android-sdk:2.25.2'
implementation 'com.squareup.okhttp3:okhttp:4.2.2'

// For using Google Advertising Id as device id
implementation 'com.google.android.gms:play-services-ads:18.3.0'

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

// initializing Rudder SDK
val rudderClient =
    RudderClient.getInstance(
        this,
        WRITE_KEY,
        RudderConfig.Builder()
            .withDataPlaneUrl(DATA_PLANE_URL)
            .withFactory(AmplitudeIntegrationFactory.FACTORY)
            .build()
    )

<meta-data android:name="com.google.android.gms.ads.AD_MANAGER_APP" android:value="true"></meta-data>

npm install @rudderstack/rudder-integration-amplitude-react-native

yarn add @rudderstack/rudder-integration-amplitude-react-native

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

import rudderClient from "@rudderstack/rudder-sdk-react-native"
import amplitude from "@rudderstack/rudder-integration-amplitude-react-native"
const config = {
  dataPlaneUrl: DATA_PLANE_URL,
  trackAppLifecycleEvents: true,
  withFactories: [amplitude],
}
rudderClient.setup(WRITE_KEY, config)

rudder_integration_amplitude_flutter: ^1.0.1

flutter pub get

import 'package:rudder_integration_amplitude_flutter/rudder_integration_amplitude_flutter.dart';

final RudderController rudderClient = RudderController.instance;
RudderConfigBuilder builder = RudderConfigBuilder();
builder.withFactory(RudderIntegrationAmplitudeFlutter());
rudderClient.initialize(<write_key>, config: builder.build(), options: null);

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.

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.

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:

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.

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:

Identify & Group settings

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

Destination settings

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

Amplitude IT

Ecommerce settings

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

These settings are applicable for the events sent in cloud mode and web device mode.

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.

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 cookie categories

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, please ensure that you have activated the integration by following the steps outlined here.

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:

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.

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.

Android

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

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.

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:

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 an identify call out of a current session by passing a trait with the name optOutOfSession and value true. In situations where there is not an active session, passing optOutOfSession will not start a new session.

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.

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.

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.

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.

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.

Groups are an enterprise-only feature in Amplitude and you need to purchase the Accounts addon to use them.

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

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

This feature is currently only available when sending events through the JavaScript SDK in cloud mode.

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.

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

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

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

[[RSClient sharedInstance] reset];

rudderClient.reset()

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

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:

• 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