Amplitude Device Mode Integration

After you have successfully set up Amplitude as a destination in RudderStack, follow this guide to correctly send your events to Amplitude in device mode.

Add device mode integration

Follow these steps to add Amplitude to your project depending on your integration platform:

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

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

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

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)

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

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

Amplitude Browser SDK version

RudderStack lets you select the Amplitude Browser SDK version that the JavaScript SDK loads in device mode. You can configure this using the SDK Version setting during destination setup.

With Browser SDK version 2, you can also add optional Amplitude products such as Guides & Surveys and Experiment alongside the device-mode integration. See Other Amplitude Features for setup details.

The JavaScript SDK loads the following Amplitude Browser SDK lines for each option:

New destinations default to Amplitude Browser SDK version 2.

Any existing integrations continue to use Amplitude Browser SDK version 1 unless you explicitly opt in to version 2.

Browser SDK version 2 requirements

Note that Amplitude Browser SDK version 2 requires a corresponding minimum supported version of the RudderStack JavaScript SDK:

• If you load the SDK from the RudderStack CDN, you always get latest version and thus it supports Amplitude SDK version 2.
• If you install it from NPM, upgrade to the latest version of the JavaScript SDK before selecting version 2.

In older SDK versions the setting is ignored and Amplitude continues to load with v1.

Behavior changes in version 2

When you switch a destination from version 1 to 2, your saved settings (such as attribution and page tracking) carry over unchanged.

However, two behaviors change in Amplitude’s version 2 SDK that you should be aware of before upgrading:

1. Attribution now tracks new campaigns

• In version 1, attribution and new-campaign tracking were controlled separately, which let you enable attribution while ignoring new campaigns within a session.
• In version 2, this is no longer a separate option. When attribution is enabled, that is, when Disable attribution setting is turned off, Amplitude automatically tracks all new campaigns. As a result, your event volume may increase, and campaign attribution data may appear differently in Amplitude.

Attribution is still controlled by the existing Disable attribution in the same place as before — only the new-campaign behavior changes.

The Save referrer, URL params, GCLID only once per session setting does not apply to version 2.

2. Re-identifying a user no longer resets the session

• Invoking rudderanalytics.identify() to re-identify a new user results in the Amplitude SDK version 1 starting a new session.
• However, Amplitude SDK version 2 does not reset the active session in this case. If your reporting relies on a new session beginning when a user logs in or is re-identified, review those reports after upgrading.

Enhanced tracking

In version 2, the Amplitude Web SDK can automatically capture additional page, interaction, and performance signals. You can enable each of these from the Amplitude destination settings.

These features are available only when the destination uses Amplitude Browser SDK version 2. Note that they are all toggled off by default, so upgrading to version 2 does not change what is captured until you enable them.

Note that Auto-capture page views is independent of the Track all pages, Track categorized pages, and Track named pages settings — these settings translate your instrumented page() calls into Amplitude events, whereas Auto-capture page views lets Amplitude’s SDK detect navigation on its own.

If you enable Auto-capture page views while your app also instruments page() calls, Amplitude receives duplicate page events — one Amplitude-native page view and one from the RudderStack page event.

The Network Tracking, Element Interactions, and Form Interactions settings capture data based on user activity on the page. Depending on your application, they may:

• Capture personally identifiable information (PII), for example, values present in element attributes, form fields, or request and response URLs.
• Significantly increase your event volume, which can affect your Amplitude billing and event quotas.

Enable these settings only after reviewing what would be captured on your pages.

Identify

You can use the identify call to associate a user with their actions and capture all relevant traits about them. This includes a unique userId and other optional information like name, email address, etc.

In device mode, RudderStack automatically captures and sends the device-specific identifiers like deviceId to Amplitude. These identifiers are used by Amplitude to track unique devices and sessions.

A sample identify call looks like the following:

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

Opt out of identify calls

This feature is available only for the mobile platforms.

You can opt out of an identify call in a current session by passing a optOutOfSession trait and setting it to true. If there is no active session, passing optOutOfSession: true does not start a new session.

Unset user properties

To unset the user traits in device mode, specify them in the integrations.Amplitude.fieldsToUnset object.

When you unset fields using fieldsToUnset, RudderStack notifies Amplitude to delete the fields along with their schema (if they exist).

See the Amplitude documentation for more information on this feature.

Example

To unset firstName and lastName in the following identify event:

rudderanalytics.identify("userId", {
  "firstName": "Alex",
  "outerObject": {
    "innerObject": {
      "lastName": "Keener"
    }
  }
});

Set the integrations object in your identify event as shown:

rudderanalytics.identify("userId", {}, {
  integrations: {
    Amplitude: {
      "fieldsToUnset": ["firstName", "outerObject.innerObject.lastName"]
    }
  }
})

Page

The page call allows you to record your website’s page views, with the additional relevant information about the viewed page. RudderStack recommends calling this method at least once per page load.

In device mode, page views are automatically tracked as events in Amplitude with the event type as [RudderStack] Page.

A sample page call looks like the following:

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

In the above example, RudderStack captures information related to the page being viewed such as the category of the page (Category) and the page name (Sample).

Screen

The screen call lets you record screen views with any additional information about the viewed screen.

In device mode, screen views are automatically tracked as events in Amplitude with the event type as [RudderStack] Screen.

A sample screen call looks like the following code snippet:

[[RSClient sharedInstance] screen:@"Main"
                properties:@{@"prop_key" : @"prop_value"}];

Group

You can use the group event to link an identified user with a group, like a company, organization, or an account.

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

Use Amplitude Groups

Note the following:

• This feature is only available for web (JavaScript) device mode.
• Groups are an enterprise-only feature in Amplitude. You need to purchase the Accounts add-on to use this feature.

To use the Amplitude Groups feature with RudderStack:

1. Configure the Group name trait and Group value trait fields in the Group trait settings.
2. In device mode, RudderStack triggers a group call 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.

For example, if you define the Group Name Trait as RS and Group Value Trait as RudderStack and make the group call, the user would then be associated with the group name as RS and the group value as RudderStack.

Note that in device mode:

• Group properties are limited to scalar values and arrays.
• Nested objects in group properties are not supported.
• Group property values cannot exceed 1000 characters.

Track

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

In device mode, events are processed and sent immediately to Amplitude. The SDK also supports offline event caching and automatic retries when the device is back online.

A sample track call looks like the following:

rudderanalytics.track("Track me")

Opt out of track calls

This feature is available only for the mobile platforms.

If you set a property with the name optOutOfSession with value set to true, then this track call will be opted out of the current session if it exists. If there is no active session, passing optOutOfSession: true does not start a new session.

Track revenue events

Revenue events are available only in web device mode.

To track revenue events, RudderStack uses 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, as shown:

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

RudderStack processes revenue events in the following ways:

• If you include price and quantity fields in your event, then RudderStack calculates the revenue as price * quantity.
• If the revenue field is present in your event but price is not, then RudderStack uses revenue as the price with quantity set to 1.

The revenue field does not override the price * quantity calculation, if both are present.

Note that:

• Each product must have either price or revenue fields for tracking.
• The logRevenueV2 API uses both price and quantity to calculate revenue.
• If quantity is not specified, it defaults to 1.

Track revenue at event or product level

For events with a products array, you can track revenue at event level or product level based on your dashboard configuration:

Track completed orders

This feature is available only in web device mode.

In device mode, revenue tracking for orders is handled by the Amplitude SDK’s logRevenueV2 API, which ensures accurate revenue attribution even in offline scenarios.

While tracking completed orders with multiple products, RudderStack generates events as follows:

When Track products as a single event setting is toggled off:

• One main Order Completed event with the overall order details
• Separate Product Purchased events for each product in the products array
• Revenue tracking based on your revenue tracking configuration

When Track products as a single event setting is toggled on:

• One single event with the original event name (Order Completed)

• All products are included as properties in this single event

• Revenue tracking based on your revenue tracking configuration:

  • If Track revenue per product setting is enabled: Each product is tracked individually with its own revenue calculation, regardless of the total order revenue.
  • If Track revenue per product setting is disabled: The total revenue specified at the order level is used.

In both the cases, any discrepancy between the sum of product revenues and the order-level revenue is ignored.

A sample Order Completed event is shown below:

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",
    },
  ],
})

Advanced features

This section covers some advanced features that you can use to enhance your Amplitude device mode integration with RudderStack.

Reset

This feature is currently available only for the mobile platforms.

You can use the reset method to reset the previously identified user and related information. This is particularly useful in scenarios like user logout.

[[RSClient sharedInstance] reset];

rudderClient.reset()

Send 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 API calls (identify, track, page, screen, and group).

If you don’t specify an event_id, the SDK automatically generates one to ensure event uniqueness.

A sample identify call with event_id is shown below:

rudderanalytics.identify(
  "1hKOmRA4GRlm", {
    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. You can change this behavior by setting the skip_user_properties_sync property to true in the integrations object.

This ensures that the event in Amplitude:

• Includes only the user properties sent with it
• Does not modify the user properties table
• Does not include any pre-existing user properties

See Amplitude documentation for more information on this feature.

A sample integrations object with the skip_user_properties_sync property is shown below:

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

FAQ

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