Configuration

The SDK is configured via window.nextConfig before the SDK script loads, and via meta tags in your HTML <head>.

Replace your-api-key-here with your actual Campaign API key from the dashboard. If you're using campaign-page-kit, run npm run config to set the API key interactively.

JavaScript Configuration

Minimal Setup

window.nextConfig = {
  apiKey: "your-api-key-here",
  storeName: "your-store-name",
};

Full Configuration Reference

window.nextConfig = {
  // Required: Your Campaign Cart API key
  apiKey: "your-api-key-here",

  // Required for Facebook purchase deduplication
  storeName: "your-store-name",

  // Currency behavior when country changes
  currencyBehavior: 'auto', // 'auto' | 'manual'

  // Payment and checkout configuration
  paymentConfig: {
    expressCheckout: {
      enabled: true,
      requireValidation: false, // Require form validation before express checkout
      requiredFields: ['email', 'fname', 'lname'],
      methodOrder: ['paypal', 'apple_pay', 'google_pay']
    }
  },

  // Address and country configuration
  addressConfig: {
    // Low-priority fallback when the campaign API returns no country list
    defaultCountry: "US",
    // Deprecated — the campaign API now provides the country list. Use as a fallback only.
    // showCountries: ["US", "CA", "GB", "AU", "DE", "FR"],
    dontShowStates: ["AS", "GU", "PR", "VI"],
    // Address autocomplete — choose one:
    // Option 1 (NextCommerce): enableAutocomplete: true, leave googleMaps.apiKey empty
    // Option 2 (Google Maps): set googleMaps.apiKey below — takes priority when non-empty
    // Option 3 (Disabled): remove enableAutocomplete and leave googleMaps.apiKey empty
    enableAutocomplete: true,
  },

  // Google Maps API key — leave empty to use NextCommerce autocomplete
  googleMaps: {
    apiKey: "",
    region: "US",
  },

  // Analytics providers
  analytics: {
    enabled: true,
    mode: 'auto', // 'auto' | 'manual' | 'disabled'
    providers: {
      nextCampaign: {
        enabled: true
      },
      gtm: {
        enabled: false,
        settings: {
          containerId: "GTM-XXXXXX",
        },
      },
      facebook: {
        enabled: false,
        settings: {
          pixelId: "YOUR_PIXEL_ID"
        },
      },
      rudderstack: {
        enabled: false,
        settings: {},
      },
      custom: {
        enabled: false,
        settings: {
          endpoint: "https://your-analytics.com/track",
          apiKey: "your-api-key"
        }
      }
    }
  },

  // UTM parameter transfer (preserve tracking params across pages)
  utmTransfer: {
    enabled: true,
    applyToExternalLinks: false,
  },

  // Optional: discount/promo codes
  // discounts: {
  //   SAVE10: { code: 'SAVE10', type: 'percentage', value: 10, scope: 'order' }
  // },

  // Optional: profiles for dynamic package mapping (e.g. exit intent pricing)
  // profiles: {
  //   SAVE_5: { name: 'Exit Save 5', packageMappings: { 1: 9, 2: 10 } }
  // },
};

Meta Tag Configuration

Configure the SDK on a per-page basis using meta tags in your HTML <head>. If you're using campaign-page-kit, these are set automatically from page frontmatter via base.html.

<!-- Campaign API Key: Optional override -->
<meta name="next-api-key" content="your-api-key-here">

<!-- Funnel Name -->
<meta name="next-funnel" content="Example Funnel">

<!-- Page Type: product, checkout, upsell, or receipt -->
<meta name="next-page-type" content="product">

<!-- Next URL: Redirect after order completion (checkout pages) -->
<meta name="next-success-url" content="/upsell">

<!-- Prevent Back Navigation: Usually on the first upsell page -->
<meta name="next-prevent-back-navigation" content="true">

<!-- Upsell URLs: For upsell pages -->
<meta name="next-upsell-accept-url" content="/receipt">
<meta name="next-upsell-decline-url" content="/receipt">

JavaScript Configuration

Minimal Setup

Full Configuration Reference

Meta Tag Configuration

On this page