Skip to main content
Ask your AI

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:

Source
Collector
Destination
123
1Capture: Listen for events (DOM clicks, API calls, player actions)2Transform: Convert to walkerOS event format (entity action, data)3Send: Forward to collector for processing and routing

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.ingest resolves 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-*)

Learn more →

dataLayer​

Integrates with existing analytics implementations:

  • Works with GA4 and GTM dataLayer
  • Event transformation and filtering
  • Gradual migration support

Learn more →

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 →

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

Learn more →

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

Learn more →

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) => Response signature
  • Batch processing and CORS support

Learn more →

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

Learn more →

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

Learn more →

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 →

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 →

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 push method (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.push

Reactive 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 changes
  • user, globals, custom - State set by the walker command of the same name
  • session - Session lifecycle events
  • config - Collector config changes
  • ready - Collector ready state
  • run - 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.

PropertyTypeDescriptionMore
consentWalkerOS.ConsentRequired consent states to process any events
mappingMapping.RulesEntity-action specific mapping rules
policyMapping.PolicyPre-processing policy rules applied to the event before its data is mapped
credentialsSource.CredentialsOptional credentials (source-defined shape)
envSource.BaseEnvEnvironment dependencies (platform-specific)
idstringSource identifier (defaults to source key)
primarybooleanMark as primary (only one can be primary)
requireArray<string>Collector events (e.g., ["consent"]) that must fire before the source receives on() calls; init and event capture are not delayed
loggerLogger.ConfigLogger configuration (level, handler) to override the collector defaults
asyncboolean | objectRespond-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.
setupboolean | objectProvisioning options for `walkeros setup`, which runs only when invoked (boolean enables defaults, object configures specifics)
ingestany | anyIngest metadata extraction mapping. On server sources it resolves against the normalized request scope (method, url, path, query, headers, body, ip, raw), without a prefix.
disabledbooleanCompletely skip this source (no init, no event capture)
stateState.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, 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, 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​

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