Integrate the Optimization React Web SDK in a React app

Overview

Use this guide to add Contentful personalization to a client-side React app you already have — a single-page app built with Vite, Create React App, React Router, or a similar setup. By the end of the quick start, one piece of content will render its personalized variant in the browser once the SDK resolves it, without changing how your app fetches or renders content.

New to personalization? Here is the whole idea in four points:

• In Contentful you author variants of an entry and attach them to an experience — a rule that decides which visitors see which variant.
• As the visitor uses your app, Contentful’s Experience API looks at who they are and picks the variant for each experience. Swapping a fetched entry for its picked variant is called resolving the entry.
• Your app hands a Contentful entry to the SDK at the point where that entry becomes output. The SDK gives back the selected variant, or the original entry when no variant applies—the baseline fallback. You can fetch the entry yourself or give the SDK your Contentful client and an entry ID; either way, the client stays yours.
• You render the returned entry with the same application components you already use.

That is enough to start. The guide introduces policy and optional capabilities at the point you need them.

You will get there in two milestones:

• Milestone 1 — a personalized entry in the client render (the quick start below). After the SDK resolves, a visitor sees their variant on screen. This is complete and shippable on its own.
• Milestone 2 — live re-personalization (opt-in, later). Content re-resolves when consent, identity, or profile changes, without a full reload. See Live updates.

This guide uses @contentful/optimization-react-web, which wraps the lower-level @contentful/optimization-web browser SDK in React providers, hooks, and an entry-rendering component. You configure it by passing props to one OptimizationRoot component you mount once — there is no separate factory call. Your app keeps ownership of the Contentful client, consent policy, identity, routing, and rendering.

Because this SDK runs entirely in the browser, there is no server-rendered first paint: the SDK becomes ready after React mounts, so loading and error states are a first-class part of the integration, not an afterthought. If your app renders on the server (Next.js), use the Next.js App Router guide or the Next.js Pages Router guide instead; if your app is not React-based, or you want to own the browser SDK lifecycle without React abstractions, use the Web SDK guide.

Quick start

Most React + Contentful apps share one shape: you fetch an entry (a page, a hero, a section) and render its fields through your own components. This quick start assumes that shape and personalizes a single entry. In the snippets that change an existing file, lines prefixed with + are what you add and the rest is a typical app for context — match the additions to your own file rather than pasting the whole block. If your app is shaped differently, the change is the same wherever an entry becomes a component; see Resolving entries and rendering the result.

It proves one result: one entry renders its personalized variant in the browser once the SDK resolves it. Because the SDK is not ready synchronously, the entry shows a brief loading state first, then reveals the resolved content — that is expected, not a bug. This quick start assumes your app may personalize on startup; if personalization must wait for consent, keep this structure and add the Consent and privacy handoff step before you ship.

1. Install the package. Add contentful too — a companion dependency you install alongside the SDK — if your app does not already have a Contentful Delivery API client.

   Copy this:

   1
   pnpm add @contentful/optimization-react-web contentful

2. Mount OptimizationRoot once, around every component that will use the SDK. Pass your Optimization project config as props. Use the same environment-variable convention your app already uses for browser-visible values (this example uses Vite’s import.meta.env with a PUBLIC_ prefix; adjust to your bundler).

   defaults is the SDK’s starting browser state (consent, persistence, and similar). Inside it, consent: true tells the SDK it may personalize and send events for this visitor; the quick start uses always-on consent to keep the path simple — production gates this on the visitor’s choice (see Consent and privacy handoff).

   Adapt this to your use case: wrap your existing app tree; replace the placeholder env-var names with yours. The config keys are explained in How the SDK fits your app.

   1
   // src/App.tsx (or wherever your app root lives)
   2
   +import { OptimizationRoot } from '@contentful/optimization-react-web'
   3
   4
    export function App() {
   5
      return (
   6
   +    <OptimizationRoot
   7
   +      clientId={import.meta.env.PUBLIC_OPTIMIZATION_CLIENT_ID}
   8
   +      environment={import.meta.env.PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main'}
   9
   +      locale="en-US" // the one locale you also pass to Contentful
   10
   +      // consent: allowed to personalize and send events for this visitor.
   11
   +      defaults={{ consent: true }}
   12
   +    >
   13
         <HomePage /> 
   14
   +    </OptimizationRoot>
   15
      )
   16
    }

3. Fetch one Contentful entry and render it through OptimizedEntry. OptimizedEntry takes the entry you fetched as baselineEntry and calls your render prop with the resolved entry — the variant when one applies, or the baseline entry otherwise. While the SDK is still resolving, OptimizedEntry shows the baseline as a hidden loading target and reveals the result once resolution settles.

   Adapt this to your use case: this is your page component. Your fetch, your Contentful client, and your markup stay yours; the pattern to copy is the fetch-in-effect and the OptimizedEntry wrap.

   1
   // src/HomePage.tsx
   2
   import { OptimizedEntry, useOptimizationContext } from '@contentful/optimization-react-web'
   3
   import { createClient, type Entry } from 'contentful'
   4
   import { useEffect, useState } from 'react'
   5
   6
   const contentfulClient = createClient({
   7
     accessToken: import.meta.env.PUBLIC_CONTENTFUL_TOKEN,
   8
     environment: import.meta.env.PUBLIC_CONTENTFUL_ENVIRONMENT ?? 'main',
   9
     space: import.meta.env.PUBLIC_CONTENTFUL_SPACE_ID,
   10
   })
   11
   12
   export function HomePage() {
   13
     // useOptimizationContext() surfaces `error` if SDK init fails — guard on it so a failure does not render broken UI.
   14
     const { error } = useOptimizationContext()
   15
     const [entry, setEntry] = useState<Entry | undefined>()
   16
   17
     useEffect(() => {
   18
       void contentfulClient
   19
         .getEntry(import.meta.env.PUBLIC_HERO_ENTRY_ID, {
   20
           include: 10, // resolve linked experience and variant entries before rendering
   21
           locale: 'en-US', // one concrete locale — never withAllLocales / locale=*
   22
         })
   23
         .then(setEntry)
   24
     }, [])
   25
   26
     if (error) return <p>Personalization failed to load.</p>
   27
     if (!entry) return <p>Loading…</p>
   28
   29
     return (
   30
       <OptimizedEntry baselineEntry={entry}>
   31
         {/* Render prop hands back a base contentful `Entry`; cast to your own type. Replace
   32
             `YourEntryType` with your own entry type, or drop the cast and use the base `Entry`. */}
   33
         {(resolved) => <h1>{String((resolved as YourEntryType).fields.title ?? '')}</h1>}
   34
       </OptimizedEntry>
   35
     )
   36
   }

4. Check that it works. In Contentful, author a variant on the entry you fetch above and attach it to an experience — for a first test, target all visitors so you match it automatically. Load the app: you should see a brief loading state, then the variant’s text render in place of the baseline. If the baseline text stays on screen, work through Troubleshooting.

You now have personalization working. The rest of this guide is not a re-run of the quick start — it explains what each step did and covers what the quick start deliberately skipped: real, consent-gated startup; the SDK readiness and loading model; your Contentful fetch requirements and the baseline-fallback contract; page events and route tracking; interaction tracking; identity; live updates; and production hardening. Read straight through, or jump to the section you need.

Before you start

The sections below walk the integration in order. First, gather the few things you can only get from outside this guide:

• A React app (18.3 or newer) with React and React DOM installed, and its own Contentful fetching already working. contentful is a companion dependency you install alongside the SDK if you do not already have a Delivery API client.
• Contentful delivery credentials — space ID, delivery token, and environment.
• At least one entry with a variant attached to an experience, authored in Contentful. Without an authored variant, the integration can still run correctly while returning the baseline, so you cannot yet distinguish working personalization from a content-authoring gap. For the first personalized-content test, target all visitors so the test request or visitor matches automatically.
• Your Optimization project values — client ID and environment, from your Optimization project settings. The Experience and Insights API base URLs default correctly; you only set them for mocks or non-default hosts (see How the SDK fits your app).

You do not need a setup inventory up front. Everything else — consent, page events, tracking, identity, live updates — is introduced by the section that needs it.

Core integration

How the SDK fits your app

Integration category: Required for first integration

This section explains the OptimizationRoot you mounted in the quick start — what each prop does and how to make startup depend on real consent.

OptimizationRoot is the single React entry point. It composes the OptimizationProvider and LiveUpdatesProvider for you, creates the underlying Web SDK instance after React commits, and destroys that instance on unmount. You configure the SDK by passing props directly to this component, and you mount it exactly once around the subtree that uses the SDK.

The props you pass break down like this:

1. clientId and environment identify your Optimization project. Read them from browser-safe env variables.
2. locale is the one locale the SDK uses for Experience and event context. Use the same locale you pass to Contentful.
3. defaults is the browser SDK’s starting state: consent (may personalize and send events) and persistenceConsent (may store the profile-id cookie — the anonymous identifier the SDK assigns each visitor to keep their variant assignments consistent across visits).
4. api overrides the Experience and Insights endpoints (experienceBaseUrl, insightsBaseUrl). Set these only for a mock, a proxy, or non-default hosts; omit them otherwise.
5. app is your app’s name and version, sent as metadata.
6. contentful opts into managed entry fetching by handing the SDK your Contentful client (contentful: { client, defaultQuery?, cache? }); leave it unset to fetch entries yourself. See Fetching Contentful entries.
7. liveUpdates, trackEntryInteraction, and onStatesReady are optional and covered in their own sections below.

The quick start used always-on defaults to get you a result. For production, make startup depend on real consent: leave consent unset (or seed it off) and call setConsent(true) from the UI that owns the visitor’s decision, as shown in Consent and privacy handoff.

The only import path you need to start is the package root, @contentful/optimization-react-web. Other subpaths cover specific needs you reach for later:

Adapt this to your use case: the root with app metadata and API overrides, the way a real app configures it.

1
import { OptimizationRoot } from '@contentful/optimization-react-web'
2
import type { ReactNode } from 'react'
3
4
export function AppRoot({ children }: { children: ReactNode }) {
5
  return (
6
    <OptimizationRoot
7
      clientId={import.meta.env.PUBLIC_OPTIMIZATION_CLIENT_ID}
8
      environment={import.meta.env.PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main'}
9
      locale="en-US"
10
      app={{ name: 'my-react-app', version: '1.0.0' }}
11
      // Set these only for mocks or non-default hosts; both default correctly otherwise.
12
      api={{
13
        experienceBaseUrl: import.meta.env.PUBLIC_EXPERIENCE_API_BASE_URL,
14
        insightsBaseUrl: import.meta.env.PUBLIC_INSIGHTS_API_BASE_URL,
15
      }}
16
      logLevel="warn"
17
    >
18
      {children}
19
    </OptimizationRoot>
20
  )
21
}

Mount OptimizationRoot exactly once. Mounting a second owned instance in the same browser runtime throws ContentfulOptimization is already initialized. Do not nest OptimizationProvider inside OptimizationRoot: the root already composes the provider and live-updates provider. If you need direct provider control, use OptimizationProvider instead of OptimizationRoot; nesting an injected provider shadows the root context, including prefetched managed entries.

SDK readiness, loading, and error states

Integration category: Required for first integration

This is the concept that has no equivalent in the server-rendered guides, so it is worth stating plainly. Because the SDK runs only in the browser, it is not ready on the first render. It is created after React commits, then it asks the Experience API who the visitor is. Two consequences follow, and both surface through hooks you already saw in the quick start:

• Reading the SDK instance. useOptimizationContext() returns { sdk, error }. sdk is defined from the first render (the provider seeds a read-only snapshot so hooks never crash), and error is set only if initialization fails. Guard on error to render a fallback, as the quick start does. Use useOptimization() instead when a component needs the SDK instance directly and can assume it is present — it throws if the SDK is unavailable, so it belongs below OptimizationRoot in code that runs after mount (event handlers, effects).
• Reading an entry’s resolution state. OptimizedEntry handles its own loading: while it waits for the Experience API outcome, it renders the baseline entry as a hidden layout target so the page does not jump, then reveals the resolved content when resolution settles. If resolution never settles, it reveals the baseline after a 5-second timeout so the UI never hangs. Pass loadingFallback to show custom loading UI during that window instead.

Your own Contentful fetch is a separate concern from SDK readiness — you can start it in an effect on mount. The important rule is only about entry resolution: an entry with optimization references stays in its loading state until the Experience request settles, which is why you see a brief loading state before the variant appears.

1. Render an app-level fallback when useOptimizationContext().error is set — personalization is unavailable, but decide whether the rest of your app should still render.
2. Let OptimizedEntry own per-entry loading; add loadingFallback only where you want custom UI.
3. Do not block your whole app waiting for optimization state. Entries without optimization references render immediately after SDK initialization.

Follow this pattern: an app-level error fallback plus per-entry loading UI.

1
import { OptimizedEntry, useOptimizationContext } from '@contentful/optimization-react-web'
2
import type { Entry } from 'contentful'
3
4
function Hero({ baselineEntry }: { baselineEntry: Entry }) {
5
  const { error } = useOptimizationContext()
6
  if (error) return <StaticHero entry={baselineEntry} /> // degrade to non-personalized UI
7
8
  return (
9
    <OptimizedEntry baselineEntry={baselineEntry} loadingFallback={() => <HeroSkeleton />}>
10
      {(resolved) => <StaticHero entry={resolved as YourEntryType} />}
11
    </OptimizedEntry>
12
  )
13
}

For components that need loading and readiness metadata directly — for example to disable a control until optimizations are available — use useOptimizedEntry(), which returns { entry, isLoading, canOptimize, selectedOptimization, … } for one baseline entry.

Fetching Contentful entries

Integration category: Required for first integration

Your app always owns the Contentful client. There are two supported ways to get a fetched entry to the point where the SDK resolves it, and you can mix them per entry:

• Manual (the quick start’s path). Your code calls the Contentful client itself and passes the result to OptimizedEntry as baselineEntry. Your fetching, caching, and response shaping stay entirely yours; the SDK only needs the entry to arrive in a shape it can resolve.
• Managed (opt-in). You hand the SDK your Contentful client once via contentful: { client } on OptimizationRoot, and then reference entries by id — <OptimizedEntry entryId="…">. The SDK fetches through your client’s getEntry() and getEntries() methods and resolves the result. This trades a little control for less wiring per entry; see Resolving entries and rendering the result for the managed component variant.

If you are just starting or want full control over fetching, stay on the manual path; switch to managed when you would rather the SDK make the getEntry() call than write per-component fetch code.

Both paths obey the same fetch rules, because the SDK resolves the same single-locale entry shape either way:

1. Fetch with one concrete Contentful locale. Do not use withAllLocales or raw Contentful Delivery API (CDA) locale=* — all-locale payloads use locale-keyed field maps the resolver cannot read, so entries fall back to baseline.
2. Use an include depth deep enough to resolve the whole tree — the entry, its sections, and the linked variant entries. include: 10 is the common setting. In the managed path the SDK applies include: 10 for you, and you can still override per call with entryQuery.
3. Pass the same locale to Contentful and to OptimizationRoot so localized Experience responses and rendered content line up. In the managed path the SDK falls back to the OptimizationRoot locale when your query does not set one.

A single-locale entry exposes its optimization fields directly, such as fields.nt_experiences and fields.nt_variants (the nt_ prefix is how personalization links appear on an entry).

Copy this: the manual fetcher from the quick start. fetchPageEntry is your own helper — name it whatever fits your app.

1
import { createClient } from 'contentful'
2
3
const APP_LOCALE = 'en-US'
4
const INCLUDE_DEPTH = 10
5
6
const contentfulClient = createClient({
7
  accessToken: import.meta.env.PUBLIC_CONTENTFUL_TOKEN,
8
  environment: import.meta.env.PUBLIC_CONTENTFUL_ENVIRONMENT ?? 'main',
9
  space: import.meta.env.PUBLIC_CONTENTFUL_SPACE_ID,
10
})
11
12
export async function fetchPageEntry(entryId: string) {
13
  return await contentfulClient.getEntry(entryId, {
14
    include: INCLUDE_DEPTH, // resolve linked experience and variant entries before rendering
15
    locale: APP_LOCALE, // keep this aligned with the OptimizationRoot locale
16
  })
17
}

To use the managed path instead, pass that same client to OptimizationRoot and let the SDK fetch. The contentful prop is SDK-owned; client is your app-owned Contentful client.

Adapt this to your use case: enable managed fetching on the root you already mount. The + line is the only addition; the rest is the root from the quick start.

1
 <OptimizationRoot
2
   clientId={import.meta.env.PUBLIC_OPTIMIZATION_CLIENT_ID}
3
   environment={import.meta.env.PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main'}
4
   locale="en-US"
5
   defaults={{ consent: true }}
6
+  // Hand the SDK your Contentful client so `<OptimizedEntry entryId>` can fetch by id.
7
+  // `defaultQuery` is merged into every managed getEntry() call; cache is per-instance
8
+  // ({ maxEntries: 100, ttlMs: 300_000 } by default, or `cache: false` to disable).
9
+  contentful={{ client: contentfulClient, defaultQuery: { locale: 'en-US' } }}
10
 >
11
   {/* your app */}
12
 </OptimizationRoot>

If your app changes locale at runtime, OptimizationRoot updates the SDK’s Experience and event locale when its locale prop changes. On the manual path you still refetch Contentful entries and re-emit page events yourself; on the managed path a changed entryId/entryQuery refetches, but you still re-emit page events yourself. For the full model, see Locale handling in the Optimization SDK Suite.

Resolving entries and rendering the result

Integration category: Required for first integration

Step 3 showed the wrap. This explains the two things about it that matter everywhere. The rule never changes: wherever a Contentful entry becomes a component, wrap it in OptimizedEntry and render whatever the render prop hands back.

• Type of the resolved entry. The render prop’s first argument is typed as a base contentful Entry. If your component expects a narrower type, cast it — resolved as YourEntryType — which mirrors the reference implementation. This direct cast works for the common cases, including .withoutUnresolvableLinks-narrowed types. Only if TypeScript rejects a cast for a genuinely disjoint type do you need resolved as unknown as YourEntryType.
• Fallback contract. When consent is denied, no variant applies, links are unresolved, or the payload was all-locale, the render prop simply receives the baseline entry. Your UI never breaks; it falls back to default content — this is why the quick start renders correctly even before you author a variant.

The quick start wrapped an entry directly in a page. The other common shape is a renderer or registry that maps a content type to a component; wrapping it there personalizes every entry it renders. The wrap and the cast are identical.

Adapt this to your use case: a content-type-to-component renderer (yours may be named differently). The + lines are the additions; keep your existing guards.

1
// e.g. your renderer that maps a content type to a component
2
+import { OptimizedEntry } from '@contentful/optimization-react-web'
3
4
 export function ContentRenderer({ items }) {
5
   return items?.map((entry) => {
6
     const Component = entry ? componentFor(entry.sys.contentType.sys.id) : undefined
7
     if (!entry || !Component) return null // your existing guard stays
8
-    return <Component key={entry.sys.id} entry={entry} />
9
+    return (
10
+      <OptimizedEntry key={entry.sys.id} baselineEntry={entry}>
11
+        {(resolved) => <Component entry={resolved as YourEntryType} />}
12
+      </OptimizedEntry>
13
+    )
14
   })
15
 }

OptimizedEntry must render under an ancestor that handles useOptimizationContext().error (as the readiness section shows). On an SDK initialization failure it throws rather than rendering baseline, so an unguarded subtree crashes.

The managed alternative to baselineEntry. If you enabled managed fetching with contentful: { client } (see Fetching Contentful entries), you can pass entryId instead of fetching yourself. The two entry sources are mutually exclusive: an OptimizedEntry takes either baselineEntry (manual — you fetched it) or entryId (managed — the SDK fetches it), never both. With entryId, the SDK fetches through your client while the component shows its loading state, then resolves and reveals exactly as the manual path does. Two props exist only for the managed path, since only it can fail while fetching:

• errorFallback — what to render if the managed fetch fails. It is a node or (error: Error) => ReactNode; return undefined to render nothing.
• onEntryError — a (error: Error) => void callback for logging or reporting the fetch failure.

Adapt this to your use case: the managed variant of the same wrap. entryQuery is optional and overrides the merged managed query per call.

1
import { OptimizedEntry } from '@contentful/optimization-react-web'
2
3
export function HomeHero() {
4
  return (
5
    <OptimizedEntry
6
      entryId={import.meta.env.PUBLIC_HERO_ENTRY_ID} // SDK fetches this id through your client
7
      entryQuery={{ locale: 'en-US' }} // optional per-call override; merged with the managed query
8
      loadingFallback={() => <HeroSkeleton />}
9
      errorFallback={(error) => <StaticHero error={error} />} // managed-fetch failure only
10
      onEntryError={(error) => diagnostics.logEntryFetchError(error)}
11
    >
12
      {(resolved) => <StaticHero entry={resolved as YourEntryType} />}
13
    </OptimizedEntry>
14
  )
15
}

The render prop, the cast, and the baseline-fallback contract are identical to the manual path; only the entry source and the two managed-failure props differ.

Two more facts hold everywhere:

• Do not double-wrap the same entry. A nested OptimizedEntry that shares a baseline entry id with an OptimizedEntry above it renders nothing (it returns null, with a dev-only warning). Wrap at one level — the renderer hand-off, or the individual cards, not both. Nested wrappers with different baseline ids are fine.
• OptimizedEntry wraps content in a layout-neutral element with display: contents by default, so it does not affect layout. Use the as prop when the wrapper must be a specific element; it accepts only 'div' or 'span' (default 'div'), so it cannot be an arbitrary element such as 'section'. It also accepts plain node children when the markup does not need the resolved entry; the wrapper still resolves metadata and emits tracking attributes.

For the resolver contract, see Entry personalization and variant resolution.

Page events and route tracking

Integration category: Required for first integration

A page event signals that a page or route was viewed. The Experience API uses page events to evaluate route-based experiences, so most integrations emit one on first load and on every route change. React Web ships auto page trackers for common routers; each dedupes consecutive route keys, including React Strict Mode’s double effects.

1. Mount one tracker inside OptimizationRoot and inside the router context it reads. Use the tracker that matches your router.
2. Use pagePayload for static fields and getPagePayload for fields derived from the route context. Router-derived payload, static pagePayload, and dynamic getPagePayload are deep-merged in that order; later values win on key conflicts.
3. For an app with no supported router, call trackPageView() from useOptimizationActions() in your own route-change effect.

Most React SPAs use React Router, so this guide uses ReactRouterAutoPageTracker. (The next-pages and next-app trackers exist for React-Web-only Next.js setups; a full Next.js integration should use the dedicated Next.js SDK guides instead.)

Adapt this to your use case: the tracker mounted once in your router root.

1
import { OptimizationRoot } from '@contentful/optimization-react-web'
2
import { ReactRouterAutoPageTracker } from '@contentful/optimization-react-web/router/react-router'
3
import { createBrowserRouter, Outlet, RouterProvider } from 'react-router-dom'
4
5
function RootLayout() {
6
  return (
7
    <OptimizationRoot clientId={import.meta.env.PUBLIC_OPTIMIZATION_CLIENT_ID}>
8
      {/* One tracker per router tree — more than one emits duplicate route page events. */}
9
      <ReactRouterAutoPageTracker />
10
      <Outlet />
11
    </OptimizationRoot>
12
  )
13
}
14
15
const router = createBrowserRouter([
16
  { path: '/', element: <RootLayout />, children: [{ index: true, element: <HomePage /> }] },
17
])
18
19
export function App() {
20
  return <RouterProvider router={router} />
21
}

To attach route-aware properties, pass getPagePayload:

Follow this pattern:

1
<ReactRouterAutoPageTracker
2
  getPagePayload={({ context }) => ({
3
    properties: { appSection: context.pathname.startsWith('/account') ? 'account' : 'public' },
4
  })}
5
/>

The next-pages and next-app trackers also accept initialPageEvent="skip" for setups where a server path already emitted the first page event. In a browser-only React SPA you emit the first page event yourself, so leave it at the default ("emit").

Consent and privacy handoff

Integration category: Common but policy-dependent

Consent policy belongs to your application. The SDK tracks two independent axes: consent (may personalize and send events) and persistenceConsent (may store the profile-id cookie). Until consent is set, the SDK permits only identify and page events; other events stay blocked.

1. If policy permits personalization by default, seed accepted consent in defaults during setup (as the quick start does).
2. If policy depends on user choice, leave consent unset and call setConsent(true | false) from the banner, Consent Management Platform (CMP) callback, or settings screen that owns the decision.
3. Use object-form consent — setConsent({ events: true, persistence: false }) — only when events and durable profile continuity have different policy decisions. A boolean sets both together.
4. Persist the visitor’s choice in your own store (a cookie, localStorage, or account preference) so your UI can restore it on the next visit. That consent record is yours — you name, write, and read it. The SDK does not manage it; it only reflects what you pass to setConsent().

Adapt this to your use case: a consent control wired to the SDK actions and to your own consent record.

1
import { useConsentState, useOptimizationActions } from '@contentful/optimization-react-web'
2
import { useEffect } from 'react'
3
4
// This cookie is YOURS: your app writes and reads it. It is not an SDK cookie.
5
const CONSENT_COOKIE = 'app-personalization-consent'
6
7
function persistConsent(consented: boolean): void {
8
  document.cookie = `${CONSENT_COOKIE}=${consented ? 'granted' : 'denied'}; Path=/; SameSite=Lax`
9
}
10
11
export function ConsentControls() {
12
  const consent = useConsentState() // boolean | undefined
13
  const { setConsent } = useOptimizationActions()
14
15
  useEffect(() => {
16
    if (typeof consent === 'boolean') persistConsent(consent)
17
  }, [consent])
18
19
  return (
20
    <button onClick={() => setConsent(consent !== true)} type="button">
21
      {consent === true ? 'Reject personalization' : 'Accept personalization'}
22
    </button>
23
  )
24
}

The SDK stores its own consent, persistence-consent, and profile-continuity state in browser storage; the browser-readable profile-id cookie is named ctfl-opt-aid and is the one persistence value the SDK owns and manages. If storage writes fail, the SDK continues with in-memory state. For the cross-SDK policy model, see Consent management in the Optimization SDK Suite.

Entry interaction tracking

Integration category: Common but policy-dependent

Interaction tracking — views, clicks, and hovers on entries — is a browser behavior. OptimizedEntry renders the tracking metadata the SDK needs, and the SDK observes interactions once consent permits. It is on by default when you use OptimizedEntry, so you rarely configure anything to get started.

1. Leave the defaults on when your consent policy allows them. Use the trackEntryInteraction prop on OptimizationRoot only to opt out of an interaction type you must not observe.
2. Use OptimizedEntry props — clickable, trackViews, trackClicks, trackHovers, and the duration-interval props — for per-entry control.
3. Page and identify events can be sent before full consent, but entry views, clicks, and hovers stay blocked until consent (or allowedEventTypes) permits them.

Tracking uses the resolved entry id, not the baseline id.

Follow this pattern: opting one detector out globally, plus a per-entry override.

1
<OptimizationRoot clientId={clientId} trackEntryInteraction={{ hovers: false }}>
2
  <OptimizedEntry baselineEntry={entry} clickable trackViews>
3
    {(resolved) => <HeroCard entry={resolved as YourEntryType} />}
4
  </OptimizedEntry>
5
</OptimizationRoot>

For DOM that automatic observation cannot reach, resolve metadata with useOptimizedEntry() and call sdk.tracking.enableElement('views', element, { data: … }) from an effect, clearing it with sdk.tracking.clearElement(...) on unmount so recycled nodes do not keep stale entry data. For detector behavior and data attributes, see Interaction tracking in Web SDKs.

Identity, profile, and reset

Integration category: Common but policy-dependent

Identify a visitor only when your app knows who they are or has policy-approved traits to send. Reset profile state when the active visitor changes or logs out.

1. Call identifyUser() from the account, session, or profile event that owns the identity decision.
2. Render SDK state with dedicated hooks such as useProfileState() and useSelectedOptimizationsState().
3. Call resetUser() when identity changes must clear profile, selected optimizations, and route dedupe state. Consent state is preserved; clear your own consent record separately if withdrawal also ends consent.
4. Re-emit trackPageView() or identifyUser() after a reset when the app needs fresh optimization state.

Adapt this to your use case: an account panel wired to the SDK actions.

1
import {
2
  useOptimizationActions,
3
  useProfileState,
4
  useSelectedOptimizationsState,
5
} from '@contentful/optimization-react-web'
6
7
export function AccountState() {
8
  const { identifyUser, resetUser } = useOptimizationActions()
9
  const profile = useProfileState()
10
  const selectedOptimizations = useSelectedOptimizationsState()
11
  const isIdentified = Boolean(profile?.traits.identified)
12
13
  return (
14
    <div>
15
      <span>Profile: {profile?.id ?? 'anonymous'}</span>
16
      <span>Optimizations: {selectedOptimizations?.length ?? 0}</span>
17
      {isIdentified ? (
18
        <button onClick={() => resetUser()} type="button">
19
          Reset profile
20
        </button>
21
      ) : (
22
        <button
23
          onClick={() => void identifyUser({ userId: 'user-123', traits: { identified: true } })}
24
          type="button"
25
        >
26
          Identify
27
        </button>
28
      )}
29
    </div>
30
  )
31
}

With live updates enabled, identifyUser(), setConsent(), and resetUser() can change selected variants and re-render affected entries without a reload. For cross-runtime identity behavior, see Profile synchronization between client and server.

Optional integrations

Live updates

Integration category: Optional

This is Milestone 2. First render is already complete and shippable; add live updates only when some content must re-personalize after it first resolves — for example when a visitor accepts consent, signs in, or is identified, and entries should update without a reload.

Live updates are opt-in because most content is fixed once resolved. You do not add a provider — the bound OptimizationRoot already includes the live-updates provider internally. You only choose the scope:

1. App-wide default: set liveUpdates on OptimizationRoot. Every entry without its own override re-resolves on state changes.
2. Per-entry: pass liveUpdates on a specific OptimizedEntry to opt one entry in (liveUpdates) or out (liveUpdates={false}), independent of the app-wide default.
3. The preview panel forces live updates while it is open, regardless of these settings.

The effective precedence is: preview panel open, then the per-entry liveUpdates prop, then the root liveUpdates prop, then the default (locked to the first resolved state).

Follow this pattern: the app-wide switch plus per-entry overrides.

1
// globalLiveUpdates is your own boolean (a state value or setting) — true turns live updates on app-wide.
2
<OptimizationRoot clientId={clientId} liveUpdates={globalLiveUpdates}>
3
  <OptimizedEntry baselineEntry={entry}>
4
    {(resolved) => <InheritsGlobalSetting entry={resolved as YourEntryType} />}
5
  </OptimizedEntry>
6
7
  <OptimizedEntry baselineEntry={entry} liveUpdates>
8
    {(resolved) => <AlwaysLive entry={resolved as YourEntryType} />}
9
  </OptimizedEntry>
10
11
  <OptimizedEntry baselineEntry={entry} liveUpdates={false}>
12
    {(resolved) => <LockedAfterFirstResolution entry={resolved as YourEntryType} />}
13
  </OptimizedEntry>
14
</OptimizationRoot>

To verify, enable live updates, then trigger identifyUser(), setConsent(), or resetUser(). Live entries re-resolve without a full reload; entries with liveUpdates={false} stay put until the next render.

Merge tags and Custom Flags

Integration category: Optional

Use merge tags when Contentful Rich Text contains embedded profile-backed values (a personalized greeting, a location). Use Custom Flags when app UI branches on a named flag rather than an optimized entry.

1. Inside an OptimizedEntry, read getMergeTagValue from the render prop’s second argument and pass it into your Rich Text renderer.
2. Use useMergeTagResolver() only when you resolve merge tags outside an OptimizedEntry render prop.
3. Merge tags live inside Rich Text as embedded entry nodes, so getMergeTagValue takes a merge-tag entry node. Guard each embedded entry with isMergeTagEntry (from /api-schemas) before resolving it.
4. For flags, read optimization.getFlag(name) for a nonreactive read, or subscribe to optimization.states.flag(name) when UI must re-render as the flag changes. Reading a flag can emit flag-view tracking when consent allows it.

Follow this pattern: resolving merge tags while rendering Rich Text.

1
import { OptimizedEntry } from '@contentful/optimization-react-web'
2
import { isMergeTagEntry } from '@contentful/optimization-react-web/api-schemas'
3
import { documentToReactComponents, type Options } from '@contentful/rich-text-react-renderer'
4
import { INLINES } from '@contentful/rich-text-types'
5
import type { Entry } from 'contentful'
6
7
export function EntryWithMergeTags({ entry }: { entry: Entry }) {
8
  return (
9
    <OptimizedEntry baselineEntry={entry}>
10
      {(resolved, { getMergeTagValue }) => {
11
        const options: Options = {
12
          renderNode: {
13
            [INLINES.EMBEDDED_ENTRY]: (node) => {
14
              const target = node.data.target
15
              // Only merge-tag nodes resolve to a profile value; render others as usual.
16
              return isMergeTagEntry(target) ? (getMergeTagValue(target) ?? '') : null
17
            },
18
          },
19
        }
20
        return documentToReactComponents(resolved.fields.body as never, options)
21
      }}
22
    </OptimizedEntry>
23
  )
24
}

Merge tags and entry replacement use different mechanics: entry replacement swaps the whole entry for its variant; merge tags read profile-backed values from current SDK state. Keep the SDK locale aligned with the rendered Contentful locale when merge tags reference localized profile fields.

Analytics forwarding

Integration category: Optional

Use analytics forwarding when your app needs to send approved Optimization context to a tag manager, customer-data platform, or analytics destination. The SDK still sends its own events to Contentful; forwarding is application-owned.

1. Register the subscription with the onStatesReady prop so it attaches before child effects (such as route trackers) emit events.
2. Dedupe forwarded events by messageId. To receive only future events, read the current messageId before subscribing and skip it.
3. Store forwarded message ids in module or app state so remounts do not forward the same event again.
4. Gate forwarding with the same consent and destination policy that governs the rest of your analytics stack.

Follow this pattern:

1
const forwardedMessageIds = new Set<string>()
2
3
<OptimizationRoot
4
  clientId={clientId}
5
  onStatesReady={(states) => {
6
    // Subscribe before child effects, such as route trackers, emit events.
7
    const initialMessageId = states.eventStream.current?.messageId
8
9
    const subscription = states.eventStream.subscribe((event) => {
10
      if (!event) return
11
      if (forwardedMessageIds.has(event.messageId)) return
12
      if (event.messageId === initialMessageId) {
13
        forwardedMessageIds.add(event.messageId)
14
        return
15
      }
16
      if (!canForwardSdkEvent(event)) return // your own consent/destination filter
17
18
      forwardedMessageIds.add(event.messageId)
19
      // pickContentfulEventProperties is your own property mapper.
20
      analytics.track(`Contentful ${event.type}`, pickContentfulEventProperties(event))
21
    })
22
23
    return () => subscription.unsubscribe()
24
  }}
25
>
26
  <ReactRouterAutoPageTracker />
27
  <YourApp />
28
</OptimizationRoot>

For diagnostics on events the SDK blocks by consent or allowedEventTypes, also subscribe to states.blockedEventStream. For vendor mappings, consent boundaries, and dedupe guidance, see Forwarding Optimization SDK context to analytics and tag-management tools.

Preview panel

Integration category: Optional

The preview panel is a separate browser package for authoring and staging workflows — including forcing a specific variant to verify a targeted experience. It appends a panel to document.body and talks to the Web SDK through the browser preview bridge.

1. Install @contentful/optimization-web-preview-panel.
2. Gate the dynamic import behind an environment variable so production bundles can drop it.
3. Attach it after the SDK exists. The onStatesReady prop is a good attach point.
4. Pass an app-owned Contentful client, or pre-fetched preview entries, to the attach function.

Adapt this to your use case:

1
import { createScopedLogger } from '@contentful/optimization-react-web/logger'
2
import { OptimizationRoot } from '@contentful/optimization-react-web'
3
4
const previewPanelLogger = createScopedLogger('PreviewPanel')
5
6
function attachPreviewPanel(): void {
7
  // Keep preview code behind an environment gate so production bundles can remove it.
8
  if (import.meta.env.PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL !== 'true') return
9
10
  void import('@contentful/optimization-web-preview-panel')
11
    .then(async ({ default: attachOptimizationPreviewPanel }) => {
12
      // contentfulClient — your existing Contentful CDA client, imported from wherever you define it.
13
      await attachOptimizationPreviewPanel({ contentful: contentfulClient })
14
    })
15
    .catch((error: unknown) => {
16
      previewPanelLogger.warn('Failed to attach the preview panel.', error)
17
    })
18
}
19
20
export function App() {
21
  return (
22
    <OptimizationRoot clientId={clientId} onStatesReady={attachPreviewPanel}>
23
      <YourApp />
24
    </OptimizationRoot>
25
  )
26
}

By default the attach function uses window.contentfulOptimization, which the provider creates in the browser. If your app injects its own SDK instance, pass optimization to the attach function. If you already load preview definitions (through GraphQL, a loader, or a proxy), pass entries: { audiences, experiences } instead of contentful. Verify with live updates enabled, because the panel forces optimized entries to react to preview state.

Advanced integrations

Owning the Web SDK instance

Integration category: Advanced or production-only

Use OptimizationProvider directly when an application or framework adapter must create and own the Web SDK instance outside React.

1. Create the Web SDK instance yourself with @contentful/optimization-web.
2. Pass it through OptimizationProvider sdk={optimization}.
3. Wrap children in LiveUpdatesProvider if any component uses OptimizedEntry, useOptimizedEntry, or useLiveUpdates. OptimizationRoot does this for you; when you compose the providers yourself, you add it explicitly.
4. Destroy the injected instance in the owner that created it — the provider does not call destroy() on instances it did not create.

Use this as an alternative to OptimizationRoot, not as a child of it. OptimizationRoot already includes OptimizationProvider, and a nested provider creates a separate context for its subtree.

Adapt this to your use case:

1
import ContentfulOptimization from '@contentful/optimization-web'
2
import { LiveUpdatesProvider, OptimizationProvider } from '@contentful/optimization-react-web'
3
4
const optimization = new ContentfulOptimization({ clientId: 'your-client-id', environment: 'main' })
5
6
function App() {
7
  return (
8
    <OptimizationProvider sdk={optimization}>
9
      <LiveUpdatesProvider>
10
        <YourApp />
11
      </LiveUpdatesProvider>
12
    </OptimizationProvider>
13
  )
14
}

The provider always renders its children — they are never withheld or unmounted. When you pass serverOptimizationState, children render against a read-only snapshot until the live SDK state is applied in a layout effect. With an injected sdk and no serverOptimizationState, children render against the live injected SDK from the first render; onStatesReady alone does not add a snapshot phase.

Prefetching managed entries for a server handoff. When a managed (entryId) OptimizedEntry renders on a server before the browser SDK is live, you can hand it its baseline entry so it renders resolved content immediately instead of a loading state. The package root exports the symbols for this: prefetchManagedEntries(runtime, descriptors) returns a ManagedEntryHandoff[] you pass to the prefetchedManagedEntries prop on OptimizationRoot (or OptimizationProvider), keyed by entryId + entryQuery. descriptors are ManagedEntryDescriptor values ('entry-id' or { entryId, entryQuery? }); runtime is any ManagedEntryPrefetchRuntime — an object exposing prefetchManagedEntries(descriptors). Core uses getEntries() for multiple uncached descriptors with the same normalized query, split into 100-ID chunks for large fetches. This SDK ships no server runtime of its own, so you supply that runtime yourself. For a full server-rendered integration with request-scoped state and page-event handoff, use the Next.js App Router guide or Next.js Pages Router guide, which own that path end to end.

Strict consent, storage, and delivery controls

Integration category: Advanced or production-only

Configure these only after your privacy, analytics, and platform owners agree on the event posture.

1. Set allowedEventTypes={[]} on OptimizationRoot when no Optimization event may emit before explicit consent. (The default allows identify and page.)
2. Use cookie when the profile-id cookie needs a specific domain or expiration.
3. Use queuePolicy when the default retry and offline-queue behavior does not match your limits.
4. Use onEventBlocked (and states.blockedEventStream) for diagnostics when consent or allowedEventTypes block events.

Follow this pattern:

1
<OptimizationRoot
2
  clientId={clientId}
3
  allowedEventTypes={[]} // block all Optimization events until consent is accepted
4
  cookie={{ domain: '.example.com', expires: 180 }}
5
  queuePolicy={{ offlineMaxEvents: 100 }}
6
  onEventBlocked={(event) => diagnostics.logBlockedOptimizationEvent(event)}
7
>
8
  <YourApp />
9
</OptimizationRoot>

Blocked events are not replayed when consent later changes. If the current route, flag, or entry state still qualifies after consent, the SDK can emit a fresh current-state event.

Production checks

Run these checks before release:

• Confirm clientId, environment, locale, api endpoints, app metadata, and log level point to the intended environment, and that browser-exposed env variables contain only values safe to ship.
• Confirm Contentful fetches use one concrete locale with a deep enough include, and never pass withAllLocales / locale=* payloads to OptimizedEntry or the resolver hooks.
• Confirm default-on vs opt-in startup matches policy, allowedEventTypes matches the pre-consent posture, and revoking consent blocks non-allowed events.
• Confirm the first page event and route-change page events deliver, that one tracker is mounted per router tree, and that Strict Mode remounts do not duplicate them.
• Confirm baseline fallback renders when the Experience API fails, variants are missing, links are unresolved, or a payload is all-locale — and that OptimizedEntry stops showing loading after resolution settles or the 5-second reveal.
• If you use managed fetching (contentful: { client } with <OptimizedEntry entryId>), confirm a failed managed fetch renders your errorFallback and reaches onEntryError, and that the managed query still uses one concrete locale with a deep enough include.
• Confirm identifyUser(), setConsent(), and resetUser() re-resolve only the entries configured for live updates, and that reset runs when identity changes.
• Confirm entry views, clicks, hovers, flag views, page events, and forwarded analytics deliver only when policy permits, that forwarding dedupes by messageId, and that manual element tracking clears overrides on unmount.
• Confirm preview-panel code is environment-gated out of production bundles unless release policy allows it.
• Run the local validation path below.

Copy this:

1
pnpm implementation:run -- react-web-sdk typecheck
2
pnpm implementation:run -- react-web-sdk build
3
pnpm test:e2e:react-web-sdk

Troubleshooting

Reference implementations to compare against

• React Web SDK reference implementation: Working React SPA using OptimizationRoot, ReactRouterAutoPageTracker, OptimizedEntry, the SDK-ready fetch pattern, live updates, merge tags, automatic and manual entry tracking, an event-stream display, consent and identity controls, and environment-gated preview-panel attachment.
• Custom React adapter over the Web SDK: Builds a custom React adapter on top of @contentful/optimization-web for comparison when an app needs full control instead of the official React Web SDK surface.