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:

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>

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)

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

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.

Questions? Contact us by email or on Slack