> Part of the walkerOS documentation. Project overview and full index: # 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[​](#how-sources-work "Direct link to How sources work") Sources capture events in their native format and send them to the collector: ## Server source contracts[​](#server-source-contracts "Direct link to 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](https://www.walkeros.io/docs/sources/scope.md)**: the eight fields `config.ingest` resolves against, identical on every server source. * **[Event envelope](https://www.walkeros.io/docs/sources/envelope.md)**: 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[​](#available-sources "Direct link to Available sources") ### Web[​](#web "Direct link to Web") #### Browser[​](#browser "Direct link to Browser") Captures events from web pages using DOM attributes: * DOM interactions (clicks, form submissions, visibility) * Automatic session and pageview tracking * Custom data attributes (`data-elb-*`) [Learn more →](https://www.walkeros.io/docs/sources/web/browser.md) #### dataLayer[​](#datalayer "Direct link to dataLayer") Integrates with existing analytics implementations: * Works with GA4 and GTM dataLayer * Event transformation and filtering * Gradual migration support [Learn more →](https://www.walkeros.io/docs/sources/web/dataLayer.md) #### Session[​](#session "Direct link to 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 [Learn more →](https://www.walkeros.io/docs/sources/web/session.md) #### Consent management[​](#consent-management "Direct link to Consent management") Consent state from a CMP, forwarded to the collector: * CookieFirst, Usercentrics and CookiePro adapters * Consent changes propagate to destinations at runtime * Events queue until consent resolves [Learn more →](https://www.walkeros.io/docs/sources/web/cmps.md) ### Server[​](#server "Direct link to Server") Server sources accept HTTP requests containing walkerOS events and forward them to the collector. #### Express[​](#express "Direct link to Express") Turn-key HTTP event collection server with Express.js: * Standalone or embedded: Start server automatically or integrate with existing Express app * CORS support and health checks * Pixel tracking with 1x1 transparent GIF [Learn more →](https://www.walkeros.io/docs/sources/server/express.md) #### Fetch[​](#fetch "Direct link to Fetch") Web Standard Fetch API source for edge and serverless platforms: * Platform agnostic: Cloudflare Workers, Vercel Edge, Deno, Bun, Node.js 18+ * Web Standard `(Request) => Response` signature * Batch processing and CORS support [Learn more →](https://www.walkeros.io/docs/sources/server/fetch.md) #### AWS Lambda[​](#aws-lambda "Direct link to AWS Lambda") AWS Lambda HTTP handler for event collection: * Multi-platform: API Gateway REST (v1), HTTP API (v2), Function URLs * Auto-detection of API Gateway version * Pixel tracking and health checks [Learn more →](https://www.walkeros.io/docs/sources/server/aws.md) #### GCP Cloud Functions[​](#gcp-cloud-functions "Direct link to GCP Cloud Functions") Google Cloud Functions HTTP handler for event collection: * Plug-and-play: Direct assignment to Cloud Functions handler * Batches via the shared [event envelope](https://www.walkeros.io/docs/sources/envelope.md) * Configurable CORS [Learn more →](https://www.walkeros.io/docs/sources/server/gcp.md) #### AWS SQS[​](#aws-sqs "Direct link to 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 [Learn more →](https://www.walkeros.io/docs/sources/server/sqs.md) #### Google Pub/Sub[​](#google-pubsub "Direct link to 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 [Learn more →](https://www.walkeros.io/docs/sources/server/pubsub.md) ## Basic setup[​](#basic-setup "Direct link to 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, session: true, prefix: 'data-elb', }, }, }, }, destinations: { /* your destinations */ }, }); // elb is now browser.push (enhanced with DOM commands) // Use elb for manual event tracking await elb('product view', { id: 'P123', name: 'Laptop' }); ``` ## Primary source[​](#primary-source "Direct link to Primary source") `startFlow` returns an `elb` function based on your sources: * **With sources**: Returns first source's `push` method (enhanced features) * **Multiple sources**: First source is primary by default * **No sources**: Returns `collector.push` (basic functionality) ### Override primary source[​](#override-primary-source "Direct link to Override primary source") ``` const { elb } = await startFlow({ sources: { browser: { code: sourceBrowser }, dataLayer: { code: sourceDataLayer, primary: true }, // Override }, }); // elb is now dataLayer.push instead of browser.push ``` ## Reactive event handling[​](#reactive-event-handling "Direct link to Reactive event handling") Sources can react to collector events via the optional `on` method: ``` const mySource: Source.Init = async (config, env) => { return { type: 'custom', config, on: async (event, context) => { if (event === 'consent') { // React to consent changes } }, }; }; ``` **Available Events:** * `consent` - Consent state changes * `session` - Session lifecycle events * `ready` - Collector ready state * `run` - Collector run events ## Creating custom sources[​](#creating-custom-sources "Direct link to Creating custom sources") See [Create Your Own Source](https://www.walkeros.io/docs/sources/create-your-own.md) for a complete guide to building custom sources. ## Configuration[​](#configuration "Direct link to 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 | | | `data` | `any \| any` | Global data transformation applied to all events | | | `include` | `Array` | Event sections to flatten into context.data | | | `mapping` | `Mapping.Rules` | Entity-action specific mapping rules | | | `policy` | `Mapping.Policy` | Pre-processing policy rules applied before mapping | | | `settings` | `Source.Settings` | Implementation-specific configuration | | | `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` | Defer source initialization until these collector events fire (e.g., \["consent"]) | | | `logger` | `Logger.Config` | | | | `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` | One-time setup options applied during source registration (boolean enables defaults, object configures specifics) | | | `ingest` | `any \| any` | Ingest metadata extraction mapping. Extracts values from raw request objects (Express req, Lambda event) using mapping syntax. | | | `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 | | | `init` | `boolean` | Init lifecycle flag set by collector to true after Instance.init() runs | | ### Events and commands take different routes[​](#events-and-commands-take-different-routes "Direct link to 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`, `cache` and `state` run, where the event picks up its per-source ingest, and what makes the source show up in `collector.status.sources`. * **`walker *` commands** (`walker consent`, `walker user`, `walker run`, …) go straight to the collector. They are control signals, not data, so no mapping or chain applies to them. This holds for every source on both platforms, web and server alike. So 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[​](#next-steps "Direct link to Next steps") * **[Browser source](https://www.walkeros.io/docs/sources/web/browser.md)** - DOM-based tracking * **[DataLayer source](https://www.walkeros.io/docs/sources/web/dataLayer.md)** - Legacy integration * **[Create your own](https://www.walkeros.io/docs/sources/create-your-own.md)** - Custom source guide