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.

Save your Secret Key in a safe place if you plan on deleting users. You may want to consider this option for GDPR purposes.

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.

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.

These settings are only applicable when you’ve connected a source in web or mobile device mode.

We suggest checking your event volume setup with Amplitude prior to configuring this section.

If multiple settings are enabled, then multiple events may be sent for a single page/screen call. For example, if both Track categorized page and Track named page settings are enabled, one Viewed {name} page / Viewed {name} Screen and one Viewed {category} page / Viewed {category} Screen event will be generated for a single page/screen call.

Identify & Group settings

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

Other settings

Amplitude IT

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.

Ecommerce settings

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

SDK settings

These settings allow you to customize the Amplitude SDK. Remember to also follow these steps to add the Amplitude SDK to your project.

Web

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

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.

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.

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.

Tracking Named, Categorized, or All Pages

If you are connecting in web or device mode, the settings you choose in your web app configurations will determine how the page or screen call is sent to RudderStack.

We highly recommend checking your RudderStack event volume setup prior to configuring this section.

When you enable Track Named Pages or Track Categorized Pages, RudderStack will send a Page or Screen call when ‘Name’ or ‘Category’ are provided. These will also be passed as a top-level event type, and will count towards a unique event type count in Amplitude. If ‘Name’ or ‘Category’ are absent, then the event will be sent as Loaded a Page or Loaded a Screen.

When you enable Track All Pages, RudderStack will send a Loaded a Page call to Amplitude, with the ‘name’ or ‘category’ included as an attribute or event property. Loaded a Page will be sent as one event type.

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.

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 add-on 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 and pass them as traits while making a group call.

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 allows you to capture any action that the user might perform, and the properties associated with that action. Each action is considered to be an event. The following settings

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 Data Regulation

Deleting a user

You can delete a user in Amplitude using Suppression with Delete regulation in the RudderStack Data Regulation 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?

Session tracking is only supported for the RudderStack device mode because the integration loads Amplitude’s SDK. Events sent via cloud mode connections will have session IDs as -1.

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.

Questions? Contact us by email or on Slack