ConfigState

Source: global.ts:1338

Everything a page can configure about the SDK.

You write these keys on window.nextConfig before the loader script runs. Some also have a <meta name="next-*"> equivalent, and where both exist the meta tag wins, because loadFromWindow() runs first and loadFromMeta() overwrites it (core/sdk-initializer.ts › SDKInitializer.initialize).

Fields marked "the SDK fills this in" are readable at runtime but are not yours to set. Writing them on window.nextConfig has no effect.

Example

<script>
  window.nextConfig = {
    apiKey: "{YOUR_CAMPAIGN_API_KEY}",
    storeName: "acme",
    currencyBehavior: "auto",
    analytics: { enabled: true, mode: "auto", debug: false, providers: {} }
  };
</script>
<script src="/next-campaign-cart.js" type="module"></script>

Properties

apiKey: string

The campaign API key every request authenticates with.

Also settable as <meta name="next-api-key">, which wins over this value. An empty string means the SDK never found a key, so no prices load and no order can be placed.

A leftover meta tag silently overriding the key here is the usual cause of a page loading the wrong campaign. Check the markup before anything else.

Example

"{YOUR_CAMPAIGN_API_KEY}"

campaignId: string

A campaign identifier shown in the debug panel.

Nothing in the SDK sends it: requests identify the campaign from ConfigState.apiKey alone. Setting it does not point the page at a different campaign.

Default: ```ts "" (not supplied) ```

Example

"winter-sale"

debug: boolean

Turns on verbose SDK logging in the browser console.

Also turned on by <meta name="next-debug" content="true"> or ?debugger=true in the URL. Leave it off for shopper traffic.

Default: ```ts false ```

Example

true

debugger: boolean | undefined

Opens the on-page debug overlay at boot.

The overlay also reads ?debugger=true and window.nextConfig.debugger directly, so changing this value after boot does not open or close it.

Default: ```ts false ```

Example

true

pageType: PageType

Which stage of the funnel this page is.

Analytics reports it as page_type, so a mislabelled page files its events under the wrong funnel step. Prefer the meta tag, which wins over this value.

Example

"checkout"

• See:
  • PageType

storeName: string

The store identifier used to deduplicate purchases against a server-side copy of the same order.

Required by the NEXT Storefront Meta App: with it set, the Meta event carries eventID: "{storeName}-{orderNumber}". Leave it unset and browser and server events count the same order twice.

Example

"acme"

spreedlyEnvironmentKey: string

The key that authorises the hosted credit-card fields.

undefined means the card fields cannot start, so card payment is unavailable and only express or pay-later methods work. Once the campaign loads its own payment_env_key overwrites whatever was set here, so check the campaign response before the page markup when the card fields use an unexpected key.

paymentConfig: PaymentConfig

Express checkout and card field behaviour.

Accepted on window.nextConfig as either paymentConfig or payment.

Example

paymentConfig: {
  expressCheckout: {
    enabled: true,
    methodOrder: ["paypal", "apple_pay", "google_pay"]
  }
}

• See:
  • PaymentConfig

googleMapsConfig: GoogleMapsConfig

Google Maps address autocomplete settings.

Written as googleMaps on window.nextConfig. Leave apiKey empty to use the NEXT autocomplete instead; a non-empty key takes priority over it.

Example

googleMaps: { apiKey: "{GOOGLE_MAPS_API_KEY}", region: "US" }

• See:
  • GoogleMapsConfig

addressConfig: AddressConfig

How the checkout address form behaves.

Example

addressConfig: { dontShowStates: ["AS", "GU", "PR", "VI"], enableAutocomplete: true }

• See:
  • AddressConfig

detectedCountry: string

The visitor's country, as geo-detected at boot. The SDK fills this in.

detectedCurrency: string

The currency geo-detection chose for the visitor. The SDK fills this in.

detectedIp: string

The visitor's IP address, from geo-detection. The SDK fills this in.

selectedCurrency: string

The currency the visitor is actually being charged in, held for the whole session. The SDK fills this in from ?currency=, a stored session value, or geo-detection, in that order.

locationData: any

The raw geo-detection response. The SDK fills this in.

currencyBehavior: 'auto' | 'manual'

Whether the SDK may change currency when the visitor's country changes.

"auto" geo-detects on first load when no ?currency= parameter and no stored currency exist, then locks that currency for the session. "manual" never auto-detects and falls back to the campaign default.

Default: ```ts "auto" ```

Example

"manual"

currencyFallbackOccurred: boolean

Whether the requested currency was unavailable and a fallback was used. The SDK fills this in.

storageScope: string

Keeps two campaigns on one domain from sharing a cart.

The SDK derives a scope from the API key and the folder the page is served from, so you do not normally set this. Reach for it when a funnel's pages sit at different depths (/hu/ and /hu/checkout), which derives two scopes and loses the cart between them. Pages that must share a cart declare the same value; pages that must not declare different ones.

Also settable as <meta name="next-storage-scope">. Unlike every other key here, this value wins over the meta tag. It is read while the storage modules are created, so it must be set before the loader script runs.

Default: ```ts undefined (derived from the API key and page path) ```

Example

"hu-earbuds"

locale: string

BCP 47 tag that pins how prices are written — "de-DE", "fr-FR", "en-US".

The locale, not the currency code, decides the decimal separator and which side the symbol sits on: the same EUR amount is €69.99 under en-US and 69,99 € under de-DE. Set this when a store must render the same way for every visitor.

Leave it unset and the visitor's own browser locale is used, which is usually what you want — a German shopper already sees 69,99 €. Pin it only when the store's format must not follow the browser.

An unparseable tag ("de_DE" with an underscore is the common typo) is rejected with a warning and the browser locale is used instead, so a bad value never breaks prices.

Default: ```ts undefined (use the browser's locale) ```

Example

"de-DE"

autoInit: boolean | undefined

rateLimit: number | undefined

cacheTtl: number | undefined

retryAttempts: number | undefined

timeout: number | undefined

testMode: boolean | undefined

maxRetries: number | undefined

requestTimeout: number | undefined

enableAnalytics: boolean | undefined

enableDebugMode: boolean | undefined

environment: 'production' | 'development' | 'staging' | undefined

version: string

buildTimestamp: string

discounts: Record<string, DiscountDefinition>

utmTransfer: { enabled: boolean; applyToExternalLinks?: boolean; excludedDomains?: string[]; paramsToCopy?: string[] }

Properties

• enabled (boolean)
• applyToExternalLinks (boolean, optional)
• excludedDomains (string[], optional)
• paramsToCopy (string[], optional)

tracking: 'auto' | 'manual' | 'disabled'

analytics: { enabled: boolean; mode: 'auto' | 'manual' | 'disabled'; debug: boolean; providers: { gtm: { enabled: boolean; settings: { containerId?: string; dataLayerName?: string; environment?: string } }; facebook: { enabled: boolean; settings: { pixelId: string; accessToken?: string; testEventCode?: string }; blockedEvents?: string[] }; custom: { enabled: boolean; settings: { endpoint: string; apiKey?: string; batchSize?: number; timeout?: number } } } }

Properties

• enabled (boolean)
• mode ("auto" | "manual" | "disabled")
• debug (boolean)
• providers ({ gtm: { enabled: boolean; settings: { containerId?: string; dataLayerName?: string; environment?: string } }; facebook: { enabled: boolean; settings: { pixelId: string; accessToken?: string; testEventCode?: string }; blockedEvents?: string[] }; custom: { enabled: boolean; settings: { endpoint: string; apiKey?: string; batchSize?: number; timeout?: number } } })

clearCartOnInit: boolean