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" },
    },
    "*": {
      visible: { batch: 2000 },
    },
  },
  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),
  on: {
    // Client-related on-events
    consent: [{ marketing: console.log }],
    ready: [console.log],
    run: [console.log],
    session: [console.log],
  },
};

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
onOn.ConfigRules for on-functions that gets triggered on specific events

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 walkerjs.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
    click: { custom: { language: 'globals.language' } }, // Custom settings
  },
  product: {
    visible: { batch: 2000 }, // Bundle all product visible events
  },
  // Set custom properties
  order: { complete: { name: 'purchase' } },
  '*': { '*': { ignore: true } }, // Ignore all other non-listed events
};

The EventConfig for each event supports standardized default options. The custom option can be used to set up custom properties for the event and destinations individual settings.

PropertyValueDescription
batchnumberTime in ms to bundle the events before calling pushBatch if available.
customobjectIndividual settings for a custom destination.
ignorebooleanIf set to true the event won't get pushed to the destination.
namestringRenaming of the event (e.g. product add to add_to_cart)

To disable processing events, add {'*': {'*': { ignore: true }}} to the mapping.

Make sure to not list duplicate keys in the mapping, since this is a n object.

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, calling the init method or batching events. The only required method is push to send events to the destination.

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: { ... } }

pushBatch​

The pushBatch method is optional and gets called if the event mapping is configured with a batch number to bundle multiple events before sending them to the destination.

const pushBatch = (batch, config, instance) => {
  console.log('demo pushBatch', { batch, config });
};

The batch is an object with the key of the used mapping, the events array and the mapping object itself.

// Configuring a destinations mapping with
const mapping = {
  '*': {
    visible: { batch: 2000 },
  },
};

// Calling a matching event two times
elb('product visible');
elb('promotion visible');

// The destinations pushBatch receives the following batch after 2 seconds
batch = {
  key: '* visible',
  events: [{ event: 'product visible' }, { event: 'promotion visible' }],
  mapping: { batch: 2000 },
};

on​

The on method is used to set up rules for on-functions that get triggered by the client (individually for walker.js and node).

const on = {
  consent: [{ marketing: console.log }],
  ready: [console.log],
  run: [console.log],
  session: [console.log], // walker.js only
};

Once a client triggers an event, the destinations on method gets called. Replace the console.log with your custom function.

Available Destinations​