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.

This document is about a feature which is in beta. This means that the Destination Actions are in active development, and some functionality may change before it becomes generally available

Good to know: This page is about the Actions-framework Amplitude Segment destination. There’s also a page about the non-Actions Amplitude destination. Both of these destinations receives data from Segment. There’s also the Amplitude Engage Segment source, which sends data to Segment!

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.

Subscription Name Trigger Amplitude Action
Track Calls All track calls from the connected source Log Event
Page Calls All page calls from the connected source Log Event
Screen Calls All screen calls from the connected source Log Event
Identify Calls All identify calls from the connected source Identify User

Available Amplitude Actions

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

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.

Amplitude Property Segment Property Description
productId productId An identifier for the product.
quantity quantity The quantity of products purchased. Note: revenue = quantity * price.
price price or revenue (or total for mobile, see note below) The price of the products purchased, and this can be negative.
revenueType revenueType The revenue type (for example tax, refund, income).
receiptSignature receiptSignature (Android) The receipt signature.
receipt receipt Required if you want to verify the revenue event.
eventProperties Any remaining properties A NSDictionary or Map of event properties to include in the revenue event.

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

Amplitude does not support currency conversion. You should normalize all revenue data to your currency of choice before sending it to Amplitude.

Send To Batch Endpoint

This endpoint is available when you send data in Cloud-mode.

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.

Segment identifier name Amplitude identifier name
previousId user_id
userId global_user_id

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.

Groups are an enterprise feature in Amplitude, and are available if you’ve purchased the Accounts add-on.

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 are on a Business Tier Segment plan, you can use Replay to run historical data through the Amplitude (Actions) destination to apply the grouping.

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

If you used Amplitude Classic in cloud-mode, you’ll notice different responses from Amplitude to calls you make with the destination. Classic Amplitude was built on Amplitude’s now-deprecated HTTP API v1.

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.

Contact Segment support if you find features missing from the Amplitude (Actions) destination that were available in the classic Amplitude destination.

Amplitude settings mapping

amplitude Classic Destination Setting How to enable in amplitude (Actions)
Connection Settings
API Key
Cloud Device-web Device-mobile

Global Setting


Track Products Once
Device-web

Not applicable to Cloud mode

Version Name
Device-web

Action field App Version.


Defaults to context.app.version.

Connection Mode
Cloud Device-web Device-mobile

Actions support Cloud mode connections

Page and Screen
Track all pages to Amplitude
Cloud Device-web Device-mobile

Subscription Page Calls


When enabled, Amplitude (Actions) tracks all Page calls by default

Track all Screens
Cloud Device-web Device-mobile

Subscription Page Calls


When enabled, Amplitude (Actions) tracks all Screen calls by default

Track Categorized Pages to Amplitude
Cloud Device-web Device-mobile

Subscription Page Calls


Add a Trigger filter condition to check that Event Property category exists

Track Named Pages to Amplitude
Cloud Device-web Device-mobile

Subscription Page Calls


Add a Trigger filter condition to check that Event Property name exists

Traits
Group Type Trait
Cloud Device-web Device-mobile

Subscription Group Identify User.


Select a value in the Group Type actions field. This field is mandatory in Amplitude (Actions). In the Amplitude Classic destination, ommiting a value for property field resulted in Amplitude creating a group called [Segment] Group.

Group Value Trait
Cloud Device-web Device-mobile

Subscription Group Identify User.


Select a value in the Group Value actions field. This field is mandatory in Amplitude actions. In the Amplitude Classic destination, ommiting a value for this property resulted in an alpha-numeric value.

Traits to Append
Cloud

Not supported with Actions

Traits to Increment
Cloud Device-web Device-mobile

Not supported with Actions

Traits to Prepend
Cloud

Not supported with Actions

Traits to Set Once
Cloud Device-web Device-mobile

Not supported with Actions

Other Settings
Append Fields to Event Properties
Device-web Device-mobile

Not supported with Actions

Batch Events
Device-web

Use Batch Endpoint field on the Log Event action


Enable Location Listening
Device-mobile

Use context.location.latitude and context.location.longitude on the mobile client. Other destinations may also process this data. Amplitude uses IP-based location, if you’re unable to send latitude and longitude.

Event Upload period millis
Device-web

Not configurable for Cloud-mode batching

Event Upload Threshold
Device-web

Not configurable for Cloud-mode batching

Force HTTPS
Device-web

Not configurable in Cloud-mode, https is enabled by default.

Map Query Params to Custom Property
Cloud Device-web

Not supported with Actions

Prefer Anonymous Device ID
Cloud Device-web Device-mobile

Actions field Device ID.


Replace the contents of the field with your preferred value.

Save Referrer, URL Params, GCLID Once per Session
Device-web

This setting supported an edge case that is not applicable to Amplitude (Actions)

Secret Key
Cloud Device-web Device-mobile

Global Setting


Enable Alias
Cloud

Use the Map User action.


The Map User action is not enabled by default. Add a new Subscription to access the Map User action.

Send to Batch Endpoint
Cloud

Use Batch Endpoint field on the Log Event action


Track GCLID
Device-web

Not supported with Actions

Track Referrer to Amplitude
Device-web

Not supported with Actions

Track Revenue per Product
Cloud Device-web Device-mobile

Actions field Track Revenue Per Product.


Available in any subscription that uses the Log Event action.
In Amplitude (Actions), this setting elevates revenue to a top-level property. This allows revenue data to pass through to Amplitude’s LTV reports.

Track Session Events to Amplitude
Device-web

This setting sends [Session Started] and [Session Ended] events. However, Session ID is used most often in session-based reporting. Analytics.js sources track Session ID by default. Mobile sources require a plugin to enable Session ID tracking. For more information, see Enable Session Tracking for Analytics.js 2.0

Track UTM Properties to Amplitude
Cloud Device-web

Not supported with Actions

Unset Params Referrer on New Session
Device-web

Not supported with Actions

Use Advertising ID for Device ID
Cloud Device-web Device-mobile

Actions field Device ID.


Update the value so your preferred field appears first in the coalesce() function.

Send Custom Language and Country Properties

Actions fields Language and Country


These fields are set by default with values from the context object.

Use Log Revenue v2 API
Device-web Device-mobile

Actions supports Revenue v2. Confirm revenue reporting is working as expected if you migrate from the Classic Amplitude destination where this setting was disabled

This page was last modified: 20 Sep 2021



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account