Skip to main content
Ask your AI

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.

note

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' },
        },
      },
    },
  },
});
tip

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.

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).

info

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​

ActionCallback 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:

FieldTypeDescription
collectorCollector.InstanceActive collector, use for push/queue
loggerLogger.InstanceUse 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: { ... } }

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 function

When 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
}
warning

Use fully anonymized & arbitrary IDs by default and check your options with persistent user IDs with your data protection officer.

tip

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.
  • require is a timing hint, not a correctness dependency. A source's require only delays when its first on delivery lands. A dependent source reacts to state correctly whether or not it declares require.
  • Before the first push. A destination's on handler receives the current state before any event is delivered to it. A destination without an init method is initialized without one, once its consent requirement is met, and its waiting on deliveries reach it then. The collector waits for an async handler to finish, up to the destination's config.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 (queued with the reason held) for one config.timeout window. 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 with blocked and 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 next walker run starts are discarded. Lifecycle handlers such as on('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 on handler must settle: until it settles or reaches config.timeout, that destination receives no events. elb commands and startFlow resolve only after the destinations' on handlers 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 run does not re-deliver events an earlier run already replayed.
  • Bounded. The buffer holds at most queueMax events (default 1000, 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 answers ok: false with the reason queue-full, counts in collector.status.failed and logs an ERROR line. Each hold is logged at debug level.

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:

  1. prePush
  2. postPush (the push is still running)
  3. preDestinationInit
  4. postDestinationInit
  5. preDestinationPush or preDestinationPushBatch
  6. 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 1

flush​

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);
});
💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)