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.
• Session tracking in cloud-mode. Amplitude (Actions) supports sending session details from cloud-mode sources.

Getting started

1. Before you start, go to your Amplitude workspace. Click Settings in the bottom left, then click Projects in the left 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.)
6. On the next page enter your Amplitude API key and Secret key and click Verify credentials.
7. Next, choose how to create the mapping. You can click Quick Setup to use the defaults provided by Segment, or click Customized Setup to start from a blank mapping.

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

Connection Modes for Amplitude (Actions) destination

The Amplitude (actions) destination does not offer a device-mode connection mode. If you’re using one of Segment’s new libraries (Analytics.js 2.0, Swift or Kotlin) with the Actions-framework version of the destination, you do not need the device-mode connection.

Most previous deployments of the Amplitude Segment destination used the device-mode connection to use the session_id tracking feature. The new Actions-framework Amplitude destination, includes session ID tracking by default. This means you don’t need to bundle any software to run on the user’s device, or write any code. It also means that you can use more of the Segment platform features on data going to Amplitude, such as Protocols filtering and transformations, and Personas identity resolution.

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

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

The session tracking is automatically enabled on Javascript sources.

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

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.

Pre-built subscriptions

By default a new Amplitude (Actions) destination comes with the following subscriptions.

You can select these subscriptions by choosing “Quick Setup” when you first configure the destination. You can enable, edit, and disable them from the screen that appears.

Available Amplitude Actions

Build your own subscriptions! Combine supported triggers with the following Amplitude-supported actions:

• Log Event
• Identify User
• Map User
• Group Identify User

You can see the Segment event fields Amplitude accepts for each action in the Actions subscription set up page. Combine these

Log Event

The Track Calls, Page Calls, and Screen Calls default subscriptions all send Log Events to Amplitude when the Amplitude (Actions) destination receives the corresponding call.

This action enables you to define the Event Type the destination sends using a combination of plain text and information received from the received event.

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.

Identify User

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

This Action sets the user ID for a specific device ID, or updates the user properties. You can use this when you want to update user information without sending an Event to Amplitude.

Merge users with Anonymous ID and User ID

To merge an anonymous user and known user based on anonymousId and userId, update the value of the Device ID field so that anonymousId is the value present.

By default, the Amplitude Device ID property receives the user’s device ID from context.device.id and falls back to anonymousId if context.device.id is not present.

Map User

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

This Action merges two users together that would otherwise have different User IDs tracked in Amplitude. You can use this when you want to merge the users without sending an Event to Amplitude.

This kind of mapping is useful for users who have different ids across different Amplitude projects. The user’s user_ids act as child ids, which Amplitude maps to a single global_user_id. This allows you to analyze the user’s behavior in Amplitude’s Cross Portfolio view.

Group Identify User

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.

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.

Amplitude settings mapping