Analytics Overview

The SDK tracks e-commerce events and sends them to analytics providers.

Supported Providers

• Google Tag Manager
• Facebook Pixel
• RudderStack
• Custom webhooks

Events follow GA4 specification and can be tracked automatically or manually using two APIs: next.* methods or window.NextAnalytics.

Quick Start

Enable analytics with minimal configuration:

window.nextConfig = {
  apiKey: 'your-api-key',
  analytics: {
    enabled: true,
    mode: 'auto',
    providers: {
      gtm: { enabled: true }
    }
  }
};

That’s it! The SDK now automatically tracks:

• User data on every page load
• Product list views on collection pages
• Add to cart events
• Checkout initiation
• Shipping and payment info

How It Works

1. Events Are Tracked

The SDK captures e-commerce events using two APIs:

Simple API

// Simple tracking methods
next.trackAddToCart(packageId, quantity);
next.trackViewItem(packageId);
next.trackBeginCheckout();
next.trackPurchase(orderData);

Works immediately, handles async loading automatically.

Advanced API

// Advanced tracking with full control
window.NextAnalytics.trackAddToCart(item, listId, listName);
window.NextAnalytics.trackViewItem(item);
window.NextAnalytics.track({ event: 'custom_event', data: '...' });

Direct access to analytics engine with advanced features.

2. Events Are Stored

All events are stored in three data layers:

• window.NextDataLayer - SDK’s primary analytics store
• window.dataLayer - Standard Google Tag Manager layer
• window.ElevarDataLayer - Elevar-compatible format

3. Events Are Sent

Events are automatically sent to all enabled providers:

providers: {
  gtm: { enabled: true },                    // → Google Tag Manager
  facebook: { enabled: true, settings: {} }, // → Facebook Pixel
  rudderstack: { enabled: true },            // → RudderStack
  custom: { enabled: true, settings: {} }    // → Your backend
}

Each provider operates independently - if one fails, others continue working.

Tracking Modes

Auto Mode (Recommended)

Automatically tracks common e-commerce events:

analytics: {
  mode: 'auto'
}

Automatically tracked:

• dl_user_data - Page load, route changes
• dl_view_item_list - Product list views
• dl_view_item - Single product pages, selected items in selectors
• dl_add_to_cart - Cart additions
• dl_begin_checkout - Checkout start
• dl_add_shipping_info - Shipping form submission
• dl_add_payment_info - Payment form submission
• dl_purchase - Order completion

Requires manual tracking:

• dl_login / dl_sign_up - User authentication
• Custom business events

Event Queue for Redirects:

Purchase events are queued to sessionStorage before page redirect and automatically fired on the confirmation page. This ensures events aren’t lost during navigation.

Manual Mode

Full control over all event tracking:

analytics: {
  mode: 'manual'
}

You must manually track ALL events using API methods.

Common Use Cases

Standard E-commerce with GTM

window.nextConfig = {
  apiKey: 'your-api-key',
  analytics: {
    enabled: true,
    mode: 'auto',
    providers: {
      gtm: { enabled: true }
    }
  }
};

// Purchase events tracked automatically in auto mode
// No manual tracking required

E-commerce with Facebook Ads

window.nextConfig = {
  apiKey: 'your-api-key',
  storeName: 'my-store',  // Required for Facebook deduplication
  analytics: {
    enabled: true,
    mode: 'auto',
    providers: {
      gtm: { enabled: true },
      facebook: {
        enabled: true,
        settings: { pixelId: 'YOUR_PIXEL_ID' }
      }
    }
  }
};

Multi-Platform Pipeline

analytics: {
  enabled: true,
  mode: 'auto',
  providers: {
    gtm: { enabled: true },
    facebook: { enabled: true, settings: { pixelId: 'xxx' } },
    rudderstack: { enabled: true },
    custom: {
      enabled: true,
      settings: { endpoint: 'https://api.yourapp.com/events' }
    }
  }
}

Event Data Structure

All events follow GA4-compliant format:

{
  event: 'dl_add_to_cart',
  event_id: 'sess_123_2_1234567890',
  event_time: '2025-01-12T10:30:00Z',

  user_properties: {
    visitor_type: 'guest',
    customer_email: '[email protected]',
    customer_id: 'user_123'
  },

  ecommerce: {
    currency: 'USD',
    value: 99.99,
    items: [{
      item_id: 'SKU-123',
      item_name: 'Product Name',
      price: 99.99,
      quantity: 1
    }]
  },

  attribution: {
    utm_source: 'google',
    utm_medium: 'cpc',
    funnel: 'main'
  },

  _metadata: {
    session_id: 'sess_abc123',
    sequence_number: 2,
    source: 'next-campaign-cart',
    version: '0.2.0'
  }
}

Testing & Verification

Enable Debug Mode

Configuration

analytics: {
  debug: true
}

Runtime

// Enable at runtime
window.NextAnalytics.setDebugMode(true);

// Check status
const status = window.NextAnalytics.getStatus();
console.log(status);

Disable Tracking Temporarily

https://yoursite.com?ignore=true

This disables ALL tracking for the entire session.

To clear:

window.NextAnalyticsClearIgnore();

Verify Events

// Check all data layers
console.log(window.NextDataLayer);
console.log(window.dataLayer);  // GTM
console.log(window.ElevarDataLayer);  // Elevar

// Get analytics status
const status = window.NextAnalytics.getStatus();
console.log('Events tracked:', status.eventsTracked);
console.log('Providers:', status.providers);

Next Steps

1. Configure providers - Set up GTM, Facebook Pixel, or other platforms

   See Providers Overview

2. Learn tracking methods - Understand the tracking API

   See Tracking API Reference

3. Review events - See all standard e-commerce events

   See Event Reference

4. Advanced tracking - Create custom events and use transform functions

   See Custom Events

Documentation Structure

• Configuration & Modes - Detailed configuration options
• Tracking API Reference - Complete API documentation
• Providers - Provider-specific setup guides
• Event Reference - Complete event schemas and examples
• Custom Events - Advanced tracking patterns
• Debugging - Troubleshooting and testing
• Best Practices - Implementation patterns and tips

FAQ

Do I need to call next.init()?

No! Analytics initializes automatically when the SDK loads. Just configure window.nextConfig.

What’s the difference between the three data layers?

• window.dataLayer - Standard GTM data layer
• window.NextDataLayer - SDK’s primary analytics store (all events)
• window.ElevarDataLayer - Elevar-compatible format for GTM integrations

Can I track events before SDK loads?

Yes, use the nextReady queue:

window.nextReady = window.nextReady || [];
window.nextReady.push(function() {
  next.trackAddToCart('123', 1);
});

What happens if a provider fails?

The SDK handles failures gracefully:

• Events still track to NextDataLayer
• Other providers continue working
• Warnings logged in debug mode
• SDK functionality unaffected

How do I check if analytics is working?

// Check status
window.NextAnalytics.getStatus();

// Check events
window.NextDataLayer;

// Enable debug
window.NextAnalytics.setDebugMode(true);