dataLayer docs

Author: alexanderkirtzel

website/docs/sources/dataLayer/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "dataLayer (coming soon)",
+  "label": "dataLayer",
   "position": 3
 }

website/docs/sources/dataLayer/configuration.mdx

@@ -0,0 +1,163 @@
+---
+title: Configuration
+sidebar_position: 2
+description: How to configure walkerOS node source.
+---
+
+import Link from '@docusaurus/Link';
+
+There are a few configuration options when creating a dataLayer source instance:
+
+```ts
+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&nbsp;<Link to="/docs/destinations/event_mapping#eventconfig">mapping configuration</Link> 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&nbsp;<Link to="https://developers.google.com/tag-platform/gtagjs/reference">gtag
+commands</Link> are used, the event name differs. In those cases the `command`
+and `parameters` are treated like entity and action.
+
+```ts
+gtag('set', 'campaign', { term: 'running+shoes' }); // "set campaign" event name
+```
+
+:::tip
+
+Use `console.log` for the `elb` function to inspect events.
+
+:::
+
+### Commands
+
+The `custom.command` property is used to map the event to a walkerOS command and
+call `elb(name, data)` with the two parameters `name` and `data`.
+
+```ts
+sourceDataLayer({
+  elb,
+  mapping: {
+    'consent update': {
+      name: 'walker consent',
+      custom: {
+        command: {
+          map: {
+            marketing: 'ad_storage',
+            analytics: 'analytics_storage',
+          },
+        },
+      },
+    },
+  },
+});
+
+gtag('consent', 'update', {
+  ad_user_data: 'denied',
+  ad_personalization: 'denied',
+  ad_storage: 'denied',
+  analytics_storage: 'granted',
+  wait_for_update: 500,
+});
+
+expect(elb).toHaveBeenCalledWith('walker consent', {
+  marketing: false,
+  analytics: true,
+});
+```
+
+### 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
+
+### purchase
+
+@TODO use codeBox with the push and the expected result.
+
+```ts
+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',
+                    },
+                  },
+                },
+              },
+            ],
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+:::info
+
+If you need professional support with your walkerOS implementation, check out
+our&nbsp;<Link to="/services">services</Link>.
+
+:::

website/docs/sources/dataLayer/consent_mode.mdx

@@ -0,0 +1,9 @@
+---
+title: Consent Mode
+sidebar_position: 3
+description: Use the Google Consent Mode to set the consent states.
+---
+
+import Link from '@docusaurus/Link';
+
+TODO

website/docs/sources/dataLayer/index.mdx

@@ -1,4 +1,26 @@
 ---
-title: dataLayer (coming soon)
-description: Installation of  walkerOS dataLayer source.
+title: dataLayer
+description: Use the dataLayer as a source for walkerOS.
 ---
+
+import Link from '@docusaurus/Link';
+import DocCardList from '@theme/DocCardList';
+import PackageLink from '/src/components/docs/package-link';
+
+<PackageLink
+  github="packages/sources/datalayer/"
+  npm="@elbwalker/source-datalayer"
+/>
+
+Many websites use the `dataLayer` to track events. The dataLayer source can be
+used work with this data. Existing and new dataLayer pushes can be processed and
+mapped to walkerOS events.
+
+Use the source to integrate single events, migrate a whole existing setup to
+walkerOS or to only use the Google Consent Mode configuration.
+
+The dataLayer source intercepts all dataLayer.pushes. Every event is cloned and
+processed in a tryCatch-block to guarantee a stable default behavior and
+preventing data mutation.
+
+<DocCardList />

website/docs/sources/dataLayer/installation.mdx

@@ -0,0 +1,34 @@
+---
+title: Installation
+sidebar_position: 1
+description: Installation of walkerOS dataLayer source.
+---
+
+import Link from '@docusaurus/Link';
+import PackageLink from '/src/components/docs/package-link';
+
+<PackageLink
+  github="packages/sources/datalayer/"
+  npm="@elbwalker/source-datalayer"
+/>
+
+Install walkerOS dataLayer source via NPM:
+
+```bash
+npm install @elbwalker/source-datalayer
+```
+
+Use the `sourceDataLayer` function to create a new source instance which returns
+the `instance` itself.
+
+```ts
+import { sourceDataLayer } from '@elbwalker/source-datalayer';
+const dataLayerSource = sourceDataLayer({ elb: window.elb });
+```
+
+:::info
+
+If you need professional support with your walkerOS implementation, check out
+our&nbsp;<Link to="/services">services</Link>.
+
+:::