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

Follow the below steps to add Amplitude to your Flutter Project:

  1. Add the following dependency to the dependencies section of your pubspec.yaml file.
yaml 
rudder_integration_amplitude_flutter: ^1.0.1
  1. Run the below command to install the dependency added in the above step:
groovy 
flutter pub get
  1. Import the RudderIntegrationAmplitudeFlutter in your application where you are initializing the SDK.
dart 
import 'package:rudder_integration_amplitude_flutter/rudder_integration_amplitude_flutter.dart';
  1. Finally, change the initialization of your RudderClient as shown:
dart 
final RudderController rudderClient = RudderController.instance;
RudderConfigBuilder builder = RudderConfigBuilder();
builder.withFactory(RudderIntegrationAmplitudeFlutter());
rudderClient.initialize(<write_key>, config: builder.build(), options: null);
For iOS platform, make sure that the minimum deployment target for your application’s target is at least 10.

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:

SDK Version setting Amplitude Browser SDK
2 (default) Amplitude Browser SDK 2.x
1 Amplitude Browser SDK 1.x

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:

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

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

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.
Setting Description
Auto-capture page views Let Amplitude’s Web SDK automatically detect browser navigation and send its own page view events.
Page URL Enrichment Enrich autocaptured events with page URL properties such as domain, path, URL, and title.
Track session events Send Amplitude session start and session end events.
Web Vitals Capture Core Web Vitals such as LCP, FCP, and TTFB as Amplitude events.
File Downloads Automatically capture file download interactions.
Frustration Interactions Capture frustration signals such as rage clicks and dead clicks.
Network Tracking Capture failed (5xx) network requests as events.
Element Interactions Automatically capture clicks and interactions on page elements.
Form Interactions Automatically capture form start and form submit interactions.

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:

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

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

Set the integrations object in your identify event as shown:

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

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

objectivec 
[[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:

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:

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

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

RudderStack processes revenue events in the following ways:

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

Note that:

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:

Dashboard setting Action
Track revenue per product is enabled Revenue is tracked separately for each product.
Track revenue per product is disabled Revenue is tracked as an aggregate at the event level.

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:

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

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:

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

objectivec 
[[RSClient sharedInstance] 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:

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

See Amplitude documentation for more information on this feature.

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

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