Skip to main content

Destinations

WalkerOS is meant to be vendor-agnostic. While clients create events, destinations are used to manage how events are processed and sent to various analytics or data storage tools. The purpose of using destinations in walkerOS is to ensure that data captured from your website or application is best-organized to easily integrated with different tools if proper consent was granted. This helps in maintaining data quality and simplifying the setup of new tools by simply mapping the events to the desired format.

info

Destinations initialize and process events only if a user granted consent.

How to use​

Destinations are added to a client (see web or node). Before receiving events from the client, the proper consent states are checked each time automatically. Destinations receive events through the push interface. Each destination can have its own configuration, which is set up in the config object. This configuration includes general settings for the destination and individual event settings. The optional init function in a destination gets called before actually pushing events. This function must return true upon successful initialization for the events to be processed.

Configuration​

The configuration of a destination is set up in the config. All properties are optional. A complete destination configuration might look like this:

{
  id: 'demo',
  custom: { foo: 'bar' },
  consent: { demo: true },
  init: false,
  loadScript: false,
  mapping: {
    // Read more in the mapping section
    page: { view: { name: 'pageview' } },
  },
  meta: { name: 'Demo', version: '1.0.0' },
  queue: true,
  verbose: false,
  onError: (error) => console.error('demo error', error),
  onLog: (message) => console.log('demo log', message),
};

Overview of all properties:

PropertyValueDescription
idstringA unique key for the destination
consentobjectRequired consent states to init and push events
customanyUsed for a destinations individual settings
initbooleanIf the destination has been initialized by calling the init method
loadScriptbooleanIf an additional script to work should be loaded
mappingobjectA map to handle events individually
metaobjectAdditional meta information about the destination
queuebooleanDisable processing of previously pushed events
verbosebooleanEnable verbose logging
onErrorfunctionCustom error handler
onLogfunctionCustom log handler

Call elb('walker destination', { push: console.log }, config); to add the destination to a client. The destination will log all events straight to the console. Edit a destinations configuration at runtime by accessing <client>.config.destinations.<id>.

To grant required consent call elb('walker consent', { demo: true });.

Mapping​

There are common rules for destinations like the renaming of the event name or the basic rules how to set up the mapping, based on entities and actions specifically. A * can be used to match all entities or actions and set up common rules. Each destination requires specific settings which can be configured in the custom section of the mapping.

const mapping = {
  entity: { action: {} }, // Basic structure
  page: {
    view: { name: 'pageview' }, // Rename the event name
    scroll: { ignore: true }, // Ignore all other page actions
    click: { custom: { language: 'globals.language' } }, // Custom settings
  },
  // Set custom properties
  order: { complete: { name: 'purchase' } },
  '*': { '*': {} }, // Process all other non-listed events
};

Both name and ignore are standardized options to either rename the event or ignore it completely. The custom object can be used to set up custom properties for the event.

If a mapping is set up, only the events listed will be processed. To also process non-listed events, add the {'*': {'*': {}}} to the mapping. Make sure to not list duplicate keys in the mapping.

info

Use Utils/Hooks to modify events before processing.

Methods​

A client communicates with a destination through the methods. It's also the clients job to check for proper consent and call the init or setup methods.

init​

The init method is optional and gets called before pushing events. It's used to eventually load additional scripts or set up the environment. To interrupt further processing, the method must return false.

The walker.js checks the config.init value to see if a destination has been initialized, or not. This way you can add a destination that has already been initialized.

// Optional init function
const init = (config) => {
  if (config.verbose) config.onLog(config.custom.foo);
  config.custom.count = 0;
};

push​

The push method gets called to send events to the destination, along with the config and eventually matching mapping.

// push function
const push = (event, config, mapping) => {
  config.custom.count++;
  event.data.count = config.custom.count;
  console.log('demo push', { event, config, mapping });
};

// elb("page view");
// Output with the mapping above
// demo log bar
// demo push { event: { data: { count: 1 }, event: 'pageview' }, config: { ... }, mapping: { ... } }