Analytics Overview

Track e-commerce events across Google Analytics 4, Facebook Pixel, RudderStack, and custom platforms.

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.

How It Works

1. Events Are Tracked

The SDK captures e-commerce events using two APIs:

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

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

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.

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',

  campaign_id: '42',
  campaign_name: 'Summer Campaign',
  campaign_currency: 'USD',
  campaign_language: 'en',
  campaign_session_id: 'ncsid_abc123', // Campaigns session-tracking ID

  user_properties: {
    visitor_type: 'guest',
    customer_email: 'user@example.com',
    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: 'session_abc123', // SDK analytics session ID
    sequence_number: 2,
    source: 'next-campaign-cart',
    version: '0.2.0'
  }
}

campaign_session_id comes from Campaigns session tracking and connects activity to Campaigns App reporting. _metadata.session_id is generated by the SDK for event ordering and browser-session correlation. They are separate identifiers; the RudderStack adapter uses the SDK identifier for its cart_id and checkout_id values.

Campaign Context

The SDK adds campaign context to every analytics event when that data is available. This makes it possible to segment events by campaign and join provider data back to Campaigns App sessions and order attribution.

Set the campaign API key before the SDK loads so it can retrieve the campaign record and populate these fields:

window.nextConfig = {
  apiKey: 'your-api-key'
};

See Campaigns configuration for the complete setup. If the key is missing, analytics logs a console warning and emits events without the campaign ID, name, currency, or language. The session-tracking ID remains available when the ncsid cookie is present.

Testing & Verification

Enable Debug Mode

analytics: {
  debug: true
}

// 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 Examples 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

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);