Installation
JavaScript SDK v1.4.0 — Installation
Overview
The browser client for Optima Edge — behaviour tracking, visitor identification, a consent store with CMP passthrough and third-party tracker gating, a display engine for on-site content, campaign surfaces, and the consent banner, and a forms renderer for published web forms, in a single tag. Everything talks to /edge/v1/* only; there is no direct CDP or Campaign call from the browser.
Browser support: ES2020+ (evergreen browsers since 2020). No polyfills are shipped or required — fetch, Promise, optional chaining, IntersectionObserver (campaign-item impression reporting falls back to a plain dwell timer where it's unavailable) and crypto.randomUUID (with a getRandomValues fallback) are assumed.
Sizes (gzip, bun run build && bun run size): core dist/optima.js ≈ 11868 B (15 KB budget), the lazy dist/display.js chunk ≈ 11676 B (12 KB budget), the lazy dist/forms.js chunk ≈ 3304 B (10 KB budget). Only the core bundle loads on every page; display/forms load on first use.
Install
Two builds come from the same source and expose the same API.
Auto-init snippet
Drop one script tag on the page. The endpoint defaults to the script's own origin, which is correct when Optima Edge serves the bundle itself.
<script async src="https://edge.shop.example/edge/v1/sdk/v1/optima.js"
data-key="oek_shop_…"
data-endpoint="https://edge.shop.example"
data-page="auto"></script>data-* attributes: data-key (required), data-endpoint, data-page (auto|off), data-debug (true|false).
Command queue snippet
For sites that need to call the API before the bundle has loaded, use the classic stub. Every call is buffered and replayed, in order, once the real SDK installs.
<script>
window.optima = window.optima || function () { (optima.q = optima.q || []).push(arguments); };
optima("init", { key: "oek_shop_…", endpoint: "https://edge.shop.example" });
optima("track", "add_to_cart", undefined, { sku: "SHOE-42", price: 79.9 });
</script>
<script async src="https://edge.shop.example/edge/v1/sdk/v1/optima.js"></script>Every public method is callable both ways: optima('track', …) and, once loaded, optima.track(…).
npm / bundlers
npm install @optima/sdkimport { OptimaSDK, resolveConfig } from "@optima/sdk";
import type { ContentItem, NbaAction, FormDef, SubmitResult } from "@optima/sdk";
const sdk = new OptimaSDK(resolveConfig({ key: "oek_shop_…", endpoint: "https://edge.shop.example" }));
sdk.track("add_to_cart", undefined, { sku: "SHOE-42", price: 79.9 });The package ships an exports map: @optima/sdk resolves to the ESM
bundle (dist/optima.esm.js) with types at dist/index.d.ts, and
@optima/sdk/optima.js to the prebuilt IIFE bundle for a <script> tag
you host yourself. Types are generated by bun run types
(tsconfig.build.json, declarations only) and by prepublishOnly, so a
publish always carries a freshly built dist/. createDisplay /
createForms are exported too, for bundler consumers who would rather
drive their own code-splitting than pay for the runtime dynamic
import().
With a nonce-based CSP, pass display: { scriptNonce } to resolveConfig. The ESM build has no loading <script> to take the nonce from, and without it tracker placeholders are not checked against the page's nonce (see Consent-gated third-party scripts).