# Amplitude (Actions) Destination ## Destination Info * Accepts [Page](/docs/segment/connections/spec/page), [Alias](/docs/segment/connections/spec/alias), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls. * Refer to it as **Actions Amplitude** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object) > \[!NOTE] > > This page is about the Amplitude (Actions) Destination. See below for information about other versions of the Amplitude destination: > > * [Amplitude (Classic)](/docs/segment/connections/destinations/catalog/amplitude) [Amplitude](https://amplitude.com/) 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](https://developers.amplitude.com/docs/http-api-v2). * **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](https://analytics.amplitude.com). 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](/docs/segment/connections/destinations/actions/#customize-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](/docs/segment/connections/sources/catalog/libraries/website/javascript/) library. ### Track sessions Session tracking is available with Segment's new libraries: [Analytics.js 2.0](/docs/segment/connections/sources/catalog/libraries/website/javascript/), [Swift](/docs/segment/connections/sources/catalog/libraries/mobile/apple/) or [Kotlin](/docs/segment/connections/sources/catalog/libraries/mobile/kotlin-android/). 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](/docs/segment/protocols/) and [Unify Identity Resolution](/docs/segment/unify/identity-resolution/). If you're using one of Segment's [Swift](/docs/segment/connections/sources/catalog/libraries/mobile/apple/), [Kotlin](/docs/segment/connections/sources/catalog/libraries/mobile/kotlin-android/), or [React Native](/docs/segment/connections/sources/catalog/libraries/mobile/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](https://help.amplitude.com/hc/en-us/articles/115002323627-Track-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_id`key 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](https://github.com/segmentio/analytics-swift): 1. Enable `trackApplicationLifecycleEvents` in your configuration. 2. Add the [Amplitude Session plugin](https://github.com/segment-integrations/analytics-swift-amplitude/blob/main/Sources/SegmentAmplitude/AmplitudeSession.swift) to your project. 3. Initialize the plugin ([example](https://github.com/segmentio/analytics-swift/blob/main/Examples/apps/DestinationsExample/DestinationsExample/AppDelegate.swift)) ```swift analytics?.add(plugin: AmplitudeSession(name: "Amplitude")) ``` ### Enable Amplitude session tracking for Kotlin To enable session tracking in Amplitude when using the [Segment Kotlin library](https://github.com/segmentio/analytics-kotlin): 1. Enable `trackApplicationLifecycleEvents` in your configuration. 2. Add the [Amplitude Session plugin](https://github.com/segment-integrations/analytics-kotlin-amplitude/blob/main/lib/src/main/java/com/segment/analytics/kotlin/destinations/amplitude/AmplitudeSession.kt) to your project. 3. Initialize the plugin ```kotlin analytics.add(AmplitudeSession()) ``` ### Enable Amplitude session tracking for iOS To enable session tracking in Amplitude when using the [Segment iOS library](https://github.com/segmentio/analytics-ios): 1. Add the [Amplitude Session middleware](https://github.com/segment-integrations/analytics-ios-integration-amplitude/blob/amplitude-session/Pod/Classes/SEGAmplitudeSession.m) to your project. 2. Add the middleware & enable `trackApplicationLifecycleEvents` in your configuration: ```objective-c 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](https://github.com/segmentio/analytics-android): 1. Add the [Amplitude Session middleware](https://github.com/segment-integrations/analytics-android-integration-amplitude/blob/master/src/main/java/com/segment/analytics/android/integrations/amplitude/AmplitudeSessionId.java) to your project. ```java implementation 'com.segment.analytics.android.integrations:amplitude:3.1.0' ``` 2. Add the middleware & enable `trackApplicationLifecycleEvents` in your configuration: ```java 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 | Field | Description | Required | Type | | --------------- | --------------------------------------------------------------------------------------------------- | -------- | -------- | | API Key | Amplitude project API key. You can find this key in the "General" tab of your Amplitude project. | Yes | password | | Endpoint Region | The region to send your data. | No | select | | Secret Key | Amplitude project secret key. You can find this key in the "General" tab of your Amplitude project. | Yes | password | ## Available Presets Amplitude (Actions) has the following presets | Preset Name | Trigger | Default Action | | ------------------------ | ------------------------------------------------------------------------------------------------------------------ | -------------- | | Track Calls | Event type = "track" and event != "Order Completed" | Log Event V2 | | Screen Calls | Event type = "screen" | Log Event V2 | | Identify Calls | Event type = "identify" | Identify User | | Page Calls | Event type = "page" | Log Event V2 | | Browser Session Tracking | Event type = "track", Event type = "identify", Event type = "group", Event type = "page", Event type = "alias" | Session Plugin | | Order Completed Calls | Event type = "track" and event = "Order Completed" | Log Purchase | ## Available Actions Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Amplitude-supported actions: > \[!NOTE] > > Individual destination instances have support a maximum of 50 mappings. * [Map User](#map-user) * [Identify User](#identify-user-25) * [Log Event](#log-event-1) * [Group Identify User](#group-identify-user-2) * [Session Plugin](#session-plugin) * [Log Purchase](#log-purchase) * [Log Event V2](#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"` | Field | Description | Required | Type | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | The User ID to be associated. | No | STRING | | Global User ID | The Global User ID to associate with the User ID. | No | STRING | | Minimum ID Length | Amplitude has a default minimum id length (\`min\_id\_length\`) of 5 characters for user\_id and device\_id fields. This field allows the minimum to be overridden to allow shorter id lengths. | No | INTEGER | ### 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"` | Field | Description | Required | Type | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | User ID | A UUID (unique user ID) specified by you. \*\*Note:\*\* If you send a request with a user ID that is not in the Amplitude system yet, then the user tied to that ID will not be marked new until their first event. Required unless device ID is present. | No | STRING | | Device ID | A device specific identifier, such as the Identifier for Vendor (IDFV) on iOS. Required unless user ID is present. | No | STRING | | User Properties | Additional data tied to the user in Amplitude. Each distinct value will show up as a user segment on the Amplitude dashboard. Object depth may not exceed 40 layers. \*\*Note:\*\* You can store property values in an array and date values are transformed into string values. | No | OBJECT | | Groups | Groups of users for Amplitude's account-level reporting feature. Note: You can only track up to 5 groups. Any groups past that threshold will not be tracked. \*\*Note:\*\* This feature is only available to Amplitude Enterprise customers who have purchased the Amplitude Accounts add-on. | No | OBJECT | | App Version | Version of the app the user is on. | No | STRING | | Platform | The platform of the user's device. | No | STRING | | OS Name | The mobile operating system or browser of the user's device. | No | STRING | | OS Version | The version of the mobile operating system or browser of the user's device. | No | STRING | | Device Brand | The brand of user's the device. | No | STRING | | Device Manufacturer | The manufacturer of the user's device. | No | STRING | | Device Model | The model of the user's device. | No | STRING | | Carrier | The user's mobile carrier. | No | STRING | | Country | The country in which the user is located. | No | STRING | | Region | The geographical region in which the user is located. | No | STRING | | City | The city in which the user is located. | No | STRING | | Designated Market Area | The Designated Market Area in which the user is located. | No | STRING | | Language | Language the user has set on their device or browser. | No | STRING | | Is Paying | Whether the user is paying or not. | No | BOOLEAN | | Initial Version | The version of the app the user was first on. | No | STRING | | Insert ID | Amplitude will deduplicate subsequent events sent with this ID we have already seen before within the past 7 days. Amplitude recommends generating a UUID or using some combination of device ID, user ID, event type, event ID, and time. | No | STRING | | User Agent | The user agent of the device sending the event. | No | STRING | | User Agent Parsing | Enabling this setting will set the Device manufacturer, Device Model and OS Name properties based on the user agent string provided in the userAgent field | No | BOOLEAN | | Include Raw User Agent | Enabling this setting will send user\_agent based on the raw user agent string provided in the userAgent field | No | BOOLEAN | | UTM Properties | UTM Tracking Properties | No | OBJECT | | Referrer | The referrer of the web request. Sent to Amplitude as both last touch “referrer” and first touch “initial\_referrer” | No | STRING | | Minimum ID Length | Amplitude has a default minimum id length of 5 characters for user\_id and device\_id fields. This field allows the minimum to be overridden to allow shorter id lengths. | No | INTEGER | | Library | The name of the library that generated the event. | No | STRING | | User Agent Data | The user agent data of device sending the event | No | OBJECT | ### Log Event Send an event to Amplitude. Log Event is a **Cloud** action. The default Trigger is `type = "track"` | Field | Description | Required | Type | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------- | | User ID | A readable ID specified by you. Must have a minimum length of 5 characters. Required unless device ID is present. \*\*Note:\*\* If you send a request with a user ID that is not in the Amplitude system yet, then the user tied to that ID will not be marked new until their first event. | No | STRING | | Device ID | A device-specific identifier, such as the Identifier for Vendor on iOS. Required unless user ID is present. If a device ID is not sent with the event, it will be set to a hashed version of the user ID. | No | STRING | | Event Type | A unique identifier for your event. | Yes | STRING | | Session ID | The start time of the session, necessary if you want to associate events with a particular system. To use automatic Amplitude session tracking in browsers, enable Analytics 2.0 on your connected source. | No | DATETIME | | Timestamp | The timestamp of the event. If time is not sent with the event, it will be set to the request upload time. | No | DATETIME | | Event Properties | An object of key-value pairs that represent additional data to be sent along with the event. You can store property values in an array, but note that Amplitude only supports one-dimensional arrays. Date values are transformed into string values. Object depth may not exceed 40 layers. | No | OBJECT | | User Properties | An object of key-value pairs that represent additional data tied to the user. You can store property values in an array, but note that Amplitude only supports one-dimensional arrays. Date values are transformed into string values. Object depth may not exceed 40 layers. | No | OBJECT | | Groups | Groups of users for the event as an event-level group. You can only track up to 5 groups. \*\*Note:\*\* This Amplitude feature is only available to Enterprise customers who have purchased the Accounts add-on. | No | OBJECT | | App Version | The current version of your application. | No | STRING | | Platform | Platform of the device. If using analytics.js to send events from a Browser and no if no Platform value is provided, the value "Web" will be sent. | No | STRING | | OS Name | The name of the mobile operating system or browser that the user is using. | No | STRING | | OS Version | The version of the mobile operating system or browser the user is using. | No | STRING | | Device Brand | The device brand that the user is using. | No | STRING | | Device Manufacturer | The device manufacturer that the user is using. | No | STRING | | Device Model | The device model that the user is using. | No | STRING | | Carrier | The carrier that the user is using. | No | STRING | | Country | The current country of the user. | No | STRING | | Region | The current region of the user. | No | STRING | | City | The current city of the user. | No | STRING | | Designated Market Area | The current Designated Market Area of the user. | No | STRING | | Language | The language set by the user. | No | STRING | | Price | The price of the item purchased. Required for revenue data if the revenue field is not sent. You can use negative values to indicate refunds. | No | NUMBER | | Quantity | The quantity of the item purchased. Defaults to 1 if not specified. | No | INTEGER | | Revenue | Revenue = price \* quantity. If you send all 3 fields of price, quantity, and revenue, then (price \* quantity) will be used as the revenue value. You can use negative values to indicate refunds. \*\*Note:\*\* You will need to explicitly set this if you are using the Amplitude in cloud-mode. | No | NUMBER | | Product ID | An identifier for the item purchased. You must send a price and quantity or revenue with this field. | No | STRING | | Revenue Type | The type of revenue for the item purchased. You must send a price and quantity or revenue with this field. | No | STRING | | Latitude | The current Latitude of the user. | No | NUMBER | | Longtitude | The current Longitude of the user. | No | NUMBER | | IP Address | The IP address of the user. Use "$remote" to use the IP address on the upload request. Amplitude will use the IP address to reverse lookup a user's location (city, country, region, and DMA). Amplitude has the ability to drop the location and IP address from events once it reaches our servers. You can submit a request to Amplitude's platform specialist team here to configure this for you. | No | STRING | | Identifier For Advertiser (IDFA) | Identifier for Advertiser. \_(iOS)\_ | No | STRING | | Identifier For Vendor (IDFV) | Identifier for Vendor. \_(iOS)\_ | No | STRING | | Google Play Services Advertising ID | Google Play Services advertising ID. \_(Android)\_ | No | STRING | | Android ID | Android ID (not the advertising ID). \_(Android)\_ | No | STRING | | Event ID | An incrementing counter to distinguish events with the same user ID and timestamp from each other. Amplitude recommends you send an event ID, increasing over time, especially if you expect events to occur simultanenously. | No | INTEGER | | Insert ID | Amplitude will deduplicate subsequent events sent with this ID we have already seen before within the past 7 days. Amplitude recommends generating a UUID or using some combination of device ID, user ID, event type, event ID, and time. | No | STRING | | Library Settings | Specifies the "library" value to send to Amplitude. Select "Use Mapping" to set the value from the "Library Mapping" field. "Legacy Behaviour" sets the value to "segment". | No | OBJECT | | Products | The list of products purchased. | No | OBJECT | | Use Batch Endpoint | If true, events are sent to Amplitude's \`batch\` endpoint rather than their \`httpapi\` events endpoint. Enabling this setting may help reduce 429s – or throttling errors – from Amplitude. More information about Amplitude's throttling is available in \[their docs]\(https://developers.amplitude.com/docs/batch-event-upload-api#429s-in-depth). | No | BOOLEAN | | User Agent | The user agent of the device sending the event. | No | STRING | | User Agent Parsing | Enabling this setting will set the Device manufacturer, Device Model and OS Name properties based on the user agent string provided in the userAgent field | No | BOOLEAN | | Include Raw User Agent | Enabling this setting will send user\_agent based on the raw user agent string provided in the userAgent field | No | BOOLEAN | | UTM Properties | UTM Tracking Properties | No | OBJECT | | Referrer | The referrer of the web request. Sent to Amplitude as both last touch “referrer” and first touch “initial\_referrer” | No | STRING | | Minimum ID Length | Amplitude has a default minimum id lenght of 5 characters for user\_id and device\_id fields. This field allows the minimum to be overridden to allow shorter id lengths. | No | INTEGER | | User Agent Data | The user agent data of device sending the event | No | OBJECT | #### Track Revenue Per Product > \[!NOTE] > > If you use Track Revenue Per Product, add a `revenue` property inside the `products` array of the Order Completed event. 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](/docs/segment/connections/spec/track/). 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. > \[!NOTE] > > 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 > \[!NOTE] > > 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](https://developers.amplitude.com/#429s-in-depth). ### 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"` | Field | Description | Required | Type | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | | User ID | A UUID (unique user ID) specified by you. \*\*Note:\*\* If you send a request with a user ID that is not in the Amplitude system yet, then the user tied to that ID will not be marked new until their first event. If either user ID or device ID is present, an associate user to group call will be made. | No | STRING | | Device ID | A device specific identifier, such as the Identifier for Vendor (IDFV) on iOS. If either user ID or device ID is present, an associate user to group call will be made. | No | STRING | | Insert ID | Amplitude will deduplicate subsequent events sent with this ID we have already seen before within the past 7 days. Amplitude recommends generating a UUID or using some combination of device ID, user ID, event type, event ID, and time. | No | STRING | | Timestamp | The timestamp of the event. If time is not sent with the event, it will be set to the request upload time. | No | STRING | | Group Properties | Additional data tied to the group in Amplitude. | No | OBJECT | | Group Type | The type of the group | Yes | STRING | | Group Value | The value of the group | Yes | STRING | | Minimum ID Length | Amplitude has a default minimum id length of 5 characters for user\_id and device\_id fields. This field allows the minimum to be overridden to allow shorter id lengths. | No | INTEGER | In the default configuration, Amplitude (Actions) triggers this mapping when it receives a Group call. > \[!WARNING] > > 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. > \[!TIP] > > If you are on a Business Tier Segment plan, you can use [Replay](/docs/segment/guides/what-is-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. ### 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"` | Field | Description | Required | Type | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Session Length | Time in milliseconds to be used before considering a session stale. | No | NUMBER | | Allow Session Tracking | if set to true, 'Session Started' and 'Session Ended' events will be triggered from the user's browser. These events will be forwarded to all connected Destinations. | No | BOOLEAN | | Session Start Event | The event name to use for the session start event. | No | STRING | | Session End Event | The event name to use for the session end event. | No | STRING | ### Log Purchase Send purchase/revenue events to Amplitude. Sends one main event with the original event type and total revenue, plus additional "Product Purchased" events for each product in the order. Log Purchase is a **Cloud** action. The default Trigger is `type = "track"` | Field | Description | Required | Type | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------- | | Track Revenue Per Product | When enabled, track revenue with each product within the event. When disabled, track total revenue once for the event. | No | BOOLEAN | | User ID | A readable ID specified by you. Must have a minimum length of 5 characters. Required unless device ID is present. \*\*Note:\*\* If you send a request with a user ID that is not in the Amplitude system yet, then the user tied to that ID will not be marked new until their first event. | No | STRING | | Device ID | A device-specific identifier, such as the Identifier for Vendor on iOS. Required unless user ID is present. If a device ID is not sent with the event, it will be set to a hashed version of the user ID. | No | STRING | | Event Type | A unique identifier for your event. | Yes | STRING | | Session ID | The start time of the session, necessary if you want to associate events with a particular system. To use automatic Amplitude session tracking in browsers, enable Analytics 2.0 on your connected source. | No | DATETIME | | Timestamp | The timestamp of the event. If time is not sent with the event, it will be set to the request upload time. | No | DATETIME | | Event Properties | An object of key-value pairs that represent additional data to be sent along with the event. You can store property values in an array, but note that Amplitude only supports one-dimensional arrays. Date values are transformed into string values. Object depth may not exceed 40 layers. | No | OBJECT | | User Properties | An object of key-value pairs that represent additional data tied to the user. You can store property values in an array, but note that Amplitude only supports one-dimensional arrays. Date values are transformed into string values. Object depth may not exceed 40 layers. | No | OBJECT | | Groups | Groups of users for the event as an event-level group. You can only track up to 5 groups. \*\*Note:\*\* This Amplitude feature is only available to Enterprise customers who have purchased the Accounts add-on. | No | OBJECT | | App Version | The current version of your application. | No | STRING | | Platform | Platform of the device. If using analytics.js to send events from a Browser and no if no Platform value is provided, the value "Web" will be sent. | No | STRING | | OS Name | The name of the mobile operating system or browser that the user is using. | No | STRING | | OS Version | The version of the mobile operating system or browser the user is using. | No | STRING | | Device Brand | The device brand that the user is using. | No | STRING | | Device Manufacturer | The device manufacturer that the user is using. | No | STRING | | Device Model | The device model that the user is using. | No | STRING | | Carrier | The carrier that the user is using. | No | STRING | | Country | The current country of the user. | No | STRING | | Region | The current region of the user. | No | STRING | | City | The current city of the user. | No | STRING | | Designated Market Area | The current Designated Market Area of the user. | No | STRING | | Language | The language set by the user. | No | STRING | | Price | The price of the item purchased. Required for revenue data if the revenue field is not sent. You can use negative values to indicate refunds. | No | NUMBER | | Quantity | The quantity of the item purchased. Defaults to 1 if not specified. | No | INTEGER | | Revenue | Revenue = price \* quantity. If you send all 3 fields of price, quantity, and revenue, then (price \* quantity) will be used as the revenue value. You can use negative values to indicate refunds. \*\*Note:\*\* You will need to explicitly set this if you are using the Amplitude in cloud-mode. | No | NUMBER | | Product ID | An identifier for the item purchased. You must send a price and quantity or revenue with this field. | No | STRING | | Revenue Type | The type of revenue for the item purchased. You must send a price and quantity or revenue with this field. | No | STRING | | Latitude | The current Latitude of the user. | No | NUMBER | | Longtitude | The current Longitude of the user. | No | NUMBER | | IP Address | The IP address of the user. Use "$remote" to use the IP address on the upload request. Amplitude will use the IP address to reverse lookup a user's location (city, country, region, and DMA). Amplitude has the ability to drop the location and IP address from events once it reaches our servers. You can submit a request to Amplitude's platform specialist team here to configure this for you. | No | STRING | | Identifier For Advertiser (IDFA) | Identifier for Advertiser. \_(iOS)\_ | No | STRING | | Identifier For Vendor (IDFV) | Identifier for Vendor. \_(iOS)\_ | No | STRING | | Google Play Services Advertising ID | Google Play Services advertising ID. \_(Android)\_ | No | STRING | | Android ID | Android ID (not the advertising ID). \_(Android)\_ | No | STRING | | Event ID | An incrementing counter to distinguish events with the same user ID and timestamp from each other. Amplitude recommends you send an event ID, increasing over time, especially if you expect events to occur simultanenously. | No | INTEGER | | Insert ID | Amplitude will deduplicate subsequent events sent with this ID we have already seen before within the past 7 days. Amplitude recommends generating a UUID or using some combination of device ID, user ID, event type, event ID, and time. | No | STRING | | Library Settings | Specifies the "library" value to send to Amplitude. Select "Use Mapping" to set the value from the "Library Mapping" field. "Legacy Behaviour" sets the value to "segment". | No | OBJECT | | Products | The list of products purchased. | No | OBJECT | | Use Batch Endpoint | If true, events are sent to Amplitude's \`batch\` endpoint rather than their \`httpapi\` events endpoint. Enabling this setting may help reduce 429s – or throttling errors – from Amplitude. More information about Amplitude's throttling is available in \[their docs]\(https://developers.amplitude.com/docs/batch-event-upload-api#429s-in-depth). | No | BOOLEAN | | User Agent | The user agent of the device sending the event. | No | STRING | | User Agent Parsing | Enabling this setting will set the Device manufacturer, Device Model and OS Name properties based on the user agent string provided in the userAgent field | No | BOOLEAN | | Include Raw User Agent | Enabling this setting will send user\_agent based on the raw user agent string provided in the userAgent field | No | BOOLEAN | | UTM Properties | UTM Tracking Properties | No | OBJECT | | Referrer | The referrer of the web request. Sent to Amplitude as both last touch “referrer” and first touch “initial\_referrer” | No | STRING | | Minimum ID Length | Amplitude has a default minimum id lenght of 5 characters for user\_id and device\_id fields. This field allows the minimum to be overridden to allow shorter id lengths. | No | INTEGER | | User Agent Data | The user agent data of device sending the event | No | OBJECT | ### Log Event V2 Send an event to Amplitude Log Event V2 is a **Cloud** action. The default Trigger is `type = "track"` | Field | Description | Required | Type | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------- | | User ID | A readable ID specified by you. Must have a minimum length of 5 characters. Required unless device ID is present. \*\*Note:\*\* If you send a request with a user ID that is not in the Amplitude system yet, then the user tied to that ID will not be marked new until their first event. | No | STRING | | Device ID | A device-specific identifier, such as the Identifier for Vendor on iOS. Required unless user ID is present. If a device ID is not sent with the event, it will be set to a hashed version of the user ID. | No | STRING | | Event Type | A unique identifier for your event. | Yes | STRING | | Session ID | The start time of the session, necessary if you want to associate events with a particular system. To use automatic Amplitude session tracking in browsers, enable Analytics 2.0 on your connected source. | No | DATETIME | | Timestamp | The timestamp of the event. If time is not sent with the event, it will be set to the request upload time. | No | DATETIME | | Event Properties | An object of key-value pairs that represent additional data to be sent along with the event. You can store property values in an array, but note that Amplitude only supports one-dimensional arrays. Date values are transformed into string values. Object depth may not exceed 40 layers. | No | OBJECT | | User Properties | An object of key-value pairs that represent additional data tied to the user. You can store property values in an array, but note that Amplitude only supports one-dimensional arrays. Date values are transformed into string values. Object depth may not exceed 40 layers. | No | OBJECT | | Groups | Groups of users for the event as an event-level group. You can only track up to 5 groups. \*\*Note:\*\* This Amplitude feature is only available to Enterprise customers who have purchased the Accounts add-on. | No | OBJECT | | App Version | The current version of your application. | No | STRING | | Platform | Platform of the device. If using analytics.js to send events from a Browser and no if no Platform value is provided, the value "Web" will be sent. | No | STRING | | OS Name | The name of the mobile operating system or browser that the user is using. | No | STRING | | OS Version | The version of the mobile operating system or browser the user is using. | No | STRING | | Device Brand | The device brand that the user is using. | No | STRING | | Device Manufacturer | The device manufacturer that the user is using. | No | STRING | | Device Model | The device model that the user is using. | No | STRING | | Carrier | The carrier that the user is using. | No | STRING | | Country | The current country of the user. | No | STRING | | Region | The current region of the user. | No | STRING | | City | The current city of the user. | No | STRING | | Designated Market Area | The current Designated Market Area of the user. | No | STRING | | Language | The language set by the user. | No | STRING | | Price | The price of the item purchased. Required for revenue data if the revenue field is not sent. You can use negative values to indicate refunds. | No | NUMBER | | Quantity | The quantity of the item purchased. Defaults to 1 if not specified. | No | INTEGER | | Revenue | Revenue = price \* quantity. If you send all 3 fields of price, quantity, and revenue, then (price \* quantity) will be used as the revenue value. You can use negative values to indicate refunds. \*\*Note:\*\* You will need to explicitly set this if you are using the Amplitude in cloud-mode. | No | NUMBER | | Product ID | An identifier for the item purchased. You must send a price and quantity or revenue with this field. | No | STRING | | Revenue Type | The type of revenue for the item purchased. You must send a price and quantity or revenue with this field. | No | STRING | | Latitude | The current Latitude of the user. | No | NUMBER | | Longtitude | The current Longitude of the user. | No | NUMBER | | IP Address | The IP address of the user. Use "$remote" to use the IP address on the upload request. Amplitude will use the IP address to reverse lookup a user's location (city, country, region, and DMA). Amplitude has the ability to drop the location and IP address from events once it reaches our servers. You can submit a request to Amplitude's platform specialist team here to configure this for you. | No | STRING | | Identifier For Advertiser (IDFA) | Identifier for Advertiser. \_(iOS)\_ | No | STRING | | Identifier For Vendor (IDFV) | Identifier for Vendor. \_(iOS)\_ | No | STRING | | Google Play Services Advertising ID | Google Play Services advertising ID. \_(Android)\_ | No | STRING | | Android ID | Android ID (not the advertising ID). \_(Android)\_ | No | STRING | | Event ID | An incrementing counter to distinguish events with the same user ID and timestamp from each other. Amplitude recommends you send an event ID, increasing over time, especially if you expect events to occur simultanenously. | No | INTEGER | | Insert ID | Amplitude will deduplicate subsequent events sent with this ID we have already seen before within the past 7 days. Amplitude recommends generating a UUID or using some combination of device ID, user ID, event type, event ID, and time. | No | STRING | | Library Settings | Specifies the "library" value to send to Amplitude. Select "Use Mapping" to set the value from the "Library Mapping" field. "Legacy Behaviour" sets the value to "segment". | No | OBJECT | | Products | The list of products purchased. | No | OBJECT | | Set Once | The following fields will only be set as user properties if they do not already have a value. | No | OBJECT | | Set Always | The following fields will be set as user properties for every event. | No | OBJECT | | Add | Increment a user property by a number with add. If the user property doesn't have a value set yet, it's initialized to 0. | No | OBJECT | | Use Batch Endpoint | If true, events are sent to Amplitude's \`batch\` endpoint rather than their \`httpapi\` events endpoint. Enabling this setting may help reduce 429s – or throttling errors – from Amplitude. More information about Amplitude's throttling is available in \[their docs]\(https://developers.amplitude.com/docs/batch-event-upload-api#429s-in-depth). | No | BOOLEAN | | User Agent | The user agent of the device sending the event. | No | STRING | | User Agent Parsing | Enabling this setting will set the Device manufacturer, Device Model and OS Name properties based on the user agent string provided in the userAgent field. | No | BOOLEAN | | Include Raw User Agent | Enabling this setting will send user\_agent based on the raw user agent string provided in the userAgent field | No | BOOLEAN | | Minimum ID Length | Amplitude has a default minimum id length of 5 characters for user\_id and device\_id fields. This field allows the minimum to be overridden to allow shorter id lengths. | No | INTEGER | | User Agent Data | The user agent data of device sending the event | No | OBJECT | ## Migration from Amplitude Classic Keep the following in mind if you plan to move to Amplitude (Actions) from a classic Amplitude destination. > \[!NOTE] > > In some cases, Amplitude Classic uses different default mappings than Amplitude (Actions). For example, the `Viewed Home Page` event in Amplitude Classic will be `Viewed Home` in Amplitude Actions, unless you configure it as `Viewed Home Page`. Be sure to follow the steps in the Destination Actions documentation to [customize your mappings](/docs/segment/connections/destinations/actions/#customize-mappings). Review how events appear in each destination, and configure the Actions' mappings properly to maintain continuity between Classic and Actions destinations. ### Amplitude (Actions) uses Amplitude's HTTP API v2 > \[!WARNING] > > 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. > \[!NOTE] > > Contact Segment support if you find features missing from the Amplitude (Actions) destination that were available in the 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](https://www.docs.developers.amplitude.com/analytics/apis/identify-api/#user_properties-supported-operations). 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 mappings #### CONNECTION SETTINGS * **API Key** (CLOUD, DEVICE-WEB, DEVICE-MOBILE): * Global Setting * **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. #### OTHER SETTINGS * **Batch Events** (DEVICE-WEB): * \*\*Use Batch Endpoint\*\* field on the \*\*Log Event\*\* action * **Prefer Anonymous Device ID** (CLOUD, DEVICE-WEB, DEVICE-MOBILE): * Actions field \*\*Device ID\*\*. * Replace the contents of the field with your preferred value. * **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 Referrer to Amplitude** (DEVICE-WEB): * Update the User Properties mapping to send \`context.page.referrer\`. * **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 UTM Properties to Amplitude** (CLOUD, DEVICE-WEB): * Supported by default. See the UTM Properties section to view the mappings. * **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. ## 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. ```js "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](https://github.com/segmentio/action-destinations/blob/12255568e4a6d35cf05ee79a118ee6c1a6823f31/packages/browser-destinations/destinations/amplitude-plugins/src/sessionId/index.ts#L33). ### 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: ```js localStorage.getItem('analytics_session_id'); ``` This call accesses the session ID stored in the browser's local storage. You can review the [retrieval code](https://github.com/segmentio/action-destinations/blob/12255568e4a6d35cf05ee79a118ee6c1a6823f31/packages/browser-destinations/destinations/amplitude-plugins/src/sessionId/index.ts#L64). ### 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: ```js 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](https://developer.chrome.com/docs/devtools/network) 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. ### Why does Segment fail to send some events to Amplitude (Actions) when I use the integrations object? You might encounter missing events when you have the integrations object in your event payload set to `All: false`. In some setups (for example, when using Segment's older [Consent Manager plugin](https://github.com/segmentio/consent-manager)), the Amplitude (Actions) integration name is auto-populated as a `session_id`, instead of `true`. Amplitude considers a `session_id` to mean `false` and discards the event. Segment recommends using [Consent Management](/docs/segment/privacy/consent-management) to manage end user consent instead of the integrations object. This prevents `All: false` from being added to your integrations object, which resolves the filtering issue. If you are unable to use Consent Management, [contact Segment support](https://segment.com/help/contact/). They can apply a workaround on your source to ensure events are still delivered to Amplitude.