Build a custom JavaScript Optimization adapter

Overview

Use this guide when you are building a JavaScript runtime or framework adapter and no official Optimization SDK package fits that surface.

Do you need this?

Quick start

Adapt this to your use case:

1
import { CoreStateful } from '@contentful/optimization-core'
2
import { OptimizedEntrySourceController } from '@contentful/optimization-core/entry-source'
3
4
const optimization = new CoreStateful({
5
  clientId,
6
  environment,
7
  locale: appLocale,
8
  contentful: {
9
    client: contentfulClient,
10
    defaultQuery: { locale: appLocale },
11
  },
12
})
13
14
const source = new OptimizedEntrySourceController()
15
16
source.setSnapshotListener((snapshot) => {
17
  if (snapshot.isLoading) {
18
    renderLoading()
19
    return
20
  }
21
22
  if (snapshot.error) {
23
    renderError(snapshot.error)
24
    return
25
  }
26
27
  if (!snapshot.baselineEntry) return
28
29
  const resolved = optimization.resolveOptimizedEntry(snapshot.baselineEntry)
30
  renderResolvedEntry(resolved.entry, resolved.selectedOptimization)
31
})
32
33
source.updateOptions({
34
  entryId: 'hero-entry',
35
  entryQuery: { locale: appLocale },
36
  sdk: optimization,
37
  isSdkStateReady: true,
38
})

Verify that the adapter renders a loading state, then renders either the selected variant or the baseline fallback for one entry.

Default recipe

Configure Core

Create the Contentful Delivery client in your application or adapter host, then pass it to Core:

1
const optimization = new CoreStateful({
2
  clientId,
3
  environment,
4
  locale: appLocale,
5
  contentful: {
6
    client: contentfulClient,
7
    defaultQuery: { locale: appLocale },
8
    cache: { maxEntries: 100, ttlMs: 300_000 },
9
  },
10
})

contentful.defaultQuery applies to every SDK-managed getEntry() and getEntries() call. Set contentful.cache: false only when the host application must own all entry caching.

Drive source controller lifecycle

Create one OptimizedEntrySourceController for each adapter instance that owns one entry source. Call updateOptions() whenever adapter inputs change:

• Pass baselineEntry when the host already fetched the entry. It takes precedence over entryId.
• Pass entryId, optional entryQuery, an SDK with fetchContentfulEntry(), and isSdkStateReady: true when the adapter wants Core-managed fetching.
• Use setSnapshotListener() to schedule renders from loading, error, or baselineEntry snapshots.
• Use getSnapshot() when the runtime needs a synchronous current value.
• Call disconnect() when the adapter unmounts or disposes.

The controller keys managed fetches by entryId + entryQuery, waits in loading state until the SDK is ready, ignores stale fetch results after source changes, and clears in-flight ownership on disconnect. createOptimizedEntryLoadingEntry(entryId) is available when a framework needs a stable placeholder Entry shape during loading.

For server prefetch, accept ManagedEntryDescriptor values and call prefetchManagedEntries(runtime, descriptors). Pass the resulting ManagedEntryHandoff[] to your browser provider under the same key your adapter uses for handoff state.

Resolve and render

The source controller only produces a baseline entry. After a snapshot contains baselineEntry, call resolveOptimizedEntry() and render the returned entry:

1
const { entry, selectedOptimization, optimizationContextId } = optimization.resolveOptimizedEntry(
2
  snapshot.baselineEntry,
3
)

Render the baseline entry when no variant resolves. Missing selections, unmatched optimization metadata, unresolved Contentful links, and out-of-range variants are fallback cases, not adapter errors.

Handle selected optimizations

Stateful Core can resolve from its current selectedOptimizations state when you omit the second argument. Emit a profile-producing event such as page() or identify() before expecting fresh personalization, and subscribe to states.selectedOptimizations when the adapter supports live updates.

Stateless Core needs request-local selections. Use a request-bound forRequest() client when available; it stores the latest accepted Experience response for that request. Root stateless callers pass explicit selectedOptimizations to resolveOptimizedEntry() or fetchOptimizedEntry().

Runtime or vendor variants

Browser adapters

For browser adapters that build on @contentful/optimization-web, prefer @contentful/optimization-web/presentation when you also need Web presentation helpers such as tracking attribute generation. For Core-only browser adapters, @contentful/optimization-core/entry-source manages only the entry source lifecycle.

After resolution, render Web tracking metadata yourself or register the element manually with optimization.tracking.enableElement(...). The entry-source controller does not emit data-ctfl-* attributes.

Core-only non-Web adapters

Non-Web adapters own their rendering and interaction model. Convert runtime view, click, hover, tap, or screen behavior into the appropriate Core event calls, and pass the resolved entry plus selectedOptimization metadata to your runtime-specific tracking layer.

One-shot server paths

Use fetchOptimizedEntry(entryId, options?) instead of the source controller when there is no mounted adapter lifecycle. It fetches the baseline entry through the configured contentful.js client, resolves immediately, and returns { baselineEntry, entry, selectedOptimization }.

Validate the integration

• Confirm the adapter renders loading and error states without tracking placeholder content as the resolved entry.
• Confirm baselineEntry takes precedence over entryId.
• Confirm entryId changes or entryQuery changes do not render stale fetch results.
• Confirm stateful adapters re-resolve when selected optimizations change, if live updates are part of the adapter contract.
• Confirm custom Web adapters render valid data-ctfl-* attributes or call tracking.enableElement(...) after resolution.

Governance notes

Use one concrete Contentful CDA locale for entries passed to Optimization resolvers. Do not use contentful.js withAllLocales or raw CDA locale=*; those responses produce locale-keyed field maps instead of the direct field values the resolver expects.

The adapter owns rendering, tracking, consent UI, route or screen events, Experience API event timing, Contentful client creation, and teardown policy. Core owns shared optimization state, events, managed entry fetching when configured, and local entry resolution.

Related documentation

• Choose the right SDK - Package selection before building a custom adapter.
• Entry optimization and variant resolution - Resolver inputs, fallback behavior, and single-locale entry constraints.
• Interaction tracking in Web SDKs - Web data-ctfl-* attributes and enableElement(...) mechanics.
• Optimization Core SDK README - Core package surface and entry-source subpath summary.