Skip to content
Optima docs
SDKsJavaScript SDK

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/sdk
import { 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).

On this page