Data Layer Configuration for Spree Commerce | OpsBlu Docs

Data Layer Configuration for Spree Commerce

How to configure the GTM data layer on Spree Commerce. Covers initialization, page metadata, user properties, custom events, and ecommerce data.

For general data layer concepts, see Data Layers Explained

What the Data Layer Does

The data layer is a JavaScript array (window.dataLayer) that passes structured information from your website to Google Tag Manager. GTM reads this data and uses it to fire tags, populate variables, and send events to analytics platforms.

Initialization

Initialize the data layer before the GTM container script loads:

<script>
  window.dataLayer = window.dataLayer || [];
</script>
<!-- GTM container script follows -->

Pushing Page Data

Push page-level information on every page load so GTM tags can access it:

window.dataLayer = window.dataLayer || [];
dataLayer.push({
  'pageType': 'article',       // homepage, category, product, article, etc.
  'pageCategory': 'blog',
  'contentTitle': document.title,
  'storeCurrency': 'USD',
  'pageLanguage': document.documentElement.lang || 'en'
});

User Properties

Push user state for segmentation in analytics:

dataLayer.push({
  'userLoggedIn': true,
  'userId': 'user_12345',       // hashed or internal ID, never PII
  'userType': 'subscriber'       // anonymous, registered, subscriber, admin
});

Custom Events

Push custom events to trigger GTM tags:

// Form submission
dataLayer.push({
  'event': 'form_submit',
  'formId': 'contact-form',
  'formName': 'Contact Us'
});

// CTA click
dataLayer.push({
  'event': 'cta_click',
  'ctaText': 'Get Started',
  'ctaLocation': 'hero'
});

// File download
dataLayer.push({
  'event': 'file_download',
  'fileName': 'whitepaper.pdf',
  'fileType': 'pdf'
});

Ecommerce Data Layer

For Spree Commerce stores, push GA4 ecommerce events to the data layer:

// Product view
dataLayer.push({ ecommerce: null });  // Clear previous ecommerce data
dataLayer.push({
  'event': 'view_item',
  'ecommerce': {
    'currency': 'USD',
    'value': 29.99,
    'items': [{
      'item_id': 'SKU-123',
      'item_name': 'Product Name',
      'price': 29.99,
      'quantity': 1
    }]
  }
});

// Purchase
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'purchase',
  'ecommerce': {
    'transaction_id': 'ORDER-456',
    'value': 59.98,
    'currency': 'USD',
    'items': [{
      'item_id': 'SKU-123',
      'item_name': 'Product Name',
      'price': 29.99,
      'quantity': 2
    }]
  }
});

Important: Always push { ecommerce: null } before each ecommerce event to clear stale data from previous events.

Reading Data Layer in GTM

In GTM, create Data Layer Variables to access pushed values:

  1. Go to Variables → New → Data Layer Variable
  2. Set the variable name to match the key you pushed (e.g., pageType, userLoggedIn)
  3. Use these variables in triggers and tag configurations

Debugging

// View all data layer entries
console.table(window.dataLayer);

// Monitor new pushes in real-time
(function() {
  var original = window.dataLayer.push;
  window.dataLayer.push = function() {
    console.log('dataLayer.push:', arguments[0]);
    return original.apply(window.dataLayer, arguments);
  };
})();

Also use GTM Preview Mode (click Preview in GTM) to see data layer events in the Tag Assistant panel as you navigate your site.

Next Steps

Nach oben