RudderStack
Server-side event delivery to RudderStack via the official @rudderstack/rudder-sdk-node SDK. Sends the Segment Spec calls track, identify, group, page, screen, and alias, skips an identify or group call that repeats the previous one, and flushes on shutdown with flush().
RudderStack is a server destination in the walkerOS flow:
Receives events server-side from the collector, resolves identity, and forwards them to RudderStack's data plane for routing to downstream destinations.
Installation
npm install @walkeros/collector @walkeros/server-destination-rudderstack- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationRudderstack from '@walkeros/server-destination-rudderstack';
await startFlow({
destinations: {
rudderstack: {
code: destinationRudderstack,
config: {
settings: {
writeKey: process.env.RUDDERSTACK_WRITE_KEY,
dataPlaneUrl: 'https://hosted.rudderlabs.com',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"rudderstack": {
"package": "@walkeros/server-destination-rudderstack",
"config": {
"settings": {
"writeKey": "$secret.RUDDERSTACK_WRITE_KEY",
"dataPlaneUrl": "https://hosted.rudderlabs.com"
}
}
}
}
}
}
}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 |
|---|---|---|---|
writeKey | string | RudderStack source write key. Find it in the RudderStack dashboard under Sources > Setup. | |
dataPlaneUrl | string | RudderStack data plane URL. Required. Example: https://your-data-plane.rudderstack.com | |
userId | string | walkerOS mapping value path to resolve userId from each event (like user.id). | |
anonymousId | string | walkerOS mapping value path to resolve anonymousId from each event (like user.session). | |
path | string | API path route (like /v1/batch). | |
flushAt | integer | Events the SDK sends in one request. Each push and each config.batch batch flushes the SDK and waits until its calls are sent. Default: 20. | |
flushInterval | integer | Max milliseconds before auto-flush. Default: 10000. | |
maxQueueSize | integer | Maximum batch payload size in bytes. Default: 460800 (450 KB). | |
maxInternalQueueSize | integer | Maximum in-memory queue length. Default: 20000. | |
logLevel | string | SDK log level: 'info', 'debug', 'error', or 'silly'. Default: 'info'. | |
retryCount | integer | Retries the SDK makes for a failed request, a tenth of config.timeout apart. Default: 2, which ends within config.timeout. A value set here wins. | |
timeout | integer | Time one request may take, in milliseconds. Default: a quarter of config.timeout (2500 at the 10 s default). A value set here wins. | |
enable | boolean | Set to false to no-op all SDK calls. Default: true. | |
gzip | boolean | Enable gzip compression for requests. Default: true. | |
identify | any | Destination-level identity mapping. Resolves to { userId?, traits? }. identify() fires when the userId or traits differ from the previous identify call this destination sent; the anonymousId is not compared. | |
group | any | Destination-level group mapping. Resolves to { groupId, traits? }. group() fires when the groupId or traits differ from the previous group call this destination sent; the user is not compared. | |
integrations | Record<string, any> | Has no effect: the destination does not add integrations to its calls. |
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 { userId?, traits? }. Use with rule-level silent: true on login/identify events. | |
group | any | Per-event group assignment. Resolves to { groupId, traits? }. Use with rule-level silent: true on company/team events. | |
page | any | Per-event page call. Resolves to { name?, properties? }, or true for a page() call without a name. Use with silent: true. | |
screen | any | Per-event screen call (mobile backends). Resolves to { name?, properties? }, or true for a screen() call without a name. Use with silent: true. | |
alias | any | Per-event alias call. Resolves to { previousId }. Links that anonymous id to the event userId, which the call needs: an event without a userId fails. Use with rule-level silent: true. |
Examples
Alias user
An identity merge fires analytics.alias to link a previous anonymous id to the newly registered user id.
{
"name": "identity merge",
"data": {
"anonymous_id": "anonymous-123"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "registered-456",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000107",
"trigger": "test",
"entity": "identity",
"action": "merge",
"timestamp": 1700000107000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"alias": {
"map": {
"previousId": "data.anonymous_id"
}
}
}
}analytics.alias({
"messageId": "ev1700000107-alias",
"userId": "registered-456",
"previousId": "anonymous-123",
"timestamp": {}
})Anonymous only
When no userId is resolved RudderStack accepts the track call keyed solely by anonymousId.
{
"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": {
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "ev1700000108",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000108000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}analytics.track({
"messageId": "ev1700000108",
"anonymousId": "s3ss10n",
"event": "product view",
"properties": {},
"timestamp": {}
})Group company
A company update fires analytics.group with the groupId and group traits for B2B account tracking.
{
"name": "company update",
"data": {
"company_id": "comp-456",
"company_name": "Acme",
"industry": "tech",
"employees": 50
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000104",
"trigger": "test",
"entity": "company",
"action": "update",
"timestamp": 1700000104000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"group": {
"map": {
"groupId": "data.company_id",
"traits": {
"map": {
"name": "data.company_name",
"industry": "data.industry",
"employees": "data.employees"
}
}
}
}
}
}analytics.group({
"messageId": "ev1700000104-group",
"userId": "us3r",
"anonymousId": "s3ss10n",
"groupId": "comp-456",
"traits": {
"name": "Acme",
"industry": "tech",
"employees": 50
},
"timestamp": {}
})Default track
A walker event becomes a RudderStack analytics.track call with userId and anonymousId resolved from the 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",
"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"
}
}analytics.track({
"messageId": "ev1700000100",
"userId": "us3r",
"anonymousId": "s3ss10n",
"event": "product view",
"properties": {},
"timestamp": {}
})Destination identify
With settings.identify mapping the email trait to 'user.email', the first push fires analytics.identify with the traits before the track call. Later pushes repeat it only when the userId or traits differ.
{
"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",
"session": "s3ss10n",
"email": "user@example.com"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000102",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000102000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}analytics.identify({
"messageId": "ev1700000102-identify",
"userId": "us3r",
"anonymousId": "s3ss10n",
"traits": {
"email": "user@example.com"
},
"timestamp": {}
});
analytics.track({
"messageId": "ev1700000102",
"userId": "us3r",
"anonymousId": "s3ss10n",
"event": "page view",
"properties": {},
"timestamp": {}
})Renamed event
A mapping renames the event so the RudderStack track call uses a canonical name such as Order Completed.
{
"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",
"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": "ev1700000101",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000101000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "Order Completed"
}analytics.track({
"messageId": "ev1700000101",
"userId": "us3r",
"anonymousId": "s3ss10n",
"event": "Order Completed",
"properties": {},
"timestamp": {}
})Page view
A page view fires analytics.page with a resolved page name and properties instead of a generic track.
{
"name": "page view",
"data": {
"title": "Getting Started",
"section": "tutorials"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000105",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000105000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"page": {
"map": {
"name": "data.title",
"properties": {
"map": {
"section": "data.section"
}
}
}
}
}
}analytics.page({
"messageId": "ev1700000105-page",
"userId": "us3r",
"anonymousId": "s3ss10n",
"name": "Getting Started",
"properties": {
"section": "tutorials"
},
"timestamp": {}
})Screen view
A screen view from a mobile app backend fires analytics.screen with a screen name and properties.
{
"name": "screen view",
"data": {
"screen_name": "Welcome",
"section": "onboarding",
"build": "1.2.3"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000106",
"trigger": "test",
"entity": "screen",
"action": "view",
"timestamp": 1700000106000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"screen": {
"map": {
"name": "data.screen_name",
"properties": {
"map": {
"build": "data.build"
}
}
}
}
}
}analytics.screen({
"messageId": "ev1700000106-screen",
"userId": "us3r",
"anonymousId": "s3ss10n",
"name": "Welcome",
"properties": {
"build": "1.2.3"
},
"timestamp": {}
})User login identify
A user login fires only an analytics.identify call with the resolved userId and traits, skipping the track.
{
"name": "user login",
"data": {
"user_id": "new-user-123",
"email": "user@acme.com",
"name": "Jane Doe",
"plan": "premium"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "ev1700000103",
"trigger": "test",
"entity": "user",
"action": "login",
"timestamp": 1700000103000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"identify": {
"map": {
"userId": "data.user_id",
"traits": {
"map": {
"email": "data.email",
"name": "data.name",
"plan": "data.plan"
}
}
}
}
}
}analytics.identify({
"messageId": "ev1700000103-identify",
"userId": "new-user-123",
"anonymousId": "s3ss10n",
"traits": {
"email": "user@acme.com",
"name": "Jane Doe",
"plan": "premium"
},
"timestamp": {}
})When it fails
- no identity company: A company update event without userId or anonymousId cannot be sent to RudderStack: the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - no identity login: A user login event without userId or anonymousId cannot be sent to RudderStack: the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - no identity merge: A identity merge event without userId or anonymousId cannot be sent to RudderStack: the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - no identity order: A order complete event without userId or anonymousId cannot be sent to RudderStack: the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - no identity page: A page view event without userId or anonymousId cannot be sent to RudderStack: the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - no identity product: A product view event without userId or anonymousId cannot be sent to RudderStack: the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input. - no identity screen: A screen view event without userId or anonymousId cannot be sent to RudderStack: the push fails with missing-input instead of counting as delivered. Reported as
failedwith codemissing-input.
Identity
Identity is resolved from each event: userId defaults to user.id and anonymousId defaults to user.session. Override these paths in settings to match your event structure. An event where neither resolves is not sent and fails with missing-input.
An identify or group call is sent only when its userId (for a group, its groupId) or its traits differ from the previous call of that kind this destination sent. The anonymousId and, for a group, the user are not compared. When a second visitor without a userId has the same traits, or a second user joins the same group with the same traits, no identify or group call is sent for them and nothing reports it. Their track calls still go out.
Batching and delivery
This destination batches by default: config.batch sends a batch at 20 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.
Consent
The quickstart sets no config.consent, so RudderStack receives every event. Add config.consent to send only with consent (consent management).
Alias support
Unlike the Segment destination, this destination also sends alias() calls, to link an anonymous identity to the user id after signup or login. Map previousId in a rule's settings.alias, as the Alias user example above does. The event needs a userId as well: an alias call without one fails the event with transport.