Collector Commands

The collector provides a core event processing engine that manages destinations, consent, user data, and custom properties. Commands are executed through the elb function

note

For browser-specific commands like DOM initialization and elbLayer communication, see Browser Source Commands.

destination

Add destinations to the collector for event processing. Destinations handle the actual delivery of events to third-party services.

// Simple demo destination for console.log
const destinationLog = { push: console.log };
elb('walker destination', destinationLog);

// Real destination example
import { destinationGtag } from '@walkeros/web-destination-gtag';
elb('walker destination', destinationGtag, {
  /* custom config */
});

tip

Destinations are typically configured during collector initialization via createCollector(). See destination-specific documentation for configuration options.

consent

Manage consent states for the collector. Names can be defined arbitrarily, but common groups are functional, analytics, and marketing. Values are booleans, and once a value is set to true it's treated as consent being granted.

elb('walker consent', { marketing: true, analytics: true });

Setting a consent state to false will immediately stop a destination from processing any events. Previously pushed events during the run are shared with existing destinations once consent is granted.

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, options);

Options depend on type and can also be an array for multiple listeners at once.

run

With each run, the on-event will be called with instance as a parameter.

elb('walker on', 'run', function (instance) {
  console.log('run with', { instance });
});

Every time the run command is called, the function will be executed:

// Setup collector with browser source
const { collector } = await createCollector({ run: true });
// Output: run with { instance: { ... } }
elb('walker run');
// Output: run with { instance: { ... } }

consent

Every time the consent changes, the rules-matching function(s) will be called with the parameters instance and consent.

function onConsent(instance, consent) {
  console.log('consent with', { instance, consent });
  if (consent.marketing) elb('walker user', readFromStorage());
}

//   command      type        rule       function
elb('walker on', 'consent', { marketing: onConsent });

The onConsent function will only be called when the marketing consent changes:

elb('walker consent', { functional: true }); // Won't trigger the onConsent function
elb('walker consent', { marketing: true }); // Will trigger the onConsent function

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.

{
  "event": "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

custom

Set custom properties that are added to each event processed by the collector.

elb('walker custom', { key: 'value' });

globals

Set global properties that are added to each event processed by the collector.

elb('walker globals', { key: 'value' });

hook

Hooks customize the default behavior of the collector. Available hooks include Push, DestinationInit, and DestinationPush. Hooks allow for validation, manipulation, or cancellation of default behavior.

Add hooks to the collector to customize or enhance default processing.

elb('walker hook', '<moment>', hookFn);

Moments

The overall function execution order is as follows:

1. prePush
2. preDestinationInit
3. postDestinationInit
4. preDestinationPush or preDestinationPushBatch
5. postDestinationPush or postDestinationPushBatch
6. postPush

Others are:

• preSessionStart
• postSessionStart

Function signatures

In general, params will be prefixed as a parameter, containing fn which is the original function and result for the post-hooks. Use the following function signatures:

// Push
function prePush(params, event, data, options, context, nested) {
  return params.fn(event, data, options, context, nested);
}
function postPush(params, event, data, trigger, context, nested) {
  console.log('default return result', params.result);
  return;
}

// DestinationInit
function preDestinationInit(params, config) {
  return params.fn(config);
}
function postDestinationInit(params, config) {
  console.log('default return result', params.result);
  return params.result;
}

// DestinationPush
function preDestinationPush(params, event, config, mapping, runState) {
  console.log('default return result', params.result);
  return params.fn(event, config, mapping, runState);
}
function postDestinationPush(params) {
  // Custom code with a void return
  return;
}

// DestinationPushBatch
function preDestinationPushBatch(params, event, config, mapping, runState) {
  console.log('default return result', params.result);
  return params.fn(event, config, mapping, runState);
}
function postDestinationPushBatch(params) {
  // Custom code with a void return
  return;
}

Adding a hook

Add hooks during collector initialization or via the hook command:

// Add hooks during initialization
const { collector } = await createCollector({
  hooks: {
    prePush: (params, ...args) => {
      window.elbTimer = Date.now();
      return params.fn(...args);
    },
  },
});

// Add hooks via command
elb('walker hook', 'postPush', function (params, ...args) {
  console.log('walker exec time', Date.now() - window.elbTimer);
});

elb('entity action');

// Output:
// walker exec time 1