Collector commands
Walker commands manage the collector's destinations, consent, user data and
custom properties. Commands are executed through the
collector's elb function, collector.elb. On a web page the browser source's
elb passes them on as well. The elb that startFlow returns is the
primary source's push: it handles commands
when that source does, as the browser source does, and it is collector.elb
when the flow has no sources.
Unknown walker commands log a warning and return { ok: false }. Commands like
walker init are browser-specific and handled by the browser source before
they reach the collector.
For browser-specific commands like DOM initialization and elbLayer communication, see Browser Source Commands.
destination
Add destinations to the collector. The recommended approach is to configure
destinations during initialization with startFlow():
import { startFlow } from '@walkeros/collector';
import { destinationGtag } from '@walkeros/web-destination-gtag';
const { collector, elb } = await startFlow({
destinations: {
gtag: {
code: destinationGtag,
config: {
loadScript: true,
settings: {
ga4: { measurementId: 'G-XXXXXXXXXX' },
},
},
},
},
});To add a destination at runtime, use the walker destination command,
elb('walker destination', { code: destinationGtag, config: { loadScript: true, settings: { ga4: { measurementId: 'G-XXXXXXXXXX' } } } }), or
collector.addDestination(). See destination-specific documentation for
configuration options.
consent
Set consent states on the collector. Names are free-form; common groups are
functional, analytics, and marketing. Values are booleans, and true means
consent is granted. A command only updates the keys it contains.
elb('walker consent', { marketing: true, analytics: true });When none of the keys in a destination's config.consent is granted, the
destination stops receiving events. Its events wait in a queue instead, and
once consent is granted during the same run, the queued events are delivered
in order. Server flows built by the CLI skip these events instead of queueing
them (consentDenied: 'skip', see
Consent-denied events on a server).
Learn more about consent management in detail.
on
Add event listeners to the collector. They get called when specific events occur
like run or consent changes.
elb('walker on', { type, rules });rules depends on type and can also be an array for multiple listeners
at once. Every callback receives (data, context) where context exposes
collector and logger.
Callback signatures
| Action | Callback signature |
|---|---|
| consent | { [key]: (consent, context) => void | Promise<void> } |
| ready | (_, context) => void | Promise<void> |
| run | (_, context) => void | Promise<void> |
| session | (session, context) => void | Promise<void> |
| user | (user, context) => void | Promise<void> |
| (other) | (data, context) => void | Promise<void> |
The context object has the same shape for every action:
| Field | Type | Description |
|---|---|---|
collector | Collector.Instance | Active collector, use for push/queue |
logger | Logger.Instance | Use for info/warn/error/debug |
run
With each run, the on-event will be called. A handler registered after the
collector started is also called once right away. Use context.collector to
access the running instance.
elb('walker on', {
type: 'run',
rules: function (_, context) {
console.log('run with', { instance: context.collector });
},
});Every time the run command is called, the function will be executed:
const { elb } = await startFlow({ run: true });
elb('walker on', {
type: 'run',
rules: (_, context) =>
console.log('run with', { instance: context.collector }),
});
// Output: run with { instance: { ... } }
elb('walker run');
// Output: run with { instance: { ... } }consent
A consent handler is called with consent as the first argument and context
(carrying collector and logger) as the second. rules is an object keyed
by consent name.
function onConsent(consent, context) {
console.log('consent with', { consent, instance: context.collector });
if (consent.marketing) elb('walker user', readFromStorage());
}
elb('walker on', {
type: 'consent',
rules: { marketing: onConsent },
});onConsent runs whenever a walker consent command contains marketing,
whether the value is true or false and whether it changed. It receives only
the values of that command, so check the value inside the handler:
elb('walker consent', { functional: true }); // Won't trigger the onConsent function
elb('walker consent', { marketing: true }); // Will trigger the onConsent function
elb('walker consent', { marketing: false }); // Will also trigger the onConsent functionWhen registered, and when the collector starts, the handler receives the full
consent state and runs if marketing is set. No handler is called before the
collector runs.
user
Set user identification data for the collector. There are three levels: user (company's internal ID), device (longer-term identifier), and session (temporary identification).
elb('walker user', { id: 'us3r', device: 'c00k13', session: 's3ss10n' });User IDs are added to each event.
{
"name": "entity action",
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
}
// other properties omitted
}Use fully anonymized & arbitrary IDs by default and check your options with persistent user IDs with your data protection officer.
Learn more about identification and user stitching
You can also set user identity declaratively from the DOM with the
data-elbuser attribute. See the browser source's
HTML attributes.
custom
Set custom properties on the collector (collector.custom), for values that
are not event data. They are not added to events; on('custom') subscribers
and the on handlers of sources and destinations receive them.
elb('walker custom', { key: 'value' });globals
Set global properties that are added to each event processed by the collector.
elb('walker globals', { key: 'value' });These values are the base for every event the collector processes, including
events from server sources and any source with no DOM to read. A browser
source adds what it finds in data-elbglobals on top, and those values win
per key. Defaults that should survive a walker run belong in the collector's
globalsStatic config instead: it seeds the base at startup, and a run that
supplies its own globals resets the base to it. An event carries the globals
known when it was created, so a global set after an event is captured does not
reach one already waiting, whether it waits for consent, for a destination's
require gate, or for a destination to be added at all.
A transformer that runs before the collector, in a source's next chain, sees
the event before enrichment and therefore before the base globals are merged.
config
Change the collector's configuration at runtime. The keys given are merged
into the current configuration; an array, such as the collector chain next,
is replaced as a whole. The new value applies to later events.
elb('walker config', { next: ['validate'] });run
Start the collector, or start a new run. startFlow sends the first run
unless it is called with run: false. A run accepts state to set first, any
of consent, user, globals and custom; its globals replace the current
globals on top of globalsStatic.
elb('walker run', { globals: { pagegroup: 'checkout' } });Each run discards the events that wait in a destination's consent queue and the
collector's replay buffer, delivers events pushed before the first run (see
Pre-run events) and calls the run handlers. With
history on, the browser source starts a run on every route change
(browser source commands).
State delivery
State commands (consent, user, globals, custom) set values on the
collector. The collector records every state change immediately, even when it
arrives before run. Side-effecting delivery to subscribers (the on
callbacks above, source on handlers, and destination on handlers) happens at or after run: when the
collector starts, it delivers the current state once to every subscriber that
has not yet seen it.
This gives five practical guarantees:
- Exactly-once. Each subscriber is invoked once per state change. The collector tracks what each subscriber has already received, so re-running or re-registering never double-fires a reaction.
- Order-independent. A consent-gated reaction fires correctly whether the
state was set before or after
run, and regardless of the order in which sources initialize. You don't have to set state and start the collector in a particular sequence. requireis a timing hint, not a correctness dependency. A source'srequireonly delays when its firstondelivery lands. A dependent source reacts to state correctly whether or not it declaresrequire.- Before the first push. A destination's
onhandler receives the current state before any event is delivered to it. A destination without aninitmethod is initialized without one, once its consent requirement is met, and its waitingondeliveries reach it then. The collector waits for an async handler to finish, up to the destination'sconfig.timeout, before it delivers events. If the handler does not finish in that time, or fails, the destination's events wait in its queue instead of going out without the state (queuedwith the reasonheld) for oneconfig.timeoutwindow. A new delivery of the state starts only once the handler has settled: a handler that failed is retried by a push after the window, and one that timed out starts the new delivery when it settles late. When that delivery succeeds, the held events are delivered and the destination receives events again. Until then, after the window, the held events and every later one fail withblockedand go to the dead-letter queue; a handler that never settles keeps the destination blocked (see the codes in Logger). Events still held when the nextwalker runstarts are discarded. Lifecycle handlers such ason('run')are awaited too, bounded by the same timeout; one that does not finish holds no events. Handlers of different destinations run independently, so a slow handler in one destination does not delay events to other destinations. - Commands wait for handlers. An async destination
onhandler must settle: until it settles or reachesconfig.timeout, that destination receives no events.elbcommands andstartFlowresolve only after the destinations'onhandlers for that command have settled or timed out; a command sent while a handler is still busy with an earlier state update resolves at once, and its update is applied right after the running one, while that destination's events wait for it.
This means sources don't need their own deduplication for state deliveries: the collector enforces exactly-once.
Pre-run events
The same record-immediately, deliver-at-run rule applies to events. An event pushed while the collector has not run yet is held in a bounded FIFO buffer instead of being discarded, and replayed once the collector starts:
const { collector, elb } = await startFlow({ run: false, destinations: { ... } });
await elb('walker consent', { essential: true });
await elb({ name: 'page view' }); // held, not delivered yet
await elb('walker run'); // 'page view' is delivered now- Replayed in push order. Held events reach destinations in the order they
were pushed, after the run-barrier state delivery, so each one carries the
consent, user, globals and custom state that is current at
run. - The pipeline runs once, at replay. Mapping, transformer chains and enrichment are applied when the event is replayed, not when it is held.
- Exactly-once. A second
rundoes not re-deliver events an earlier run already replayed. - Bounded. The buffer holds at most
queueMaxevents (default1000, the same setting that caps the collector's replay buffer). When it is full, the newest event is refused and the held ones stay: that push answersok: falsewith the reasonqueue-full, counts incollector.status.failedand logs an ERROR line. Each hold is logged atdebuglevel.
Commands are unaffected: they continue to apply immediately, as described above.
hook
Hooks run before and after collector operations, such as a push, a command or
a destination's push, and can validate, change or cancel them. Available hooks
include Push,
DestinationInit, DestinationPush, StoreGet, StoreSet, and
StoreDelete.
Add a hook with the hook command:
elb('walker hook', { name: '<moment>', fn: hookFn });Moments
A pre-hook runs before its function and a post-hook right after the function
returns. When the function is async, the post-hook runs before its work has
finished and params.result is the pending promise: await it to read the
outcome. For one event, the moments run in this order:
- prePush
- postPush (the push is still running)
- preDestinationInit
- postDestinationInit
- preDestinationPush or preDestinationPushBatch
- postDestinationPush or postDestinationPushBatch
Others are:
- preCommand / postCommand
- preTransformerInit / postTransformerInit
- preTransformerPush / postTransformerPush
- preStoreGet / postStoreGet
- preStoreSet / postStoreSet
- preStoreDelete / postStoreDelete
Function signatures
Every hook receives params as its first argument: params.fn is the
original function, and post-hooks also get params.result. A post-hook's return
value replaces the result, so return params.result to keep it. Use the
following function signatures:
// Push
function prePush(params, event, options) {
return params.fn(event, options);
}
async function postPush(params, event, options) {
const result = await params.result;
console.log('default return result', result);
return result;
}
// DestinationInit
function preDestinationInit(params, context) {
return params.fn(context);
}
function postDestinationInit(params, context) {
console.log('default return result', params.result);
return params.result;
}
// DestinationPush
function preDestinationPush(params, event, context) {
return params.fn(event, context);
}
function postDestinationPush(params, event, context) {
return params.result;
}
// DestinationPushBatch
function preDestinationPushBatch(params, batch, context) {
return params.fn(batch, context);
}
function postDestinationPushBatch(params, batch, context) {
return params.result;
}
// StoreGet
function preStoreGet(params, key) {
return params.fn(key);
}
function postStoreGet(params, key) {
return params.result;
}
// StoreSet
function preStoreSet(params, key, value, ttl) {
return params.fn(key, value, ttl);
}
function postStoreSet(params, key, value, ttl) {
return params.result;
}
// StoreDelete
function preStoreDelete(params, key) {
return params.fn(key);
}
function postStoreDelete(params, key) {
return params.result;
}Adding a hook
Add hooks during collector initialization or via the hook command:
// Add hooks during initialization
const { collector } = await startFlow({
hooks: {
prePush: (params, ...args) => {
window.elbTimer = Date.now();
return params.fn(...args);
},
},
});
// Add hooks via command
elb('walker hook', {
name: 'postPush',
fn: async function (params, ...args) {
const result = await params.result;
console.log('walker exec time', Date.now() - window.elbTimer);
return result;
},
});
elb({ name: 'page view' });
// Output:
// walker exec time 1flush
Send every pending destination batch now (see
Batch scheduling) and keep the collector
running. It answers a PushResult that merges the outcome of each flushed
batch, so a failed flush shows under failed with its reason. Shutdown uses
the same flush, and the browser source sends walker flush when the page goes
away (pagehide, or the page turning hidden), so batched web events are not
lost when a visitor leaves.
await collector.command('flush');shutdown
Stop the collector: sources are destroyed first, then pending batches are
flushed (up to 5 seconds each) and destinations, transformers and stores are
destroyed, in that order. A second walker shutdown does nothing. The runner
sends it on SIGTERM and SIGINT; in the browser nothing sends it. Outside the
runner, send it with collector.command and await it before the process exits,
for example from a signal handler. Node's exit event cannot wait for the
flush, so pending batches sent from there are lost:
process.on('SIGTERM', async () => {
await collector.command('shutdown');
process.exit(0);
});