Configuration

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

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

await 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 (return true to abort processing)
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

note

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

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

await 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.

note

The filter function can also be used to ignore events that might have been pushed by a walker.js destination.

Examples

add_to_cart

Configuration

await 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',
            },
          },
        },
      },
    },
  },
});

await 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

await 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',
                    },
                  },
                },
              },
            ],
          },
        },
      },
    },
  },
});

await 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.