Skip to main content

Configuration & Modes

Configure the analytics system through window.nextConfig to control tracking behavior, enable providers, and set operational modes.

Basic Configuration​

window.nextConfig = {
  apiKey: 'your-api-key',
  storeName: 'my-store',  // Important for Facebook deduplication
  analytics: {
    enabled: true,
    debug: false,
    mode: 'auto',
    providers: {
      gtm: { enabled: true },
      facebook: {
        enabled: true,
        settings: { pixelId: 'YOUR_PIXEL_ID' }
      },
      rudderstack: { enabled: true },
      custom: {
        enabled: true,
        settings: { endpoint: 'https://api.yourapp.com/analytics' }
      }
    }
  }
};

Configuration Options​

Top-Level Options​

OptionTypeDefaultDescription
enabledbooleanfalseMaster switch for all analytics tracking
debugbooleanfalseEnable detailed console logging for troubleshooting
modestring'auto'Tracking mode: 'auto' or 'manual'
providersobject{}Provider configurations (GTM, Facebook, RudderStack, custom)

Store-Level Options​

OptionTypeDescription
storeNamestringRequired for Facebook Pixel - Used for purchase deduplication

Tracking Modes​

Auto mode automatically tracks common e-commerce events without manual intervention.

analytics: {
  mode: 'auto'
}

Automatically tracked events:

EventWhenTrigger
dl_user_dataFirst event on page loadAnalytics initialization in auto mode
dl_view_item_listPage load or when products are detectedViewItemListTracker scans for elements with data-next-package-id
dl_view_itemSingle product viewWhen only one product is detected on page (via ViewItemListTracker)
dl_add_to_cartItem added to cartcart:item-added SDK event (auto-tracked via AutoEventListener)
dl_remove_from_cartItem removed from cartcart:item-removed SDK event (auto-tracked via AutoEventListener)
dl_begin_checkoutCheckout form initializesCheckoutFormEnhancer detects checkout form and cart has items
dl_add_shipping_infoShipping form submissionShipping information entered
dl_add_payment_infoPayment form submissionAfter all credit card fields are valid and complete or when the express checkout button is clicked
dl_purchaseOrder completedorder:completed SDK event (auto-tracked via AutoEventListener)
dl_viewed_upsellUpsell offer displayedupsell:viewed SDK event (auto-tracked)
dl_accepted_upsellUser accepts upsellupsell:accepted or upsell:added SDK events (auto-tracked)

Events requiring manual tracking:

  • dl_sign_up - User registration
  • dl_login - User login
  • Custom business events

Event Queue:

Events with redirects (like dl_purchase) are queued to sessionStorage and automatically fired after navigation completes.

When to use auto mode:

  • Standard e-commerce implementations
  • Minimal custom tracking requirements
  • Want to minimize code complexity
  • Need consistent tracking across pages

Manual Mode​

Full control over when and how events are tracked.

analytics: {
  mode: 'manual'
}

All events must be manually tracked using the tracking API.

When to use manual mode:

  • Need complete control over event timing
  • Custom e-commerce flows that don't match standard patterns
  • Want to track only specific events
  • Implementing custom event logic

Example manual tracking:

// View item
window.NextAnalytics.trackViewItem({ id: '123', title: 'Product', price: 99.99 });

// Add to cart
window.NextAnalytics.trackAddToCart({ id: '123', quantity: 1 });

// Begin checkout
window.NextAnalytics.trackBeginCheckout();

// Purchase
window.NextAnalytics.trackPurchase(orderData);

Provider Configuration​

Google Tag Manager​

providers: {
  gtm: {
    enabled: true,
    blockedEvents: ['dl_test_event', 'internal_event']  // Optional
  }
}

Options:

OptionTypeDescription
enabledbooleanEnable GTM integration
blockedEventsstring[]Events to exclude from GTM

Events are pushed to window.dataLayer and window.ElevarDataLayer.

See Google Tag Manager Setup for detailed configuration.

Facebook Pixel​

storeName: 'my-store',  // CRITICAL for deduplication
analytics: {
  providers: {
    facebook: {
      enabled: true,
      settings: {
        pixelId: 'YOUR_PIXEL_ID'
      },
      blockedEvents: []  // Optional
    }
  }
}

Options:

OptionTypeDescription
enabledbooleanEnable Facebook Pixel integration
settings.pixelIdstringRequired - Facebook Pixel ID
blockedEventsstring[]Events to exclude from Facebook
caution

Always set storeName in your config when using Facebook Pixel to ensure proper purchase deduplication with server-side events.

See Facebook Pixel Setup for event mapping and deduplication details.

RudderStack​

providers: {
  rudderstack: {
    enabled: true,
    blockedEvents: []  // Optional
  }
}

Options:

OptionTypeDescription
enabledbooleanEnable RudderStack integration
blockedEventsstring[]Events to exclude from RudderStack

Events are mapped to Segment specification format.

See RudderStack Setup for event mapping details.

Custom Webhook​

providers: {
  custom: {
    enabled: true,
    settings: {
      // Required
      endpoint: 'https://api.yourapp.com/analytics',

      // Optional headers
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
        'X-Store-ID': 'store-123'
      },

      // Batching settings
      batchSize: 10,           // Events per batch (default: 10)
      batchIntervalMs: 5000,   // Max time before sending (default: 5000ms)

      // Retry configuration
      maxRetries: 3,           // Retry attempts (default: 3)
      retryDelayMs: 1000,      // Initial retry delay (default: 1000ms)

      // Transform function
      transformFunction: (event) => {
        event.app_version = '1.0.0';
        return event;
      }
    },
    blockedEvents: []  // Optional
  }
}

Options:

OptionTypeDescription
enabledbooleanEnable custom webhook integration
settings.endpointstringRequired - Your webhook URL
settings.headersobjectCustom HTTP headers
settings.batchSizenumberEvents per batch (default: 10)
settings.batchIntervalMsnumberMax batch wait time (default: 5000ms)
settings.maxRetriesnumberRetry attempts on failure (default: 3)
settings.retryDelayMsnumberInitial retry delay with exponential backoff (default: 1000ms)
settings.transformFunctionfunctionTransform events before sending
blockedEventsstring[]Events to exclude from webhook

See Custom Webhook Setup for batching, retry logic, and implementation details.

Multiple Providers​

Enable all providers simultaneously - each operates independently:

providers: {
  gtm: { enabled: true },
  facebook: { enabled: true, settings: { pixelId: 'xxx' } },
  rudderstack: { enabled: true },
  custom: { enabled: true, settings: { endpoint: 'https://...' } }
}

How it works:

  • Each event sent to ALL enabled providers
  • Providers operate independently (one failure doesn't affect others)
  • Events always stored in NextDataLayer regardless of provider status
  • Debug mode shows which providers received each event

Runtime Configuration​

Enable Debug Mode​

analytics: {
  debug: true
}

Check Analytics Status​

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

// Output:
// {
//   enabled: true,
//   mode: 'auto',
//   providers: ['GTM', 'Facebook', 'RudderStack'],
//   eventsTracked: 15,
//   debugMode: false
// }

Disable Tracking Temporarily​

Add ?ignore=true to URL:

https://yoursite.com?ignore=true

This disables ALL tracking for the entire session.

To clear ignore flag:

window.NextAnalyticsClearIgnore();

Configuration Examples​

Minimal Configuration (GTM Only)​

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

E-commerce with Facebook Ads​

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

Development Configuration​

window.nextConfig = {
  apiKey: 'your-api-key',
  analytics: {
    enabled: true,
    debug: true,  // Enable debug logging
    mode: 'auto',
    providers: {
      gtm: { enabled: false },  // Disable GTM in dev
      custom: {
        enabled: true,
        settings: {
          endpoint: 'http://localhost:3000/analytics',
          headers: { 'X-Dev-Mode': 'true' }
        }
      }
    }
  }
};

Enterprise Multi-Platform Setup​

window.nextConfig = {
  apiKey: 'your-api-key',
  storeName: 'enterprise-store',
  analytics: {
    enabled: true,
    mode: 'auto',
    providers: {
      gtm: {
        enabled: true,
        blockedEvents: ['internal_test', 'dev_event']
      },
      facebook: {
        enabled: true,
        settings: { pixelId: 'PROD_PIXEL_ID' }
      },
      rudderstack: { enabled: true },
      custom: {
        enabled: true,
        settings: {
          endpoint: 'https://api.yourapp.com/analytics',
          headers: {
            'Authorization': 'Bearer YOUR_PRODUCTION_TOKEN',
            'X-Environment': 'production',
            'X-Region': 'US-WEST'
          },
          batchSize: 20,
          batchIntervalMs: 3000,
          maxRetries: 5,
          transformFunction: (event) => {
            // Add custom metadata
            event.app_version = window.APP_VERSION;
            event.environment = 'production';
            event.region = 'us-west-1';

            // Filter sensitive data
            if (event.user_properties?.customer_phone) {
              delete event.user_properties.customer_phone;
            }

            return event;
          }
        }
      }
    }
  }
};

Configuration Best Practices​

1. Always Set storeName for Facebook​

{
  storeName: 'my-store',  // Required for purchase deduplication
  analytics: {
    providers: {
      facebook: { enabled: true, settings: { pixelId: 'xxx' } }
    }
  }
}

2. Use Auto Mode for Standard Implementations​

analytics: {
  mode: 'auto'  // Handles 90% of tracking automatically
}

3. Enable Debug in Development​

analytics: {
  debug: process.env.NODE_ENV === 'development'
}

4. Block Internal Events​

providers: {
  gtm: {
    enabled: true,
    blockedEvents: ['internal_test', 'dev_event', 'debug_event']
  }
}

5. Use Transform Functions for Custom Data​

custom: {
  settings: {
    transformFunction: (event) => {
      event.custom_field = getCustomData();
      return event;
    }
  }
}
All systems normal