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:
| Key | Default | Meaning |
|---|---|---|
key | (required) | The edge SDK key (data-key in the auto-init snippet). |
endpoint | the loading <script>'s own origin, else location.origin | Base 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. |
spa | true | Patches 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". |
debug | false | Enables 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. |
scriptUrl | the 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>
};
}