Create Your Own Source

A source captures events from an environment (browser, server, third-party API) and forwards them to the walkerOS collector.

The source interface

Sources are async functions that receive a context object and return a source instance:

The context contains:

The returned instance must implement:

Types bundle

Sources use a Types interface to bundle all TypeScript types:

The 4 type parameters:

Settings: Source configuration options
Mapping: Event mapping (usually never for sources)
Push: External push signature (what source.push exposes)
Env: Internal dependencies (what source calls via env.elb)

Context destructuring

The context parameter contains everything your source needs:

The collector provides env.push (formerly env.elb). You provide other dependencies (like window, document, custom APIs) when configuring the source.

Minimal example

Complete example: Event API source

Capturing events from a third-party API with event listeners:

Using your source

Testing your source

Test Utilities

Test Example

Common patterns

Polling for API Readiness

When the external API isn't immediately available:

Source as adapter pattern

Sources bridge external systems and the collector:

External System  ←→  Source (Adapter)  ←→  Collector

Two interfaces:

External (source.push): Platform-specific signature
- Browser: push(elem, data, options) → Returns Promise<PushResult>
- Server: push(req, res) → Returns Promise<void> (writes HTTP response)
- Your choice: Match your environment's needs
Internal (env.elb): Standard collector interface
- Always Elb.Fn - same across all sources
- Sources translate external inputs → standard events → env.elb(event)

Example signatures:

The Push type parameter defines what your source exposes externally. Internally, all sources use env.elb to forward to the collector.

Key concepts

Context pattern: Sources receive a single context object with config, env, logger, id
Validate custom dependencies: Only check optional env properties your source needs
Types bundle: Use 4-parameter pattern for full type safety
Adapter pattern: External push adapts to environment, internal env.push stays standard
Cleanup: Implement destroy() to remove listeners
Stateless: Let collector manage state

Next steps

Review Browser Source for DOM patterns
Review DataLayer Source for interception patterns
Learn about creating destinations

💡 Need Professional Support?

Need professional support with your walkerOS implementation? Check out our services.

The source interface​

Types bundle​

Context destructuring​

Minimal example​

Complete example: Event API source​

Using your source​

Testing your source​

Test Utilities​

Test Example​

Common patterns​

Polling for API Readiness​

Source as adapter pattern​

Key concepts​

Next steps​