Configuration

There are a few configuration options when creating a dataLayer source instance:

import { sourceDataLayer } from '@elbwalker/source-datalayer';

sourceDataLayer({
  elb: elb, // The elb function to use (required)
  filter: (event) => {
    // Filter out internal GTM events
    return event.event.startsWith('gtm.');
  },
  mapping: {
    'consent update': {
      name: 'walker consent',
      custom: {
        command: {
          map: {
            marketing: 'ad_storage',
            analytics: 'analytics_storage',
          },
        },
      },
    },
  },
  name: 'dataLayer', // The name of the dataLayer variable
  prefix: 'dataLayer', // Used to prefix the event name
});

Option	Type	Description
elb*	function	The function to push the events to
filter	function	A check to filter specific events
mapping	object	The mapping configuration of the events
name	string	Name of the dataLayer array (default: dataLayer)
prefix	string	Prefix for the event name to match entity action format (default: dataLayer)

Properties with a * are required.

Usually, the event name is the actual event property of the dataLayer event. If gtag commands are used, the event name differs. In those cases the command and parameters are treated like entity and action.

gtag('set', 'campaign', { term: 'running+shoes' });
// Will become "set campaign" as event name

tip

Use console.log for the elb function to inspect events.

Commands

The custom.command mapping property is used to map the event to a walkerOS command and call elb(name, data) with the two parameters name and data.

Configuration

sourceDataLayer({
  elb,
  mapping: {
    'consent update': {
      name: 'walker consent',
      custom: {
        command: {
          map: {
            marketing: 'ad_storage',
            analytics: 'analytics_storage',
          },
        },
      },
    },
  },
});

sourceDataLayer({ elb, mapping: { 'consent update': { name: 'walker consent', custom: { command: { map: { marketing: 'ad_storage', analytics: 'analytics_storage', }, }, }, }, }, });

Event

gtag('consent', 'update', {
  ad_user_data: 'denied',
  ad_personalization: 'denied',
  ad_storage: 'denied',
  analytics_storage: 'granted',
  wait_for_update: 500,
});

gtag('consent', 'update', { ad_user_data: 'denied', ad_personalization: 'denied', ad_storage: 'denied', analytics_storage: 'granted', wait_for_update: 500, });

Result

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

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

Infinite loops

The internal processing flag is used to prevent infinite loops. While the dataLayer source listens for new dataLayer.push events and forwards them to a walker.js instance, another dataLayer related destination might push that event to the dataLayer again (like GA4). Therefore, while processing an event, newly pushed events are ignored and stored in the skipped array.

As a additional rule the filter function can be used to ignore events that might have been pushed by a walker.js destination.

Examples

add_to_cart

Configuration

sourceDataLayer({
  elb,
  mapping: {
    add_to_cart: {
      name: 'product add',
      data: {
        map: {
          data: {
            map: {
              id: 'items.0.item_id',
              name: 'items.0.item_name',
              discount: 'items.0.discount',
              brand: 'items.0.item_brand',
              category: 'items.0.item_category',
              color: 'items.0.item_variant',
              currency: 'currency',
              price: 'items.0.price',
              quantity: 'items.0.quantity',
              total: 'value',
            },
          },
        },
      },
    },
  },
});

sourceDataLayer({ elb, mapping: { add_to_cart: { name: 'product add', data: { map: { data: { map: { id: 'items.0.item_id', name: 'items.0.item_name', discount: 'items.0.discount', brand: 'items.0.item_brand', category: 'items.0.item_category', color: 'items.0.item_variant', currency: 'currency', price: 'items.0.price', quantity: 'items.0.quantity', total: 'value', }, }, }, }, }, }, });

Event

dataLayer.push({
  event: 'add_to_cart',
  currency: 'EUR',
  value: 840,
  items: [{
    item_id: 'abc',
    item_name: 'Everyday Ruck Snack',
    discount: 10,
    item_brand: 'Fictive',
    item_category: 'Apparel',
    item_list_id: 'related_products',
    item_variant: 'black',
    price: 420,
    quantity: 2,
  }],
});

dataLayer.push({ event: 'add_to_cart', currency: 'EUR', value: 840, items: [{ item_id: 'abc', item_name: 'Everyday Ruck Snack', discount: 10, item_brand: 'Fictive', item_category: 'Apparel', item_list_id: 'related_products', item_variant: 'black', price: 420, quantity: 2, }], });

Result

elb({
  event: 'product add',
  data: {
    currency: 'EUR',
    id: 'abc',
    name: 'Everyday Ruck Snack',
    discount: 10,
    brand: 'Fictive',
    category: 'Apparel',
    color: 'black',
    price: 420,
    quantity: 2,
    total: 840,
  },
});

elb({ event: 'product add', data: { currency: 'EUR', id: 'abc', name: 'Everyday Ruck Snack', discount: 10, brand: 'Fictive', category: 'Apparel', color: 'black', price: 420, quantity: 2, total: 840, }, });

purchase

Configuration

sourceDataLayer({
  elb,
  mapping: {
    purchase: {
      name: 'order complete',
      data: {
        map: {
          data: {
            map: {
              id: 'transaction_id',
              currency: 'currency',
              shipping: 'shipping',
              taxes: 'tax',
              total: 'value',
              coupon: 'coupon',
            },
          },
          nested: {
            loop: [
              'items',
              {
                map: {
                  data: {
                    map: {
                      id: 'item_id',
                      name: 'item_name',
                      price: 'price',
                    },
                  },
                },
              },
            ],
          },
        },
      },
    },
  },
});

sourceDataLayer({ elb, mapping: { purchase: { name: 'order complete', data: { map: { data: { map: { id: 'transaction_id', currency: 'currency', shipping: 'shipping', taxes: 'tax', total: 'value', coupon: 'coupon', }, }, nested: { loop: [ 'items', { map: { data: { map: { id: 'item_id', name: 'item_name', price: 'price', }, }, }, }, ], }, }, }, }, }, });

Event

gtag('event', 'purchase', {
  transaction_id: '0rd3r1d',
  currency: 'EUR',
  shipping: 5.22,
  tax: 73.76,
  value: 555,
  coupon: 'SUMM3RS4L3',
  items: [{
    item_id: 'abc',
    item_name: 'Everyday Ruck Snack',
    discount: 10,
    item_brand: 'Fictive',
    item_category: 'Apparel',
    item_list_id: 'related_products',
    item_variant: 'black',
    price: 420,
    quantity: 2,
  }, {
    item_id: 'xyz',
    item_name: 'Cool Cap',
    price: 42,
  }],
})

gtag('event', 'purchase', { transaction_id: '0rd3r1d', currency: 'EUR', shipping: 5.22, tax: 73.76, value: 555, coupon: 'SUMM3RS4L3', items: [{ item_id: 'abc', item_name: 'Everyday Ruck Snack', discount: 10, item_brand: 'Fictive', item_category: 'Apparel', item_list_id: 'related_products', item_variant: 'black', price: 420, quantity: 2, }, { item_id: 'xyz', item_name: 'Cool Cap', price: 42, }], })

Result

elb({
  event: 'order complete',
  data: {
    id: '0rd3r1d',
    currency: 'EUR',
    shipping: 5.22,
    taxes: 73.76,
    total: 555,
    coupon: 'SUMM3RS4L3',
  },
  nested: [
    {
      type: 'product',
      data: {
        id: 'abc',
        name: 'Everyday Ruck Snack',
        price: 420,
      },
      nested: [],
      context: {},
    },
    {
      type: 'product',
      data: {
        id: 'xyz',
        name: 'Cool Cap',
        price: 42,
      },
      nested: [],
      context: {},
    },
  ],
});

elb({ event: 'order complete', data: { id: '0rd3r1d', currency: 'EUR', shipping: 5.22, taxes: 73.76, total: 555, coupon: 'SUMM3RS4L3', }, nested: [ { type: 'product', data: { id: 'abc', name: 'Everyday Ruck Snack', price: 420, }, nested: [], context: {}, }, { type: 'product', data: { id: 'xyz', name: 'Cool Cap', price: 42, }, nested: [], context: {}, }, ], });

info

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