Amplitude
Server-side event delivery to Amplitude for product analytics, using the official @amplitude/analytics-node SDK. Supports track, identify, revenue, setGroup, groupIdentify, and flush calls with per-event identity via EventOptions.
Amplitude is a server destination in the walkerOS flow:
Sends events server-side to Amplitude's HTTP API, providing reliable delivery with identity resolution, revenue tracking, and group analytics without browser-side SDK overhead.
Installation
npm install @walkeros/collector @walkeros/server-destination-amplitude- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationAmplitude from '@walkeros/server-destination-amplitude';
await startFlow({
destinations: {
amplitude: {
code: destinationAmplitude,
config: {
settings: {
apiKey: process.env.AMPLITUDE_API_KEY,
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"amplitude": {
"package": "@walkeros/server-destination-amplitude",
"config": {
"settings": {
"apiKey": "$secret.AMPLITUDE_API_KEY"
}
}
}
}
}
}
}Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
apiKey | string | Your Amplitude project API key. Find it in your Amplitude project settings under "General" -> "API Keys". | |
serverZone | 'US' | 'EU' | Amplitude data residency zone. Use EU for European data residency. Default: US. | |
flushIntervalMillis | integer | How long (in ms) the SDK waits before it sends queued events, and before its first retry of a failed request. Default: a tenth of config.timeout (1000 at the 10 s default). A value set here wins. | |
flushQueueSize | integer | Events the SDK sends in one request. Each push and each config.batch batch flushes the SDK and waits until Amplitude answered its calls. Default: 200. | |
flushMaxRetries | integer | Attempts per event, the first send included. Default: as many as end within config.timeout with the SDK's waits, each request bounded by a quarter of it (3 at the 10 s default). A value set here wins. | |
useBatch | boolean | Use the Amplitude batch endpoint for higher rate limits. Recommended for high-volume server flows. Default: false. | |
minIdLength | integer | Minimum length for user_id and device_id fields. | |
serverUrl | string | Custom server URL for proxies or self-hosted endpoints. | |
optOut | boolean | Initial opt-out state. When true, no events are sent, and each event the destination receives fails with a transport error. Default: false. | |
enableRequestBodyCompression | boolean | Enable gzip compression for request payloads. Default: false. | |
identify | any | walkerOS mapping value resolving to per-event identity. Keys: user_id, device_id, session_id, set, setOnce, add, append, prepend, preInsert, postInsert, remove, unset, clearAll. | |
eventOptions | any | walkerOS mapping value resolving to per-event EventOptions. Keys: time, insert_id, ip, city, country, region, language, platform, os_name, os_version, device_brand, device_model, app_version, user_agent. | |
include | Array<string> | walkerOS event sections to include as event_properties (like ['data', 'globals']). |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
identify | any | Per-event identity mapping. Resolves to an object with any of: user_id, device_id, session_id, set, setOnce, add, append, prepend, preInsert, postInsert, remove, unset, clearAll. | |
revenue | any | Revenue mapping. Resolves to a single object or (via loop) an array, each with: productId, price, quantity, revenueType, currency, revenue, receipt, receiptSig, eventProperties. One amplitude.revenue() call fires per item. | |
group | any | Group assignment. Resolves to { type, name } -> amplitude.setGroup(type, name, eventOptions). | |
groupIdentify | any | Group properties. Resolves to { type, name, set?, setOnce?, ... } -> amplitude.groupIdentify(type, name, identify, eventOptions). | |
eventOptions | any | Per-rule EventOptions override. Resolves to { time?, insert_id?, ip?, ... }. Overrides destination-level eventOptions for this rule. | |
include | Array<string> | Per-rule include override. Replaces destination-level include for this rule. |
Examples
Consent granted
With consent: { analytics: true } in the destination config, a walker consent command that grants analytics opts into Amplitude tracking via setOptOut(false).
{
"analytics": true
}amplitude.setOptOut(false)Consent revoked
With consent: { analytics: true } in the destination config, revoking analytics consent after a grant opts out of Amplitude tracking via setOptOut(true).
{
"analytics": false
}amplitude.setOptOut(false);
amplitude.setOptOut(true)Default event
A walkerOS event forwarded as an Amplitude track call with the event name and empty properties.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "ev1700000100",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000100000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}amplitude.track("product view", {}, {
"insert_id": "ev1700000100"
})Identify per event
With settings.identify mapping user_id, device_id, and session_id to 'user.id', 'user.device', and 'user.session', every call carries them in its Amplitude EventOptions. A non-numeric session string is hashed to a stable number.
{
"name": "page view",
"data": {
"domain": "www.example.com",
"title": "walkerOS documentation",
"referrer": "https://www.walkeros.io/",
"search": "?foo=bar",
"hash": "#hash",
"id": "/docs/"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000104",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000104000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}amplitude.track("page view", {}, {
"insert_id": "ev1700000104",
"user_id": "us3r",
"device_id": "c00k13",
"session_id": 394324160
})Include data section
With include: ['data'] in the destination config, the event data section is flattened into prefixed event_properties on every track call.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "ev1700000102",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000102000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}amplitude.track("product view", {
"data_id": "ers",
"data_name": "Everyday Ruck Snack",
"data_color": "black",
"data_size": "l",
"data_price": 420,
"data_currency": "EUR"
}, {
"insert_id": "ev1700000102"
})Event options
With settings.eventOptions mapping time to 'timestamp' and insert_id to 'id', each call carries the event time and that insert_id in its Amplitude EventOptions.
{
"name": "page view",
"data": {
"domain": "www.example.com",
"title": "walkerOS documentation",
"referrer": "https://www.walkeros.io/",
"search": "?foo=bar",
"hash": "#hash",
"id": "/docs/"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "1700000110abcdef",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000110000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}amplitude.track("page view", {}, {
"time": 1700000110000,
"insert_id": "1700000110abcdef"
})Group assignment
A company update assigns the user to a group and sets group properties via setGroup plus groupIdentify.
{
"name": "company update",
"data": {
"company": "Acme",
"industry": "tech",
"employee_count": 50,
"founded_year": 2020
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000109",
"trigger": "test",
"entity": "company",
"action": "update",
"timestamp": 1700000109000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"group": {
"map": {
"type": {
"value": "company"
},
"name": "data.company"
}
},
"groupIdentify": {
"map": {
"type": {
"value": "company"
},
"name": "data.company",
"set": {
"map": {
"industry": "data.industry",
"size": "data.employee_count"
}
},
"setOnce": {
"map": {
"founded": "data.founded_year"
}
}
}
}
}
}amplitude.setGroup("company", "Acme", {
"insert_id": "ev1700000109-group"
});
amplitude.groupIdentify("company", "Acme", {
"set": {
"industry": "tech",
"size": 50
},
"setOnce": {
"founded": 2020
}
}, {
"insert_id": "ev1700000109-groupIdentify"
})Multi-product order
An order with multiple nested products fires one amplitude.revenue per product plus a single track for the order.
{
"name": "order complete",
"data": {
"id": "0rd3r1d",
"currency": "EUR",
"value": 462,
"tax": 73.76,
"shipping": 5.22,
"total": 467.22
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "product",
"data": {
"id": "cc",
"name": "Cool Cap",
"size": "one size",
"price": 42
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "gift",
"data": {
"name": "Surprise"
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
}
],
"consent": {
"functional": true
},
"id": "ev1700000108",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000108000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"include": [
"data",
"globals"
],
"settings": {
"revenue": {
"loop": [
"nested",
{
"condition": {
"$code": "e=>{const t=e;return\"number\"==typeof t?.data?.price}"
},
"map": {
"productId": "data.id",
"price": "data.price",
"quantity": {
"key": "data.quantity",
"value": 1
},
"revenueType": {
"value": "purchase"
},
"currency": {
"key": "data.currency",
"value": "EUR"
}
}
}
]
}
}
}amplitude.revenue({
"productId": "ers",
"price": 420,
"quantity": 1,
"revenueType": "purchase",
"currency": "EUR"
}, {
"insert_id": "ev1700000108-revenue-0"
});
amplitude.revenue({
"productId": "cc",
"price": 42,
"quantity": 1,
"revenueType": "purchase",
"currency": "EUR"
}, {
"insert_id": "ev1700000108-revenue-1"
});
amplitude.track("order complete", {
"data_id": "0rd3r1d",
"data_currency": "EUR",
"data_value": 462,
"data_tax": 73.76,
"data_shipping": 5.22,
"data_total": 467.22,
"globals_pagegroup": "shop"
}, {
"insert_id": "ev1700000108"
})Subscription revenue
A subscription renewal fires a single amplitude.revenue call with productId, price, and a currency fallback.
{
"name": "subscription renew",
"data": {
"plan_id": "plan-pro",
"amount": 9.99
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000107",
"trigger": "test",
"entity": "subscription",
"action": "renew",
"timestamp": 1700000107000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"revenue": {
"map": {
"productId": "data.plan_id",
"price": "data.amount",
"revenueType": {
"value": "renewal"
},
"currency": {
"key": "data.currency",
"value": "EUR"
}
}
}
}
}amplitude.revenue({
"productId": "plan-pro",
"price": 9.99,
"revenueType": "renewal",
"currency": "EUR"
}, {
"insert_id": "ev1700000107-revenue-0"
})User login identify
A user login maps to amplitude.identify with set, setOnce, and add operations while the default track call is skipped.
{
"name": "user login",
"data": {
"user_id": "new-user-123",
"plan": "premium",
"company": "Acme",
"email": "user@acme.com"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000105",
"trigger": "test",
"entity": "user",
"action": "login",
"timestamp": 1700000105000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"identify": {
"map": {
"user_id": "data.user_id",
"set": {
"map": {
"plan": "data.plan",
"company": "data.company",
"email": "data.email"
}
},
"setOnce": {
"map": {
"first_login": "timestamp"
}
},
"add": {
"map": {
"login_count": {
"value": 1
}
}
}
}
}
}
}amplitude.identify({
"set": {
"plan": "premium",
"company": "Acme",
"email": "user@acme.com"
},
"setOnce": {
"first_login": 1700000105000
},
"add": {
"login_count": 1
}
}, {
"insert_id": "ev1700000105-identify",
"user_id": "new-user-123"
})Identity
Without settings.identify the destination sends no user_id or device_id, so the quickstart's events carry neither. Amplitude's HTTP V2 API requires one of them on every event, and a 400 answer fails the push with transport and status 400. Map them from the event in settings.identify, as the Identify per event example above does, or per rule.
Batching and delivery
This destination batches by default: config.batch sends a batch at 200 events, 10 seconds after the last event, or 30 seconds after the first, whichever comes first, and each event keeps its own outcome. Set config.batch: { size: 1 } to send each event at once. How batching, retries, deduplication and acknowledgement work for the server SDK destinations is described in Server SDK destinations.
A request that Amplitude refuses fails the event with its status, for example 400. A 5xx answer or no answer at all fails it with status 500 once the retries within config.timeout are used up.
A group name list that holds a non-string is skipped with a DEBUG line, not sent.
Consent
The quickstart sets no config.consent, so Amplitude receives every event and a walker consent command changes nothing. Add consent: { analytics: true } to config, next to settings, to send only with analytics consent (consent management): a revocation then calls setOptOut(true) and a grant setOptOut(false). Events still waiting in the batch at a revocation are not sent: each fails with a transport error and goes to the dead-letter queue. settings.optOut: true does the same to every event.