Commands
New version available
This is an outdated version of the package. It's recommended to update and use the latest version.
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. Use the elb
function as a handy
helper.
The communication works entirely asynchronously. The elb
function pushes
events to the elbLayer
. The walker.js
will process the stack and each push.
elb
// Import
import { elb } from '@elbwalker/walker.js';
window.elb = elb;
// Or define the elb function manually in the browser as an alternative
function elb() {
(window.elbLayer = window.elbLayer || []).push(arguments);
}
Configuration
To configure
walker.js either do it while creating an instance or use the
walker config
command. There are 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
});
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 the
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');
Initialization
(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 a wizard.
elb('walker init', element); // or an array of elements
Destinations
Run the walker destination
command to add a destination to the 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 */
});
Consent Management
Learn more about consent management in detail.
Those 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 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.
On-Events
The on
command adds event listeners to the walker.js. They get called when the
type changes with run
or consent
.
elb('walker on', type, options);
Options
depend on the 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: { ... } }
Consent
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
Setting the user IDs. There are three levels for user identification. Typically, the user is a company's internal ID. In contrast, 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' });
The new user IDs have been added to each event. Make sure only to use hashed or anonymous ids.
{
"event": "entity action",
"user": {
"id": "us3r",
"device": "c00k13",
"hash": "s3ss10n"
}
// other properties omitted
}
Learn more about identification and user stitching in the guides.
We highly recommend only using fully anonymized & arbitrary IDs by default and checking your options with persistent user IDs with your data protection officer.
Hooks
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.
The walker hook
command 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
- postDestinationPush
- postPush
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;
}
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
To learn more about hooks, visit the Utils/Hooks section.