Sources
Sources are the entry points for event data in walkerOS. They capture events from different environments and formats, then transform them into standardized events that the collector can process.
How sources work
Sources capture events in their native format and send them to the collector:
Server source contracts
Every server source normalizes its platform's request into one shared shape before mapping, and accepts one shared set of POST body forms. Two pages define them:
- Request scope: the eight fields
config.ingestresolves against, identical on every server source. - Event envelope: how many events a request body carries, the batch cap, and the response contract.
Web and queue sources have no inbound request to adapt, so neither applies to
them: browser and dataLayer sources push directly, and config.ingest is inert
there.
Available sources
Web
Browser
Captures events from web pages using DOM attributes:
- DOM interactions (clicks, form submissions, visibility)
- Automatic pageview tracking
- Custom data attributes (
data-elb-*)
dataLayer
Integrates with existing analytics implementations:
- Works with GA4 and GTM dataLayer
- Event transformation and filtering
- Gradual migration support
Session
Session lifecycle detection, emitting session start and session end:
- Storage-backed session identity across page loads
- Configurable timeout and lifetime
- Feeds session context to every downstream event
Consent management
Consent state from a CMP, forwarded to the collector:
- Cookiebot, CookieFirst, Usercentrics and CookiePro adapters
- Consent changes propagate to destinations at runtime
- Destinations that require consent hold their events until it is granted
Server
Server sources accept HTTP requests containing walkerOS events and forward them to the collector.
Express
HTTP event collection server built on Express.js:
- Starts its own server or integrates with an existing Express app
- CORS support and configurable routes
- Pixel tracking with 1x1 transparent GIF
Fetch
Web Standard Fetch API source for edge and serverless platforms:
- Runs on Cloudflare Workers, Vercel Edge, Deno, Bun and Node.js 18+
- Web Standard
(Request) => Responsesignature - Batch processing and CORS support
AWS Lambda
AWS Lambda HTTP handler for event collection:
- Handles API Gateway REST (v1), HTTP API (v2) and Function URLs
- Auto-detection of API Gateway version
- Pixel tracking and health checks
GCP Cloud Functions
Google Cloud Functions HTTP handler for event collection:
- Assigned directly as the Cloud Functions handler
- Batches via the shared event envelope
- Configurable CORS
AWS SQS
Queue consumer for events delivered through Amazon SQS:
- Decouples ingestion from processing
- Batch record handling
- Retries and dead-letter handling stay with the queue
Google Pub/Sub
Pull subscriber and push webhook for Google Pub/Sub:
- Pull for long-running workers, push for HTTP endpoints
- Configurable decoders for the message payload
- Redelivery governed by the subscription
Basic setup
Sources are configured in startFlow:
import { startFlow } from '@walkeros/collector';
import { sourceBrowser } from '@walkeros/web-source-browser';
const { collector, elb } = await startFlow({
sources: {
browser: {
code: sourceBrowser,
config: {
settings: {
pageview: true,
prefix: 'data-elb',
},
},
},
},
destinations: {
/* your destinations */
},
});
// elb is now browser.push (enhanced with DOM commands)
// Use elb for manual event tracking
await elb({ name: 'product view', data: { id: 'P123', name: 'Laptop' } });Primary source
startFlow returns an elb function based on your sources:
- With sources: Returns first source's
pushmethod (enhanced features) - Multiple sources: First source is primary by default
- No sources: Returns the collector's own
elb(events and walker commands, no DOM commands)
Override primary source
const { elb } = await startFlow({
sources: {
browser: { code: sourceBrowser },
dataLayer: { code: sourceDataLayer, primary: true }, // Override
},
});
// elb is now the dataLayer source's push (the collector's elb) instead of browser.pushReactive event handling
Sources can react to collector events via the optional on method:
const mySource: Source.Init = async (context) => {
return {
type: 'custom',
config: context.config,
push: context.env.elb,
on: async (event, data) => {
if (event === 'consent') {
// React to consent changes
}
},
};
};Available events:
consent- Consent state changesuser,globals,custom- State set by thewalkercommand of the same namesession- Session lifecycle eventsconfig- Collector config changesready- Collector ready staterun- Collector run events
Creating custom sources
See Create Your Own Source for a complete guide to building custom sources.
Configuration
These fields are available on every source, regardless of package. They wrap the
package-specific settings field, which is documented on each source's page.
| Property | Type | Description | More |
|---|---|---|---|
consent | WalkerOS.Consent | Required consent states to process any events | |
mapping | Mapping.Rules | Entity-action specific mapping rules | |
policy | Mapping.Policy | Pre-processing policy rules applied to the event before its data is mapped | |
credentials | Source.Credentials | Optional credentials (source-defined shape) | |
env | Source.BaseEnv | Environment dependencies (platform-specific) | |
id | string | Source identifier (defaults to source key) | |
primary | boolean | Mark as primary (only one can be primary) | |
require | Array<string> | Collector events (e.g., ["consent"]) that must fire before the source receives on() calls; init and event capture are not delayed | |
logger | Logger.Config | Logger configuration (level, handler) to override the collector defaults | |
async | boolean | object | Respond-first acknowledgement for response-producing server sources. When true the source responds 2xx ("accepted") before the event is delivered; when false it waits for delivery to settle and the response reflects the outcome. A record configures this per source-defined key: the express source keys it by HTTP method (GET/POST) and defaults to { GET: false, POST: true }. Browser/dataLayer sources have no HTTP response to defer and ignore it. A 2xx means accepted, not delivered. Defaults are per source type. | |
setup | boolean | object | Provisioning options for `walkeros setup`, which runs only when invoked (boolean enables defaults, object configures specifics) | |
ingest | any | any | Ingest metadata extraction mapping. On server sources it resolves against the normalized request scope (method, url, path, query, headers, body, ip, raw), without a prefix. | |
disabled | boolean | Completely skip this source (no init, no event capture) | |
state | State.Config | State.Config[] | Declarative store get/set operations applied around this source |
Events and commands take different routes
A source has two ways out, and the pipeline fields above apply to only one of them:
- Events go through the source pipeline. This is where
before,next,mapping,cacheandstaterun, where the event picks up its per-source ingest, and what makes the source show up incollector.status.sources. walker *commands (walker consent,walker user,walker run, …) go straight to the collector. They are control signals, so no mapping or chain applies to them.
This holds for every source, web and server. A next chain declared on the
browser or dataLayer source runs for the events it
captures, while a consent grant coming from a CMP source reaches the collector
untouched.
Next steps
- Browser source - DOM-based tracking
- DataLayer source - Legacy integration
- Create your own - Custom source guide