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.

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

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.

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. This is indicated by the following text in 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())
   

Available Amplitude Actions

Amplitude supports the following 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.

Quick set-up actions

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.

Amplitude’s Log Event Action

In the default configuration, the Log Event mapping is triggered when Segment sends a Track call to Amplitude (Actions).

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. Revenue data is added to 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 product that was purchased. Revenue data is added to each “Product Purchased” event, and 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.

Send To Batch Endpoint

If true, events are sent to Amplitude’s batch endpoint rather than to their 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, this mapping is triggered when Segment sends an Identify call to Amplitude (Actions).

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.

Map User

In the default configuration, this mapping is triggered when Segment sends an Alias call to Amplitude (Actions).

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.

Group Identify User

In the default configuration, this mapping is triggered when Segment sends a Group call to Amplitude (Actions).

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 only affect events that occur after you set up the Amplitude mapping. You cannot use this to group historical data.

Important differences from the classic Amplitude destination

The following user fields are captured by the classic Amplitude destination in device-mode (when it runs on the user’s device), but are not captured by Amplitude (Actions):

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

Replicating classic Amplitude destination settings

Most of the classic Amplitude destination settings were related to device-mode collection (for example, batching or Log Revenue V2), and do not apply to the Amplitude (Actions) destination, which runs in cloud-mode. The following sections discuss how to replicate the old settings where possible.

Track Named, Categorized, or All Pages or Screens

The default Amplitude (Actions) subscription sends all Page and Screen calls. To replicate the old behavior, change the trigger to include only events that contain name or category.

Prefer Anonymous ID for Device ID

To replicate the old behavior, change the mapping for Device ID field. Default:

'@if': {
        exists: { '@path': '$.context.device.id' },
        then: { '@path': '$.context.device.id' },
        else: { '@path': '$.anonymousId' }
      }

Use AdvertisingId for DeviceId

To replicate the old behavior, change the mapping for Device ID field. Default:

'@if': {
        exists: { '@path': '$.context.device.id' },
        then: { '@path': '$.context.device.id' },
        else: { '@path': '$.anonymousId' }
        }

Location Tracking

Location Tracking is a feature of Amplitude’s mobile SDKs and is not supported in Amplitude (Actions) which run in cloud-mode only. This setting required that the user grant location permission for the mobile app. This is different from the IP-based location lookup that Amplitude can perform.

To work around this limitation, send context.location.latitude and context.location.longitude from your app, and let Amplitude perform the lookup.