Skip to main content
Ask your AI

Amplitude

Server Source code Package

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.

Where this fits

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
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,
        },
      },
    },
  },
});

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​

PropertyTypeDescriptionMore
apiKey*stringYour 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.
flushIntervalMillisintegerHow 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.
flushQueueSizeintegerEvents 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.
flushMaxRetriesintegerAttempts 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.
useBatchbooleanUse the Amplitude batch endpoint for higher rate limits. Recommended for high-volume server flows. Default: false.
minIdLengthintegerMinimum length for user_id and device_id fields.
serverUrlstringCustom server URL for proxies or self-hosted endpoints.
optOutbooleanInitial opt-out state. When true, no events are sent, and each event the destination receives fails with a transport error. Default: false.
enableRequestBodyCompressionbooleanEnable gzip compression for request payloads. Default: false.
identifyanywalkerOS mapping value resolving to per-event identity. Keys: user_id, device_id, session_id, set, setOnce, add, append, prepend, preInsert, postInsert, remove, unset, clearAll.
eventOptionsanywalkerOS 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.
includeArray<string>walkerOS event sections to include as event_properties (like ['data', 'globals']).
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
identifyanyPer-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.
revenueanyRevenue 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.
groupanyGroup assignment. Resolves to { type, name } -> amplitude.setGroup(type, name, eventOptions).
groupIdentifyanyGroup properties. Resolves to { type, name, set?, setOnce?, ... } -> amplitude.groupIdentify(type, name, identify, eventOptions).
eventOptionsanyPer-rule EventOptions override. Resolves to { time?, insert_id?, ip?, ... }. Overrides destination-level eventOptions for this rule.
includeArray<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).

Event
{
  "analytics": true
}
Out
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).

Event
{
  "analytics": false
}
Out
amplitude.setOptOut(false);

amplitude.setOptOut(true)

Default event

A walkerOS event forwarded as an Amplitude track call with the event name and empty properties.

Event
{
  "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"
  }
}
Out
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.

Event
{
  "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"
  }
}
Out
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.

Event
{
  "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"
  }
}
Out
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.

Event
{
  "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"
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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"
          }
        }
      }
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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"
            }
          }
        }
      ]
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "revenue": {
      "map": {
        "productId": "data.plan_id",
        "price": "data.amount",
        "revenueType": {
          "value": "renewal"
        },
        "currency": {
          "key": "data.currency",
          "value": "EUR"
        }
      }
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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
            }
          }
        }
      }
    }
  }
}
Out
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.

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.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)