Amplitude (Actions) Destination

Amplitude is an event tracking and segmentation platform for your web and mobile apps. By analyzing the actions your users perform, you can gain a better understanding to drive retention, engagement, and conversion.

Benefits of Amplitude (Actions) vs Amplitude Classic

Amplitude (Actions) provides the following benefits over the classic Amplitude destination:

• Fewer settings. Data mapping for actions-based destinations happens in during configuration, which eliminates the need for most settings.
• Clearer mapping of data. Actions-based destinations enable you to define the mapping between the data Segment receives from your source, and the data Segment sends to the destination.
• Support for Amplitude’s HTTP API v2. Amplitude (Actions) is built on the latest version of Amplitude’s HTTP API.
• Revenue is a top-level property. Amplitude (Actions) elevates revenue to a top-level property in requests sent to Amplitude. This enables inclusion of this data in Amplitude features like customer LTV reports.
• Tracking in cloud-mode. Amplitude (Actions) supports sending details from cloud-mode sources.

Getting started

1. Before you start, go to your Amplitude workspace. Click Settings in the top right and then click Organization Settings to navigate to your Projects in the menu. Select your Project. Copy the Amplitude API Key and Secret Key for the project.
2. From the Segment web app, click Catalog, then click Destinations.
3. Find the Destinations Actions item in the left navigation, and click it.
4. Click the “Amplitude” item to select it and click Configure.
5. Choose which of your sources to connect the destination to. (You can connect more sources to the destination later.)

Once you have a mapping, you can follow the steps in the Destinations Actions documentation on Customizing mappings.

Log Purchases in existing destination instances

Initially, the Log Event Action was reporting purchases to Amplitude for all events containing a products array, even if the products were just added to cart. This inflated the LTV Chart in Amplitude.

To resolve this, purchase reporting takes place in a new Action called Log Purchase.

For instances created prior to before the Log Purchases action was released, you need to manually add the Log Purchases Action to report purchases to Amplitude.

To manually add the Log Purchases Action:

1. Add a new Mapping for the Log Purchases Action. The default trigger for this action is Order Completed events.
2. Modify the Trigger if you need to report purchases for any other events.
3. Modify the Trigger of Log Event to exclude these same events. This helps you to avoid sending the same event twice.
4. Enable the Log Purchases mapping.

Connection Modes for Amplitude (Actions) destination

The Amplitude (Actions) destination does not offer a device-mode connection mode. Previous deployments of the Amplitude Segment destination required the device-mode connection to use the session_id tracking feature. However, the Amplitude (Actions) destination now includes session ID tracking by default when you use Segment’s (Analytics.js 2.0 library.

Track sessions

Session tracking is available with Segment’s new libraries: Analytics.js 2.0, Swift or Kotlin.

When connected to the Analytics.js 2.0 source, Segment automatically loads a plugin on your website for session tracking and enrichment as an alternative to the Amplitude SDK. This means you don’t need to bundle any software or write any code to run on the user’s device, and can use more of the Segment platform features for data going to Amplitude, like Protocols filtering and transformations and Unify Identity Resolution.

If you’re using one of Segment’s Swift, Kotlin, or React Native libraries, you will need to include the Amplitude destination plugin to enable session tracking.

You can read more about Amplitude’s tracking sessions feature in Amplitude’s documentation.

Device ID Mappings

The Amplitude destination requires that each event include either a Device ID or a User ID. If a User ID isn’t present, Amplitude uses a Device ID, and vice versa, if a Device ID isn’t present, Amplitude uses the User ID.

By default, Segment maps the Segment property context.device.id to the Amplitude property Device ID. If context.device.id isn’t available, Segment maps the property anonymousId to the Amplitude Device ID. The Actions interface indicates this with the following contents of the Device ID field: coalesce( context.device.id anonymousId ).

Enable session tracking for Analytics.js 2.0

JavaScript sources automatically enable session tracking.

The session ID Segment passes to Amplitude stores locally in a key-value pair. View the value associated with the analytics_session_idkey to access the session ID. The session ID is set to timeout every 30 minutes by default.

Enable Amplitude session tracking for Swift

To enable session tracking in Amplitude when using the Segment Swift library:

1. Enable trackApplicationLifecycleEvents in your configuration.
2. Add the Amplitude Session plugin to your project.
3. Initialize the plugin (example)

   analytics?.add(plugin: AmplitudeSession(name: "Amplitude"))
   

Enable Amplitude session tracking for Kotlin

To enable session tracking in Amplitude when using the Segment Kotlin library:

1. Enable trackApplicationLifecycleEvents in your configuration.
2. Add the Amplitude Session plugin to your project.
3. Initialize the plugin

   analytics.add(AmplitudeSession())
   

Enable Amplitude session tracking for iOS

To enable session tracking in Amplitude when using the Segment iOS library:

1. Add the Amplitude Session middleware to your project.
2. Add the middleware & enable trackApplicationLifecycleEvents in your configuration:

   	NSString *const SEGMENT_WRITE_KEY = @" ... ";
   	SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:SEGMENT_WRITE_KEY];
   	configuration.trackApplicationLifecycleEvents = true
   	configuration.sourceMiddleware = @[[[SEGAmplitudeSession alloc] init]];
   	[SEGAnalytics setupWithConfiguration:configuration];
   

Enable Amplitude session tracking for Android

To enable session tracking in Amplitude when using the Segment Android library:

1. Add the Amplitude Session middleware to your project.

    implementation 'com.segment.analytics.android.integrations:amplitude:3.1.0'
   

2. Add the middleware & enable trackApplicationLifecycleEvents in your configuration:

   	String SEGMENT_WRITE_KEY = " ... ";
   	analytics = new Analytics.Builder(this, SEGMENT_WRITE_KEY)
                .trackApplicationLifecycleEvents()
                .useSourceMiddleware(new AmplitudeSessionId())
                .build();
   

Important differences from the classic Amplitude destination

The classic Amplitude destination captures the following user fields in device-mode (when it runs on the user’s device):

• Device Type (for example, Mac, PC, mobile device)
• Platform (for example iOS or Android)

Amplitude (Actions) runs in cloud-mode, and does not capture these fields.

Destination Settings

Available Presets

Amplitude (Actions) has the following presets:

Available Actions

Build your own Mappings. Combine supported triggers with the following Amplitude-supported actions:

• Map User

• Identify User

• Log Event

• Group Identify User

• Session Plugin

• Log Purchase

• Log Event V2

Map User

Merge two users together that would otherwise have different User IDs tracked in Amplitude.

Map User is a Cloud action. The default Trigger is: type = "alias"

Click to show / hide fields

Identify User

Set the user ID for a particular device ID or update user properties without sending an event to Amplitude.

Identify User is a Cloud action. The default Trigger is: type = "identify"

Click to show / hide fields

Log Event

Send an event to Amplitude.

Log Event is a Cloud action. The default Trigger is: type = "track"

Click to show / hide fields

Track Revenue Per Product

Amplitude has two different ways to track revenue associated with a multi-product purchase. You can choose which method you want to use using the Track Revenue Per Product destination setting.

If you disable the setting (“off”), Segment sends a single revenue event with the total amount purchased and adds revenue data the Amplitude “Order Completed” event. The “Product Purchased” events do not contain any native Amplitude revenue data.

If you enable the setting (“on”), Segment sends a single revenue event for each purchased product and adds Revenue data to each “Product Purchased” event. The “Order Completed” event does not contain any native Amplitude revenue data.

Make sure you format your events using the Track method spec. You must pass a revenue property, a price property, and a quantity property for each product in the products list.

Log Revenue v2

Segment’s iOS and Android sources can send revenue using Amplitude’s preferred logRevenueV2 method. Segment sets Amplitude’s special revenue properties, such as revenueType and productIdentifier, which Amplitude’s Revenue Analysis uses for Revenue Analysis and Revenue LTV charts. Segment uses the Amplitude eventProperties field to send any properties not mapped to Amplitude’s special properties.

* If properties.price is not present, Segment uses revenue instead, and sends that as price. In Segment’s iOS and Android libraries, if revenue isn’t present either, Segment sends the total.

Property names should be camelCase for Android implementations, and snake_case for iOS implementations.

Send To Batch Endpoint

If true, the destination sends events to Amplitude’s batch endpoint rather than the httpapi endpoint. Because Amplitude’s batch endpoint throttles traffic less restrictively than the Amplitude httpapi endpoint, enabling this setting can help to reduce 429 errors (throttling errors) from Amplitude.

Amplitude’s batch endpoint throttles data when the rate of events sharing the same user_id or device_id exceeds an average of 1,000/second over a 30-second period. See the Amplitude documentation for more about 429 errors and throttling in Amplitude.

Group Identify User

Set or update properties of particular groups. Note that these updates will only affect events going forward.

Group Identify User is a Cloud action. The default Trigger is: type = "group"

Click to show / hide fields

In the default configuration, Amplitude (Actions) triggers this mapping when it receives a Group call.

This Action sets or updates the properties of specific groups. You can use this when you want to update a group’s information without sending an Event to Amplitude.

These Group updates affect events that occur after you set up the Amplitude mapping. You cannot use this to group historical data.

If you don’t have an enterprise Amplitude account, or don’t have the Accounts add-on, Segment always adds groups as user_properties on a user record. As long as you specify the Action settings below, Segment adds a “group type” user property with a value of the “group value”.

To use Amplitude’s groups with Segment, you must enable the following Action settings and make sure to include the data values they need to function. These settings act as a mapping from Segment group traits to Amplitude group types and values.

• “Amplitude Group Type Trait”: This specifies what trait in your Group calls contains the Amplitude “group type”. In other words, it’s how you tell Segment which trait to use as the group type.

• “Amplitude Group Value Trait”: This specifies what trait in your Group calls contains the Amplitude “group value”. It’s how you tell Segment which trait to use as the group value.

Session Plugin

Generates a Session ID and attaches it to every Amplitude browser based event.

Session Plugin is a Web action. The default Trigger is: type = "track" or type = "identify" or type = "group" or type = "page" or type = "alias"

Click to show / hide fields

Log Purchase

Send an event to Amplitude.

Log Purchase is a Cloud action. The default Trigger is: type = "track"

Click to show / hide fields

Log Event V2

Send an event to Amplitude

Log Event V2 is a Cloud action. The default Trigger is: type = "track"

Click to show / hide fields

Migration from Amplitude Classic

Keep the following in mind if you plan to move to Amplitude (Actions) from a classic Amplitude destination.

Amplitude (Actions) uses Amplitude’s HTTP API v2

You configure the Amplitude (Actions) destination through Filters and Actions. Consult the table below for information about configuring your Amplitude (Actions) destination similarly to your classic Amplitude destination.

Set Once/Set Always fields

Amplitude restricts the mixing of top-level user properties with $set, $setOnce, or $setAlways operations in a single request, as outlined in Amplitude’s documentation.

To circumvent this within Segment, users can opt to exclusively map event parameters to either the User Properties field or to one of the user property operations (Set Once and/or Set Always) available in mappings. If you use the Set Once and/or Set Always fields, include all relevant fields in their respective mappings and do not configure mappings for User Properties in the same request.

Conversely, to send top-level user properties, map only to the User Properties field and exclude mappings for the Set Once and Set Always fields.

Amplitude settings mapping

Advanced Amplitude (Actions) settings

Increment Traits

The traitsToIncrement setting increases a user property by some numerical value. If the user property does not have a value set yet, Segment initializes it with a value of 0. The trait must have a numerical value so it can be incremented.

In the following example, the Amplitude User property friendCount equals 4.

"traits" : {"$add": {"friendCount": 3} }
"traits" : {"$add": {"friendCount": 1} }

FAQs and troubleshooting

Does Segment load the Amplitude SDK on the webpage to collect data?

Segment doesn’t load the Amplitude SDK directly on the webpage. Instead, Segment collects data using the Analytics.js library. Once events reach Segment’s servers, they are forwarded to Amplitude’s servers using Amplitude’s HTTP API.

How does Segment handle the Amplitude session ID?

The Analytics.js library includes a plugin that sets the Amplitude session ID on the device. This session ID is used to track sessions and is automatically attached to events sent to Amplitude. By default, the session ID is set to timeout after 30 minutes of inactivity. You can review the code implementation for setting the session ID.

How can I retrieve the Amplitude session ID set by Segment?

Since Segment doesn’t load the Amplitude SDK, the Amplitude native method amplitude.getInstance()._sessionId won’t work. You can retrieve the session ID using the this method:

localStorage.getItem('analytics_session_id');

This call accesses the session ID stored in the browser’s local storage. You can review the retrieval code.

Why doesn’t Segment automatically add the session_id to my Web Events?

For Segment to automatically add the session_id to your web events, your website must allow the following URL:

https://cdn.segment.com/next-integrations/actions/amplitude-plugins/..

To check if your website allows the URL:

1. Open your browser’s developer tools and inspect the network requests on your website.
2. Look for a request related to Amplitude.

If the request is missing:

• Ensure your browser settings or network configuration allow the URL to load.
• Check for any third-party script blockers or restrictions that might prevent it.