Skip to content
Optima docs
SDKsJavaScript SDK

Configuration

JavaScript SDK v1.4.0 — Configuration

optima.init(cfg) (command-queue form) or the resolveConfig/OptimaSDK constructor (bundler form). Every key of Config (src/config.ts), its default, and what it does:

KeyDefaultMeaning
key(required)The edge SDK key (data-key in the auto-init snippet).
endpointthe loading <script>'s own origin, else location.originBase URL for every /edge/v1/* call.
page"auto""auto" fires page() on load and SPA navigation; "off" disables automatic page views (call page() yourself) — it does not disable the automatic content refresh on navigation, which spa alone governs.
spatruePatches pushState/replaceState/listens to popstate to detect SPA navigations. Installed regardless of page: a navigation always refreshes content (URL-targeted), and additionally fires page() when page: "auto".
debugfalseEnables console.info/console.warn logging ([optima] ...) for internal events that are otherwise silent.
cookieDomain(unset — current host only)Sets the Domain attribute on the _optima_did/_optima_consent cookies, so the device id survives subdomain hops. Every subdomain under it can then set the visitor's device id — only use it when all of them are yours.
scriptUrlthe loading <script>'s own src, when known (IIFE build only)Internal — resolved automatically from the <script> tag so the lazy display/forms chunks can be found next to wherever optima.js actually loaded from. Not meant to be hand-set.
consent.beforeDecision"buffer""buffer" queues hits AND identify() calls until a consent decision exists (identify calls are held in memory only — at most 10, dropped after 30 min or on page unload); "send" sends immediately without declaring purposes until the visitor decides.
consent.source"optima""optima" treats the SDK's own store as the declaration. "cmp" hands the conversation to an external CMP: the SDK's own purposes are never declared (only the tcf/gcm/keys carriers), a served banner_consent item is emitted as content:item but never rendered, and beforeDecision is forced to "send". See Consent, CMP passthrough, and Global Privacy Control.
consent.gpcDenies[]Purposes recorded false (and sent to /edge/v1/consent once) when navigator.globalPrivacyControl === true and no decision exists yet for that purpose. Does not mark the visitor decided.
display.codeMode"inline""inline" re-creates <script> tags with full page access; "sandbox" renders in a zero-chrome allow-scripts iframe. See Custom code run and the trust model.
display.hideUntilReady(unset — off){ selector: string; timeout_ms: number } (default timeout_ms when set: 1500) — anti-flicker: hides selector until the first content.refresh() settles or the timeout fires.
display.scriptNonce(the loading <script>'s nonce, IIFE build)CSP nonce applied to every re-created <script> tag and required on every text/plain tracker placeholder (see Consent-gated third-party scripts).
display.styleNonce(unset)CSP nonce applied to the overlay layer's and anti-flicker's injected <style> tags.
{
  key: string;                 // required, the edge SDK key
  endpoint?: string;            // defaults to the loading script's own origin
  page?: "auto" | "off";        // default "auto"
  spa?: boolean;                 // default true — patches history for SPA page views
  debug?: boolean;
  cookieDomain?: string;
  consent?: {
    beforeDecision?: "buffer" | "send"; // default "buffer"
    source?: "optima" | "cmp";           // default "optima"
    gpcDenies?: string[];                // default []
  };
  display?: {
    codeMode?: "inline" | "sandbox";     // default "inline"
    hideUntilReady?: { selector: string; timeout_ms: number }; // default: off
    scriptNonce?: string;                 // CSP nonce: stamped on re-created <script>s, required on tracker placeholders; defaults to the loading script's nonce
    styleNonce?: string;                  // CSP nonce for the overlay's/anti-flicker's injected <style>
  };
}