Amplitude

Step-by-step guide to send your event data from RudderStack to Amplitude

Amplitude is a comprehensive product analytics platform for the web as well as mobile platforms. Over 12,000 companies use Amplitude to get useful marketing insights that drive product strategy and conversion and retention of their customers.

RudderStack supports sending events from the RudderStack SDKs to Amplitude through our data plane and Web connection mode.

Find the open-source transformer code for this destination in our GitHub repo.

Getting started

Before configuring Amplitude as a destination in RudderStack, verify if the source platform is supported by Amplitude by referring to the table below:

Connection Mode	Web	Mobile	Server
Device mode	Supported	Supported	-
Cloud mode	Supported	Supported	Supported

To know more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.

Once you have confirmed that the source platform supports sending events to Amplitude, follow these steps:

1. From your RudderStack dashboard, add the source. Then, from the list of destinations, select Amplitude.

2. Assign a name to the destination and click on Next.

Connection settings

To successfully configure Amplitude as a destination, you will need to configure the following settings:

• API Key: You can find the Amplitude API key in the Amplitude dashboard.

• API Secret Key required for deletion of users: Enter your API Secret Key required for user deletion.

• Residency Server: Based on the Amplitude data center you have configured, select the residency server from the below options:

  • Standard Server

  • EU Residency Server

Group settings

• Group name trait: The trait that we will use as groupType in the group call.

• Group value trait: The trait that we will use as groupValue in the group call.

Track pages

These settings can be used for tracking via web and mobile device mode only.

• Track all pages: If this setting is enabled, an event named Loaded a page / Loaded a Screen will be sent to Amplitude.

• Track Categorized pages: If this setting is enabled and if category is present in a page / screen call, then an event named Viewed {category} page / Viewed {category} Screen will be sent to Amplitude.

• Track Named pages: If this setting is enabled and the name is present in a page call, then an event named Viewed {name} page will be sent to Amplitude.

If name is present in a screen call, then RudderStack sends the event name as Viewed {name} Screen to Amplitude. However, if name is absent, then the event is sent as Loaded a Screen.

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 events will be generated for a single page/screen call.

Trait settings

This setting is for configuring the traits sent to Amplitude via RudderStack's identify call.

• Traits to increment: If this setting is enabled, the value of the corresponding trait will be incremented at Amplitude, with the value provided against the trait in an identify call.

• Traits to set once: If this setting is enabled, the value of the corresponding trait will be set once at Amplitude with the value provided against the trait in an identify call.

• Traits to Append: If this setting is enabled, the value of the corresponding trait will be appended to the corresponding trait array at Amplitude. 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.

This feature is not applicable for the web device mode integration.

• Traits to Prepend: If this setting is enabled, the value of the corresponding trait will be prepended to the corresponding trait array at Amplitude. 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.

This feature is not applicable for the web device mode integration.

Other settings

• Track Products once: If this setting is enabled and if the event payload contains an array of products, then the event is tracked with the original event name and all the products as its property. Otherwise, each product is tracked with event as Product purchased.

• Track Revenue per product: If this setting is enabled and if the event payload contains multiple products, each product's revenue is tracked individually.

• Version Name: The value of this field is set as the versionName of the Amplitude SDK.

This feature is applicable only for the web device mode integration.

• Map device brand: Enable this setting for RudderStack to send the device brand information (context.device.brand) to Amplitude.

Amplitude computes device_family as device_family: {device_brand} {device_manufacturer} {device_model}.

Client-side events filtering

Refer to the Client-side Events Filtering guide for more information on this setting.

Web SDK settings

• Batch events: If this setting is enabled, the events are batched together and uploaded by the Amplitude SDK only when the number of queued events is greater than or equal to eventUploadThreshold or eventUploadPeriodMillis (in ms), since the first unsent event is queued.

• Event upload period millis: If the batch events settings is enabled, this is the amount of time that the SDK waits to upload the events.

• Event upload threshold: If the batch events settings is enabled, this is the minimum number of events to batch together by the Amplitude SDK.

• Use device mode to send events: Enable this flag to send the events through Amplitude web SDK. The other web SDK-supported settings will also work if you enable this option.

• Prefer Anonymous ID for Device ID: If this setting is enabled, the Device ID will be set as the anonymousId generated by RudderStack SDK or by the value you explicitly set as the anonymousId via RudderStack'ssetAnonymousId() method.

For more information on explicitly setting the anonymousId, refer to the JavaScript SDK documentation.

• Set Device ID from the URL parameter: If this setting is enabled, the Amplitude SDK will parse the URL parameter and set the Device ID from amp_device_id.

• Force HTTPS: If this setting is enabled, the events will always be uploaded by the Amplitude SDK to the HTTPS endpoint, otherwise it will use the embedding site's protocol.

• Track GCLID: If this setting is enabled, the Amplitude SDK will capture the gclid URL parameters along with the user's initial_gclid parameters.

• Track Referrer: If this setting is enabled, the Amplitude SDK will capture the referrer and referring_domain for each session along with the user's initial_referrer and initial_referring_domain.

• Track UTM properties: If this setting is enabled, the Amplitude SDK parses the UTM parameters in the query string or _utmz cookie and includes them as user properties in all uploaded events.

• Save Referrer, URL Params, GCLID once per session: If this setting is enabled, the corresponding tracking of gclid, referrer, UTM parameters will be done once per session.

Disable this option if you always want to capture new values through the session.

• Unset param referrer on new session: If this setting is disabled, the existing referrer and utm_parameter values will be passed to each new session. If enabled, referrer and utm_parameter properties will be set to null upon instantiating a new session.

This feature works only if the Track Referrer and Track UTM properties settings are enabled in the dashboard.

Adding device mode integration

iOS Android React Native Follow these steps to add Amplitude to your iOS project:

• In your Podfile and add the Rudder-Amplitude extension

  pod 'Rudder-Amplitude'
  
  # for using IDFA as device id, location listening only
  pod 'Amplitude', '~> 7.2.0'

• After adding the dependency followed by pod install , you can add the imports to your AppDelegate.m file as shown:

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

• and also add the initialization of your RSClient as shown:

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

• Add the below logic just after initializing RudderClient in AppDelegate.m if you would like to send IDFA of iOS device as device id to Amplitude

  Make sure that you enable use IDFA as device id under iOS SDK settings on dashboard.

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

• and then add the below logic if you would like to track location (latitude, longitude)

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

To add Amplitude to your Android Project please follow these steps :

• Open your app/build.gradle (Module: app) file, and add the following under the dependencies section :

  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'

• Add the following under compileOptions in the android tag :

  compileOptions {
      sourceCompatibility JavaVersion.VERSION_1_8
      targetCompatibility JavaVersion.VERSION_1_8
  }

• Initialize the Rudder SDK in the Application class's onCreate() method as following:

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

• If you would like to send Google Advertising Id of the device as device id to the Amplitude then add the below code in the AndroidManifest.xml of your app under <application> tag:

  Make sure that you enable Use Advertising ID for Device ID under Android SDK settings on the dashboard

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

To add Amplitude to your React Native project:

• Add the RudderStack-Amplitude module to your app using :

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

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

• Open your android/app/build.gradle (Module: app) file, and add the following under compileOptions in the Android tag :

  compileOptions {
      sourceCompatibility JavaVersion.VERSION_1_8
      targetCompatibility JavaVersion.VERSION_1_8
  }

• Import the module added above and add it to your SDK initialization code as shown:

  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)

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.

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.

A sample track call looks like the following:

rudderanalytics.track("Track me")

Revenue events

Amplitude allows for tracking of revenue events.

To track a revenue event, you must include a revenue key in the event. This key is required to have the event counted as a revenue event to send data through the RudderStack cloud mode.

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

You can also set a product_id, but only if revenue has been set as well.

A sample revenue track call looks like the following:

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

To track revenue event in web device mode, we use Amplitude's logRevenueV2() api and also for an eCommerce event, we expect revenue as a top level attribute in properties. If products array is present in event payload, then to track product individually, at each product level price or revenuemust be present, or else we will not track the revenue. As logRevenueV2 uses both price and quantity to calculate the revenue, if no quantity is present, we will take default as 1.

A sample eCommerce event (Order Completed) is as following:

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.

To know more about the difference between Cloud mode and Device mode in RudderStack, read the RudderStack connection modes guide.

(Mobile Only) If a property with the name optOutOfSession and value truethen 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.

Identify

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

A sample identify call looks like the following:

rudderanalytics.identify(
  "userId", {
    email: "[e-mail]",
    name: "John Doe",
    profession: "Student",
  })

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

Event dashboard

User properties dashboard

(Mobile Only) If a trait with the name optOutOfSession and value true then this identify 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.

Group

This feature is currently supported by the RudderStack JavaScript SDK only.

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

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

In order to use the Amplitude groups feature with RudderStack you need to define the Group name trait and Group value trait on the dashboard settings pane and you need to pass them as traits while making a group call.

Even if you are not having an enterprise account or groups add-on, RudderStack would add groupsas a User Property on a user's profile with Group name trait as its type and Group value trait as its value.

Let' say you had defined Group name trait as company_id and Group value trait as company_name and made the above call then the user would be associated with a Group name : RS and a Group Value : RudderStack and you can also see that a user property with type RS and value RudderStack on user's profile.

Alias

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

Refer to the [JavaScript SDK documentation]](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk/#35-alias) 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 a global_user_id in the to parameter of the alias call. If it is included, RudderStack will dismiss it.

For more information on how the alias call works for Amplitude, visit this link.

Reset

This feature is currently available as a part of RudderStack Mobile SDK's only

The reset method resets the previously identified user and related information. For more information, please refer to our RudderStack API Specification guide.

iOS Android

[[RSClient sharedInstance] reset];

rudderClient.reset();

FAQs

How do I get the Amplitude API Key?

You can find the Amplitude API key in the Amplitude Settings Page.

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 the cloud mode connections will have session IDs as -1.

Contact us

For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.