--- title: Amplitude slug: amplitude createdAt: 2025-06-02T18:45:36.968Z --- # Introduction Chord CDP supports two Amplitude destination modes that share the same default event routing and custom action mappings. Most importantly, the Device Mode destination ensures that the session is passed along to the cloud mode destination. The device mode destination need to be enabled for accurate session tracking in the Cloud Mode, even if only the cloud mode is used to send events. With the device mode destination, the CDP event will contain `context.clientIds.amplitudeSessionId` with the current users session ID. # Requirements | Feature | Requires | | ----------------------- | ------------------------------------------------ | | Basic event tracking | API Key | | User identification | API Key | | Group analytics | API Key + Secret Key + Amplitude Accounts add-on | | User aliasing (mapUser) | API Key + Secret Key | # Destination modes | Mode | ID | Description | | --------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Cloud Mode** | amplitude-cloud | Server-side integration using Amplitude HTTP API v2. Events are sent from Chord's servers directly to Amplitude. | | **Device Mode** | amplitude-pixel | Client-side integration that loads the Amplitude SDK in the browser. Enables session tracking and real-time event capture. | ## Connecting to an Amplitude CDP destination 1. Log into the Chord data platform. 2. Navigate to the CDP. 3. Click the **"Add"** button next to Destinations. 4. Select **Amplitude (Cloud Mode) **or** Amplitude (Device Mode) **from the destination catalog. 5. For the **Amplitude (Cloud Mode)** destination, enter in the destination name and the **Project API Key. **You can also include the Project Secret Key, Region, and Custom Action Mappings. 6. For the **Amplitude (Device Mode)** destination, enter in the destination name and the **Amplitude API key.** You can also toggle track configurations. 7. Click **"Create" **to connect. :::hint{type="warning"} Please reach out to ***help\@chord.co ***if you are looking to utilize Amplitude's advanced features like ***[Autocapture](https://amplitude.com/docs/data/autocapture)*** & ***[Visual Labeling](https://amplitude.com/docs/data/visual-labeling), ***as the implementation will vary. ::: ## Configuration ### Cloud mode settings | Field | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | **Project API Key** | Yes | Your Amplitude Project API Key. Found in Amplitude under Data > Sources & Destinations. | | **Project Secret Key** | No | Required only for group identify and user mapping operations. Found in Data > Sources & Destinations. | | **Region** | No | north\_america (default) or europe. Select Europe if your Amplitude project is in the EU data center. | ### Device mode settings | Field | Default | Description | | --------------------------------- | ------- | ----------------------------------------------------------------------------- | | **API Key** | — | Your Amplitude project's API Key | | **Track All Pages** | false | Send a "Loaded a Page" event for every page() call | | **Track Named Pages** | true | Send "Viewed \[Name] Page" when page name is provided | | **Track Categorized Pages** | true | Send "Viewed \[Category] Page" when category is provided | | **Track UTM Properties** | true | Automatically capture UTM parameters from the URL | | **Track Referrer** | false | Include referrer information in events | | **Use Anonymous ID as Device ID** | false | Use Chord's anonymousId as Amplitude's device\_id for cross-platform tracking | | **Session Timeout** | 30 | Minutes of inactivity before starting a new session | ## Default event routing Both Cloud and Device modes use the same default routing: | Source Event | Amplitude Action | Notes | | --------------- | ----------------- | ----------------------------------------------- | | track | logEventV2 | All track events except Order Completed | | Order Completed | logPurchase | Includes revenue tracking | | identify | identifyUser | Updates user properties | | page / screen | logEventV2 | Sent as "Viewed \[name]" | | group | groupIdentifyUser | Requires Amplitude Accounts add-on & Secret Key | | alias | mapUser | Merges user identities. Requires Secret Key | ## Default field mappings The following tables show how Chord CDP event fields are automatically mapped to Amplitude fields. ### User & device identification | Source Field | Amplitude Field | Notes | | ----------------- | --------------- | ------------------------------ | | userId | user\_id | Primary user identifier | | context.device.id | device\_id | Falls back to anonymousId | | anonymousId | device\_id | Used when device.id is not set | | messageId | insert\_id | Deduplication key | ### Device & platform | Source Field | Amplitude Field | Fallback | | --------------------------- | -------------------- | ----------------------------------------------- | | context.device.type | platform | user.deviceType, or "Web" for analytics.js | | context.os.name | os\_name | user.deviceOs, parsed from User-Agent | | context.os.version | os\_version | user.deviceOsVersion, parsed from User-Agent | | context.device.brand | device\_brand | — | | context.device.manufacturer | device\_manufacturer | user.deviceManufacturer, parsed from User-Agent | | context.device.model | device\_model | user.deviceModel, parsed from User-Agent | | context.network.carrier | carrier | user.deviceCarrier | | context.userAgent | user\_agent | — | | context.app.version | app\_version | — | ### Location & locale | Source Field | Amplitude Field | Fallback | | -------------------------- | --------------- | -------------------- | | context.location.country | country | user.address.country | | context.location.region | region | user.address.state | | context.location.city | city | user.address.city | | context.location.dma | dma | — | | context.location.latitude | location\_lat | user.deviceLatitude | | context.location.longitude | location\_lng | user.deviceLongitude | | context.locale | language | user.locale | | context.ip | ip | user.ip | ### Event data | Source Field | Amplitude Field | Notes | | ------------------------------------ | ----------------- | --------------------------------- | | event | event\_type | For page/screen: "Viewed \[name]" | | timestamp | time | Converted to milliseconds | | properties | event\_properties | All event properties | | context.clientIds.amplitudeSessionId | session\_id | For session tracking | | context.library.name | library | Defaults to "chordcdp" | | context.groups | groups | For group analytics | ### Mobile advertising IDs | Source Field | Amplitude Field | Notes | | ---------------------------- | --------------- | ---------------------- | | context.device.advertisingId | idfa | iOS Advertising ID | | context.device.idfa | idfa | Alternative source | | context.device.advertisingId | adid | Android Advertising ID | | context.device.adid | adid | Alternative source | | context.device.id | idfv | iOS Vendor ID | ### Revenue fields (logPurchase action) | Source Field | Amplitude Field | Notes | | ------------------------ | ----------------- | --------------------------------------------- | | properties.revenue | revenue | Total revenue amount | | properties.price | price | Unit price | | properties.quantity | quantity | Number of items | | properties.productId | productId | Product identifier | | properties.revenueType | revenueType | e.g., "purchase", "refund" | | properties.products\[\*] | Individual events | Creates "Product Purchased" event per product | ### UTM & campaign tracking Campaign parameters are mapped to user properties with both current and initial values: | Source Field | $set Property | $setOnce Property | | ------------------------ | ------------- | ---------------------- | | context.campaign.source | utm\_source | initial\_utm\_source | | context.campaign.medium | utm\_medium | initial\_utm\_medium | | context.campaign.name | utm\_campaign | initial\_utm\_campaign | | context.campaign.term | utm\_term | initial\_utm\_term | | context.campaign.content | utm\_content | initial\_utm\_content | | context.page.referrer | referrer | initial\_referrer | User traits from identify calls are also set via user\_properties.$set. ## Amplitude actions reference | Action | Description | | ----------------- | -------------------------------------------------------------------- | | logEventV2 | Track a standard event with properties | | identifyUser | Update user properties without tracking an event | | logPurchase | Track a revenue event (includes revenue, price, quantity, productId) | | mapUser | Merge two user identities (alias). Requires Secret Key | | groupIdentifyUser | Update group properties. Requires Secret Key | | logEvent | Legacy event tracking (use logEventV2 instead) | ## Custom action mappings Override the default routing or add field transformations using **Custom Action Mappings**. ### Use cases - **Route specific events** — Send Subscription Started to logPurchase instead of logEventV2 - **Rename events** — Transform Button Clicked → CTA Interaction - **Map custom fields** — Map any property to Amplitude fields using dot notation - **Filter events** — Use $drop as target event name to exclude events ### Mapping fields | Field | Description | | --------------------- | ---------------------------------------------------------------------------------------------- | | **Source Event(s)** | Event(s) to match. Comma-separated for multiple (e.g., Purchase,Subscription). Use \* for all. | | **Amplitude Action** | Which Amplitude API to call | | **Target Event Name** | Override the event name. Leave empty for original. Use $drop to filter out. | | **Field Mappings** | Map source properties to Amplitude fields | ### Property path examples :::BlockQuote properties.product\_id → Access a top-level property properties.products\[0].sku → Access first item in an array properties.products\[\*].sku → Access ALL items in an array (wildcard) context.campaign.source → Access nested context fields traits.email → Access user traits (for identify events) ::: ### Target property examples :::BlockQuote event\_properties.item\_id → Set an event property user\_properties.$set.plan → Set a user property revenue → Set the revenue field productId → Set the product ID ::: ### Match priority 1. **Exact match** — Event name matches exactly (e.g., Order Completed) 2. **Type match** — Event type matches (e.g., track matches all track events) 3. **Wildcard** — \* matches all events (lowest priority) ## Examples ### Route subscription events to revenue tracking :::BlockQuote Source Event: Subscription Started, Subscription Renewed Action: logPurchase ::: ### Rename an event :::BlockQuote Source Event: Button Clicked Action: logEventV2 Target Event: CTA Interaction ::: ### Map custom fields for purchase events :::BlockQuote Source Event: Order Completed Action: logPurchase Field Mappings: \- properties.order\_id → event\_properties.order\_id \- properties.items\[\*].sku → event\_properties.product\_ids \- properties.total → revenue ::: ### Drop unwanted events :::BlockQuote Source Event: Internal Debug Event Action: logEventV2 Target Event: $drop ::: :::hint{type="danger"} Before connecting destinations in the Chord CDP, please verify with all Destination owners that all **non-Chord CDP** configured destinations are *disabled.* ** Running external destinations alongside configured Chord CDP destinations ***can result in duplicate events downstream. *** :::