Skip to main content

Data Layer Guide

What Is Selwise Data Layer

Selwise maintains a structured layer for behavioral events and integration-safe payloads.

  • Default layer variable: window.selwiseLayer
  • Runtime push method: pushDataLayer(data)
  • Runtime read method: getDataLayer()

Currency rule: use ISO-4217 uppercase currency codes and replace SITE_CURRENCY placeholders with your site currency.

Access By Integration Mode

  • CDN: window.Selwise.pushDataLayer(...)
  • npm instance: widget.pushDataLayer(...)
  • npm global (optional): window.Selwise.pushDataLayer(...) with exposeGlobal: true
  • React Native: sdk.pushDataLayer(...) and sdk.getDataLayer() (local structured snapshot)

Basic Setup

npm

import Selwise from '@selwise/widget';

const widget = new Selwise();
await widget.init({
  siteKey: 'YOUR_SITE_KEY',
  apiUrl: 'https://api.selwise.com/api/v1',
  exposeGlobal: true,
});

CDN

<script
  src="https://widget.selwise.com/client.js"
  data-site-key="YOUR_SITE_KEY"
  data-api-url="https://api.selwise.com/api/v1"
></script>

Core Methods

widget.pushDataLayer({ event: 'page_view', page: { type: 'home', url: location.href } });

const layer = widget.getDataLayer();
console.log(layer[layer.length - 1]);

If data-layer is disabled in site config, methods stay callable and return safe no-op behavior.

React Native behavior note:

  • pushDataLayer stores local structured records for app-level state/debugging.
  • Network event ingestion in RN should use track(...) and flush().

Event Family Payload Templates

Page events

widget.pushDataLayer({
  event: 'page_view',
  page: { type: 'home', path: '/', url: location.href, title: document.title },
});

widget.pushDataLayer({
  event: 'virtual_page_view',
  page: { path: '/category/shoes', url: location.href, title: document.title },
});

Product events

widget.pushDataLayer({
  event: 'product_view',
  product: { sku: 'SKU-123', id: 'prod_123', title: 'Running Shoes', price: 149.9 },
});

widget.pushDataLayer({
  event: 'product_click',
  product: { sku: 'SKU-123', id: 'prod_123', title: 'Running Shoes' },
});

Basket/cart events

widget.pushDataLayer({
  event: 'add_to_cart',
  basket: {
    id: 'cart_001',
    currency: 'SITE_CURRENCY',
    total: 149.9,
    products: [{ sku: 'SKU-123', quantity: 1, price: 149.9 }],
  },
});

widget.pushDataLayer({
  event: 'remove_from_cart',
  basket: {
    id: 'cart_001',
    currency: 'SITE_CURRENCY',
    total: 0,
    products: [{ sku: 'SKU-123', quantity: 1, price: 149.9 }],
  },
});

Checkout / purchase events

widget.pushDataLayer({
  event: 'checkout_begin',
  checkout: { step: 1, basketId: 'cart_001', total: 149.9, currency: 'SITE_CURRENCY' },
});

widget.pushDataLayer({
  event: 'purchase',
  order: {
    id: 'ORDER-1001',
    total: 149.9,
    currency: 'SITE_CURRENCY',
    products: [{ sku: 'SKU-123', quantity: 1, price: 149.9 }],
  },
});

Search events

widget.pushDataLayer({
  event: 'search_query',
  search: { query: 'running shoes', results: 120 },
});

widget.pushDataLayer({
  event: 'search_zero_results',
  search: { query: 'nonexistent query', results: 0 },
});

User events

widget.pushDataLayer({ event: 'user_login', user: { id: 'user_42' } });
widget.pushDataLayer({ event: 'user_update', user: { id: 'user_42', email: 'u@example.com' } });

Custom events

widget.pushDataLayer({
  event: 'custom_event',
  custom: { name: 'newsletter_signup', params: { source: 'footer_form' } },
});

Validation Rules

  1. Use canonical event names only.
  2. Keep required fields for each event family.
  3. Ensure product events include stable SKU/product identifiers.
  4. Keep payload keys consistent across environments.

For complete event-by-event payload guidance:

Consent methods affect which event families are sent:

console.log(widget.getConsentState());
widget.grantConsent({ analytics: true, marketing: true });
widget.revokeConsent(['marketing']);

Troubleshooting

  1. Data-layer event appears locally but not in analytics.
  • non-canonical event name
  • missing required fields
  • consent category not granted
  1. getDataLayer() always empty.
  • runtime not initialized
  • site config disabled data-layer
  1. Duplicate SPA events.
  • multiple runtime instances in route lifecycle