Amplitude

26 min

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

Log into the Chord data platform.

Navigate to the CDP.

Click the "Add" button next to Destinations.

Select Amplitude (Cloud Mode) or Amplitude (Device Mode) from the destination catalog.

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.

For the Amplitude (Device Mode) destination, enter in the destination name and the Amplitude API key. You can also toggle track configurations.

Click "Create" to connect.

Please reach out to [email protected] if you are looking to utilize Amplitude's advanced features like Autocapture & 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

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

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

Exact match — Event name matches exactly (e.g., Order Completed)

Type match — Event type matches (e.g., track matches all track events)

Wildcard — * matches all events (lowest priority)

Examples

Route subscription events to revenue tracking

Source Event: Subscription Started, Subscription Renewed Action: logPurchase

Rename an event

Source Event: Button Clicked Action: logEventV2 Target Event: CTA Interaction

Map custom fields for purchase events

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

Source Event: Internal Debug Event Action: logEventV2 Target Event: $drop

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.