Contentful Personalization & Analytics

Optimization Web SDK

This SDK implements browser-specific optimization behavior on top of the Optimization Core SDK. Use it directly for non-React browser applications, framework adapters, and client-side runtimes that need consent state, anonymous ID persistence, automatic entry interaction tracking, and browser-side event delivery.

If you are integrating a browser application, start with Getting Started, then use Integrating the Optimization Web SDK in a web app for the step-by-step flow. This README keeps the package orientation and common setup options close at hand; generated reference documentation remains the source of truth for exported API signatures.

Getting started

Install using an NPM-compatible package manager, pnpm for example:

pnpm install @contentful/optimization-web
Copy

Import the Optimization class; both CJS and ESM module systems are supported, ESM preferred:

import ContentfulOptimization from '@contentful/optimization-web'
Copy

Configure and initialize the Optimization Web SDK once per page runtime:

const optimization = new ContentfulOptimization({
  clientId: 'your-client-id',
  environment: 'main',
})
Copy

Usage in vanilla JS web pages

The UMD build is available for HTML pages that do not use a bundler:

<script src="https://cdn.jsdelivr.net/npm/@contentful/optimization-web@latest/dist/contentful-optimization-web.umd.js"></script>
<script>
  window.contentfulOptimization = new ContentfulOptimization({
    clientId: 'your-client-id',
    environment: 'main',
  })
</script>
Copy

When to use this package

Use @contentful/optimization-web for browser applications that need the stateful Web runtime directly, including consent state, anonymous ID persistence, automatic entry interaction tracking, and browser-side event delivery.

We recommend starting React applications with @contentful/optimization-react-web, which wraps this SDK with React providers, hooks, router adapters, and entry-rendering primitives.

Common configuration

The Web SDK communicates with the Experience API for profile and optimization selection, and with the Insights API for event ingestion.

Common api options:

Common fetchOptions are fetchMethod, requestTimeout, retries, intervalTimeout, onFailedAttempt, and onRequestTimeout. Default retries intentionally apply only to HTTP 503 responses.

For every option, callback payload, and exported type, use the generated Web SDK reference.

Core workflows

Consent and profile events

Consent is application policy. The SDK stores the consent state and blocks non-allowed events until consent is accepted.

optimization.consent(true)

const data = await optimization.page({
  properties: { path: window.location.pathname },
})
Copy

page(), identify(), screen(), track(), and sticky trackView() calls can return optimization data containing profile, selectedOptimizations, and changes.

Content resolution

Fetch Contentful entries in your application layer, then use the SDK to resolve the selected variant:

const optimizationData = await optimization.page({ properties: { path: location.pathname } })
const resolvedEntry = optimization.resolveOptimizedEntry(
  baselineEntry,
  optimizationData?.selectedOptimizations,
)
Copy

Use getMergeTagValue() for Contentful Rich Text merge tags and getFlag() for Custom Flags. The Web SDK is stateful, so reading a flag also emits flag-view tracking.

Entry interaction tracking

Enable automatic tracking when entry elements follow the standard data-attribute pattern:

const optimization = new ContentfulOptimization({
  clientId: 'your-client-id',
  autoTrackEntryInteraction: { views: true, clicks: true, hovers: false },
})
Copy

Use manual element overrides when the DOM structure does not fit automatic observation:

optimization.tracking.enableElement('views', element, {
  data: {
    componentId: 'entry-id',
    experienceId: 'experience-id',
    variantIndex: 0,
  },
})
Copy

For detection thresholds, data attributes, click and hover behavior, and manual overrides, use the Web SDK integration guide.

State subscriptions

The stateful Web SDK exposes observable state for UI feedback and integration glue:

const unsubscribe = optimization.states.profile.subscribe((profile) => {
  console.log(profile?.id)
})
Copy

Common state streams include consent, profile, selectedOptimizations, changes, blockedEventStream, eventStream, and preview-panel state. Use the generated reference for the complete states surface.

Runtime notes

• Browser storage persistence is best-effort. If localStorage writes fail, the SDK continues with in-memory state and retries persistence on subsequent writes.
• reset() clears internal state except consent. Use it when the active profile changes.
• flush() drains queued Insights API and Experience API events.
• destroy() releases listeners and singleton ownership for explicit teardown paths such as tests or hot-reload workflows.
• Lifecycle interceptors exist for first-party SDK and preview-panel integration. Most application code does not need them directly.

Related

• Integrating the Optimization Web SDK in a web app - step-by-step browser integration guide
• Web SDK generated reference - exported API reference
• React Web SDK - React provider, hook, router, and OptimizedEntry layer built on this SDK
• Web Vanilla reference implementation - static Web page using the vanilla JS drop-in build
• Web SDK React Adapter reference implementation - React application that builds a local adapter layer directly on top of this SDK