Skip to content
Optima docs
SDKsJavaScript SDK

Known limitations

JavaScript SDK v1.4.0 — Known limitations

  • No dispose() teardown. There is no supported way to remove the overlay container or the modal Escape listener from the page once the SDK has installed — fine for the normal "one tag, whole page lifetime" use, awkward for a test harness or a component that mounts/unmounts the SDK repeatedly.
  • consent.set resolves before server-side durability. The local consent store updates (and is treated as authoritative) synchronously, and the returned Promise resolves once the first POST /edge/v1/consent attempt has settled. A 429/503/network failure is retried in the background on the shared ladder (5 attempts, Retry-After honoured, identical body) — so awaiting it tells you the request was made, never that the server recorded it. A final give-up surfaces as an error event (op: "consent").
  • Personalization set_attr/hide apply once. A web_personalization modification is applied when it lands (immediately, or via the MutationObserver late-match) and is not re-asserted afterwards — a client-side framework that re-renders the target element later can silently undo it.
  • CMP load order matters for Google Consent Mode. A GTM/CMP that loads and reassigns dataLayer.push after this SDK has already wrapped it wins that reassignment; the SDK stops seeing consent updates with no re-wrap polling. See "Load order" in Consent for the two workarounds (load order, or calling consent.setGCM directly).
  • Sandboxed custom code has no click feedback. A codeMode: "sandbox" item's click/stop_on_click reporting doesn't work for plain clicks (declarative data-link actions are the exception) — the SDK has no visibility into an opaque-origin iframe's DOM — and it still inherits the embedding page's CSP (a srcdoc iframe always does), so sandboxing is not a CSP remedy, only a page-access/cookie isolation choice.
  • content:blocked can be a false positive. The CSP violation watcher reports every securitypolicyviolation it can plausibly attribute to Optima; itemId: undefined means "not necessarily ours" — it can fire for a host-page CSP violation the SDK had nothing to do with.
  • data-endpoint needs setting explicitly when public_base_url carries a path. The auto-init snippet's default (the loading script's own origin) is only correct when the gateway serves the bundle from its domain root; a tenant whose Edge public_base_url includes a path segment must set data-endpoint (or endpoint in code) to that full base explicitly.
  • Playwright e2e is manual. bun run e2e (see the Development section of the SDK repository README) is not part of bun test/CI — Chromium could not be launched in this SDK's own build sandbox (missing system libraries), so it stands as documentation of expected behavior more than a gate.
  • The live integration test needs a real gateway. test/integration/ is skipped unless EDGE_URL/EDGE_KEY (and optionally EDGE_FORM_ID) point at an actually-running Optima Edge — it was never run against a live dev instance as part of this SDK's own development.