Commands

The walker is designed to support asynchronous communication through the elbLayer array. With the creation of the Walkerjs, the elbLayer items are scanned. The walker will process each push.

The communication works entirely asynchronously. The elb function pushes events to the elbLayer. The walker.js will process each push.

elb

// Import
import { elb } from '@elbwalker/walker.js';
window.elb = elb;

// Or define the elb function manually in the browser
function elb() {
  (window.elbLayer = window.elbLayer || []).push(arguments);
}

Usage options:

elb("entity action", data, ...);
elb({event: "entity action", data: { foo: "bar"}});

config

To configure walker.js either do it while creating an instance or use the walker config command. There are a few options available before a run is called:

elb('walker config', {
  consent: { functional: true }, // Initial consent states, learn more under consent
  elb: 'elb', // Name of assign the elb function to the window
  elbLayer: window.elbLayer, // Public elbwalker API for async communication (only prior run)
  globals: {}, // Static attributes added to each event
  instance: 'walkerjs', // Name of the walkerjs instance to assign to the window
  pageview: true, // Trigger a page view event by default
  prefix: 'data-elb', // Attributes prefix used by the walker
  user: { id: '', device: '', session: '' }, // Setting the user ids
  tagging: 0, // Current version of the tracking setup
});

note

After the run command, only globals and tagging can be updated.

run

A run can be seen like a regular page view. It will start the walker.js and (re-)Initialize the handler, reset counters, clear queues, and update globals. A page view event is triggered by default, the tagging is checked for load actions, and the elbLayer stack is processed.

elb('walker run');

A run accepts a partial State parameter to predefine the state of the walker.js:

elb('walker run', { group: 'gr0up1d' });

init

(Re-)initializes event listeners on one or multiple target elements. Can be used e.g., asynchronously loaded content like newly added products in a category list or within a wizard.

elb('walker init', element); // or an array of elements

destination

Run walker destination to add a destination to walker.js. Individual destination configurations can be made by using the destination.config property.

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

import destinationGTM from '@elbwalker/destination-web-google-gtm';
elb('walker destination', destinationGTM, {
  /* custom config */
});

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. Previously pushed events during the run are now shared with existing destinations and new ones.

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

Setting a consent state to false will immediately stop a destination from processing any events.

info

Learn more about consent management in detail.

on

on adds event listeners to walker.js. They get called when the type changes with run or consent.

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:

const walkerjs = Walkerjs({ run: true });
// Output: run with { instance: { ... } }
elb('walker run');
// Output: run with { instance: { ... } }

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

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

There are three levels for user identification. Typically, the user is a company's internal ID. The device ID can be treated as a value stored in a cookie for a more extended period, and the session can be used for temporary identification.

elb('walker user', { id: 'us3r', device: 'c00k13', session: 's3ss10n' });

User IDs have 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

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

globals

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

hook

Hooks can be used to customize the default behavior of the walker.js. Three hooks are available: Push, DestinationInit, and DestinationPush. Hooks allows for validation, manipulation, or even eventual cancellation of default behavior.

walker hook adds a function to the walker.js to customize or enhance default processing.

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

Moments

The overall function execution order is as follows:

prePush
preDestinationInit
postDestinationInit
preDestinationPush or preDestinationPushBatch
postDestinationPush or postDestinationPushBatch
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

To add a hook, either add the hooks during initialization or call the hook command:

const walkerjs = Walkerjs({
  hooks: {
    // Add hooks on init
    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

tip

To learn more about hooks, visit the utils/hooks section.

info

If you need professional support with your walkerOS implementation, check out our services.

elb​

config​

run​

init​

destination​

consent​

on​

run​

consent​

user​

custom​

globals​

hook​

Moments​

Function signatures​

Adding a hook​

elb