Create Your Own Destination

This guide provides the essentials for building a custom walkerOS destination.

What is a Destination?

A destination is a function that receives events from walkerOS and sends them to an external service, such as an analytics platform, an API, or a database.

The Destination Interface

A destination is an object that implements the Destination interface. The most important property is the push function, which is called for every event.

The `push` function

The push function is where you'll implement the logic to send the event to your desired service. It receives the event and a context object containing the destination's configuration.

Example: A Simple Webhook Destination

Here is an example of a simple destination that sends events to a webhook URL.

Schema Validation (Optional)

Destinations can export Zod schemas to provide runtime validation and TypeScript IDE support for configuration options. Export a schemas namespace containing SettingsSchema and MappingSchema to enable validation, autocomplete, and JSON Schema generation for tools like MCP and Explorer.

See the Destination Schemas Guide for implementation details, or reference existing destinations like Meta Pixel for complete examples.

The `on` method (Optional)

The optional on method allows your destination to respond to collector lifecycle events. This is useful for handling consent changes, session management, or cleanup tasks.

Available Events

consent - Called when user consent changes, with consent state as context
session - Called when a new session starts, with session data as context
ready - Called when the collector is ready to process events
run - Called when the collector starts or resumes processing

Using your destination

To use your custom destination, add it to the destinations object in your collector configuration.

Advanced Example: Session Management

Here's a more advanced example that demonstrates session handling and cleanup:

TypeScript Integration

To get full TypeScript support for your destination's configuration, you can extend the WalkerOS.Destinations interface.

Environment Dependencies (Testing)

The env parameter enables dependency injection for external APIs and SDKs. This allows you to test your destination logic without making actual API calls or requiring real browser globals.

Use Cases:

Mock external SDKs (Google Analytics, Facebook Pixel, AWS SDK)
Test without network requests
Simulate different API responses
Run tests in any environment (Node.js, browser, CI)

Defining an Environment

Define the external dependencies your destination needs:

Using Environment in Your Destination

Use the 3rd generic parameter for type safety, then access env in init or push:

Creating Test Environments

Create reusable mock environments in an examples/env.ts file:

Export from your examples index:

Using in Tests

Key Points:

Production: No env needed, uses real APIs (window, fetch, SDKs)
Testing: Provide env with mocks for isolated testing
Type Safety: 3rd generic parameter gives full autocomplete
Fallback: getEnv(env) automatically uses real APIs if env not provided
Reusable: Store mock environments in examples/env.ts for consistency

💡 Need Professional Support?

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

What is a Destination?​

The Destination Interface​

The push function​

Example: A Simple Webhook Destination​

Schema Validation (Optional)​

The on method (Optional)​

Available Events​

Example: Consent-Aware Destination​

Using your destination​

Advanced Example: Session Management​

TypeScript Integration​

Environment Dependencies (Testing)​

Defining an Environment​

Using Environment in Your Destination​

Creating Test Environments​

Using in Tests​