Amplitude

Step-by-step guide on sending 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.

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:

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

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

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.

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

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.

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

Client-side events filtering

Web device mode 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 settings related to the device modewill 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.

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

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

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:

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:

Copy
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:

Copy
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:

Copy
rudderanalytics.track("Track me")

Revenue events

Amplitude allows for tracking of revenue events.

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:

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

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

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

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:

Copy
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:

Deleting a user

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

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

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

Group

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

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, then the user would be associated with the Group name: RS and the Group Value: RudderStack.

Send event_id in device mode

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

A sample identify call with event_id is as follows:

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

Alias

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.

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

Copy
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 more information on how the alias call works for Amplitude, refer to this Amplitude support page.

Reset

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

Copy
[[RSClient sharedInstance] reset];

Copy
rudderClient.reset();

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