Skip to main content
Ask your AI

RudderStack

Server Source code Package Beta

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().

Where this fits

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

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
writeKey*stringRudderStack source write key. Find it in the RudderStack dashboard under Sources > Setup.
dataPlaneUrl*stringRudderStack data plane URL. Required. Example: https://your-data-plane.rudderstack.com
userIdstringwalkerOS mapping value path to resolve userId from each event (like user.id).
anonymousIdstringwalkerOS mapping value path to resolve anonymousId from each event (like user.session).
pathstringAPI path route (like /v1/batch).
flushAtintegerEvents 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.
flushIntervalintegerMax milliseconds before auto-flush. Default: 10000.
maxQueueSizeintegerMaximum batch payload size in bytes. Default: 460800 (450 KB).
maxInternalQueueSizeintegerMaximum in-memory queue length. Default: 20000.
logLevelstringSDK log level: 'info', 'debug', 'error', or 'silly'. Default: 'info'.
retryCountintegerRetries 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.
timeoutintegerTime one request may take, in milliseconds. Default: a quarter of config.timeout (2500 at the 10 s default). A value set here wins.
enablebooleanSet to false to no-op all SDK calls. Default: true.
gzipbooleanEnable gzip compression for requests. Default: true.
identifyanyDestination-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.
groupanyDestination-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.
integrationsRecord<string, any>Has no effect: the destination does not add integrations to its calls.
* 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 { userId?, traits? }. Use with rule-level silent: true on login/identify events.
groupanyPer-event group assignment. Resolves to { groupId, traits? }. Use with rule-level silent: true on company/team events.
pageanyPer-event page call. Resolves to { name?, properties? }, or true for a page() call without a name. Use with silent: true.
screenanyPer-event screen call (mobile backends). Resolves to { name?, properties? }, or true for a screen() call without a name. Use with silent: true.
aliasanyPer-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.

Event
{
  "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"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "alias": {
      "map": {
        "previousId": "data.anonymous_id"
      }
    }
  }
}
Out
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.

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

Event
{
  "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"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "group": {
      "map": {
        "groupId": "data.company_id",
        "traits": {
          "map": {
            "name": "data.company_name",
            "industry": "data.industry",
            "employees": "data.employees"
          }
        }
      }
    }
  }
}
Out
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.

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

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

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",
    "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"
  }
}
Mapping
{
  "name": "Order Completed"
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "page": {
      "map": {
        "name": "data.title",
        "properties": {
          "map": {
            "section": "data.section"
          }
        }
      }
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "screen": {
      "map": {
        "name": "data.screen_name",
        "properties": {
          "map": {
            "build": "data.build"
          }
        }
      }
    }
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "silent": true,
  "settings": {
    "identify": {
      "map": {
        "userId": "data.user_id",
        "traits": {
          "map": {
            "email": "data.email",
            "name": "data.name",
            "plan": "data.plan"
          }
        }
      }
    }
  }
}
Out
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 failed with code missing-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 failed with code missing-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 failed with code missing-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 failed with code missing-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 failed with code missing-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 failed with code missing-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 failed with code missing-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.

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.

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