Unified DataLayer

A multi-framework utility package for managing XP Data Layer events across different platforms, with a focus on Adobe Analytics integration.

Overview

Unified DataLayer provides a standardised way to interact with Adobe's Data Layer across different web frameworks. It offers module-based architecture for various tracking scenarios like page views, product displays, cart interactions, and more.

Features

• Framework Agnostic: Works with any JavaScript framework (React, Vue, Angular, etc.)
• Singleton Pattern: Consistent access to the data layer across your application
• Modular Design: Separate modules for different tracking scenarios
• Smart Nullification: Automatically handles data layer cleanup between events
• Standardised Formatting: Ensures consistent data structure across all events
• Built-in Validation: Comprehensive input validation with detailed error messages
• TypeScript Support: Full TypeScript definitions included

Installation

# Using npm
npm install unified-datalayer

# Using yarn
yarn add unified-datalayer

# Using bun
bun add unified-datalayer

Basic Usage

Initialisation

Initialise the data layer with your site information:

import { getDataLayer } from 'unified-datalayer';

// Get the singleton instance
const dataLayer = getDataLayer();

// Initialise with site info (required)
dataLayer.init({
  siteInfo: {
    name: 'My Store',
    experience: 'web',
    currency: 'USD',
    division: 'retail',
    domain: 'mystore.com',
    env: 'production',
    version: '1.0.0'
  }
});

Tracking Page Views

// Track homepage view
dataLayer.page.home();

// Track other page types
dataLayer.page.view('category');
dataLayer.page.view('search', 'results');

Tracking Product Display

// Track product view on PDP
const product = {
  brand: 'Brand Name',
  category: ['Footwear', 'Running'],
  child_sku: 'SKU12345',
  color: 'Blue',
  full_price: 150,
  gender: 'Men',
  listed_price: 150,
  name: 'Speed Runner 2.0',
  parent_category: 'Footwear',
  parent_sku: 'PARENT-SKU',
  sku_available: true
};

dataLayer.pdp.view(product);

// Track color selection
dataLayer.pdp.colorSelect('Red');

// Track size selection
dataLayer.pdp.sizeSelect('10');

Tracking Cart Interactions

// Track adding a product to cart
const cartProduct = {
  ...product,
  qty: 1,
  size: '10',
  sku_by_size: 'SKU12345-10'
};

dataLayer.cart.add(cartProduct);

// Track cart view
const cartItems = [
  { ...cartProduct, qty: 1 },
  { ...anotherCartProduct, qty: 2 }
];

dataLayer.cart.fullView(cartItems, { cartId: 'cart123' });

// Track cart updates
dataLayer.cart.update('SKU12345-10', 2);

// Track cart item removal
dataLayer.cart.remove('SKU12345-10');

Available Modules

Page Module

Handles tracking for general page views and navigation:

• home(): Track home page view
• view(pageType, action?): Track any page type view
• error(): Track page errors

Product Display Module (PDP)

Manages tracking for product detail pages:

• view(productData): Track product detail view
• colorSelect(color): Track color selection
• sizeSelect(size): Track size selection

Product Listing Module (PLP)

Manages tracking for product listing pages:

• view(productsArray, listName?): Track product listing view
• filter(listFilters): Track filter usage
• sort(option): Track sort option selection
• click(): Track product click (placeholder)

Cart Module

Manages tracking for cart interactions:

• add(product): Track adding product to cart
• remove(childSku): Track removing product from cart
• update(childSku, quantity): Track updating cart item quantity
• miniView(items, cartInfo): Track mini cart view
• fullView(items, cartInfo): Track full cart view
• getCartItems(): Get current cart items
• getCartInfo(): Get current cart information

Checkout Module

Manages tracking for checkout process:

• start(): Track checkout initiation
• step2(): Track checkout second step
• step3(): Track checkout third step

Account Module

Manages tracking for user account actions:

• createStart(): Track account creation start
• createComplete(): Track account creation completion
• loginStart(): Track login attempt
• loginSuccess(): Track successful login

Order Module

Manages tracking for order completion:

• success(): Track successful order completion

Wishlist Module

Manages tracking for wishlist interactions:

• view(): Track wishlist view
• add(): Track adding item to wishlist

Data Types

ProductData Interface

interface ProductData {
  brand: string;
  category: string[];
  child_sku: string;
  color: string;
  full_price: number;
  gender: string;
  listed_price: number;
  name: string;
  parent_category: string;
  parent_sku: string;
  sku_available: boolean;
  // Optional fields
  available_size?: string[];
  barcode?: string;
  feature?: string[];
  rating?: number;
  reward_points?: number;
  model?: string;
  speciality?: string;
  sport?: string;
  story?: string;
}

CartProductData Interface

interface CartProductData extends ProductData {
  qty: number;
  size: string;
  sku_by_size: string;
}

ListFilters Interface

interface ListFilters {
  filter_type: string;  // Pipe-separated: "category|price|color"
  filter_value: string; // Corresponding values: "sneakers|50-100|red,blue"
}

Advanced Configuration

Property Nullification

Configure which properties should be automatically nullified between events:

// Set properties to nullify
dataLayer.setPropertiesToNullify({
  default: ['error', 'user'],
  cart: ['cart_item_removed']
});

// Add properties to nullify 
dataLayer.addPropertiesToNullify('default', ['search']);

Error Handling

The library includes comprehensive error handling with detailed error messages.

All errors are logged to the console and requires no implementation, this is all handled internally.

State Management

Access current cart state:

// Get current cart items
const currentItems = dataLayer.cart.getCartItems();

// Get current cart info
const cartInfo = dataLayer.cart.getCartInfo();

Event Examples

Product Listing with Filters

// Track product listing view
const products = [
  {
    brand: 'Nike',
    category: ['Footwear', 'Running'],
    child_sku: 'NIKE-RUN-001',
    color: 'Black',
    full_price: 120.00,
    gender: 'Men',
    listed_price: 99.99,
    name: 'Air Max Runner',
    parent_category: 'Footwear',
    parent_sku: 'NIKE-RUN',
    sku_available: true
  }
];

dataLayer.plp.view(products, 'Running Shoes');

// Track filter application
dataLayer.plp.filter({
  filter_type: 'category|price|color',
  filter_value: 'running|50-150|black,white'
});

// Track sorting
dataLayer.plp.sort('price_ascending');

Account Creation Flow

// Track account creation start
dataLayer.account.createStart();

// After successful registration
dataLayer.account.createComplete();

// Track login attempts
dataLayer.account.loginStart();

// After successful login
dataLayer.account.loginSuccess();

Development

Prerequisites

• Bun (for building and testing)

Setup

# Clone the repository
git clone https://github.com/JordanRobo/Unified-DataLayer
cd unified-datalayer

# Install dependencies
bun install

Scripts

# Build the package
bun run build

# Generate TypeScript declarations
bun run build:types

# Run development mode with watch
bun run dev

# Run tests
bun run test

# Build and prepare for publishing
bun run prepare

Testing

The package includes a comprehensive test suite with an interactive HTML test page:

# Open test/index.html in a browser to test all functionality
# The test page includes:
# - All module testing
# - Error handling validation
# - Real-time data layer state inspection
# - Console output monitoring

Browser Compatibility

• Modern browsers with ES6+ support
• Adobe Client Data Layer integration

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request