Skip to content

README.md

Latest commit

 

History

History
220 lines (167 loc) · 10.1 KB

README.md

File metadata and controls

220 lines (167 loc) · 10.1 KB

Contentful Logo

Contentful Personalization & Analytics

Optimization React Web SDK

Warning

The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.

The Optimization React Web SDK provides React providers, hooks, router adapters, and entry-rendering primitives on top of the Optimization Web SDK. Use it when a React browser application must not manage the lower-level Web SDK instance, state subscriptions, entry resolution, and route tracking by hand.

If you are integrating a React application, start with Getting Started, then use Integrating the Optimization React Web SDK in a React 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.

Table of Contents

Getting started

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

pnpm install @contentful/optimization-react-web

Mount OptimizationRoot once near the root of your React application:

import { OptimizationRoot } from '@contentful/optimization-react-web'

function App() {
  return (
    <OptimizationRoot clientId="your-client-id" environment="main">
      <YourApp />
    </OptimizationRoot>
  )
}

When to use this package

Use @contentful/optimization-react-web for React browser applications that need provider-based SDK initialization, hooks, router page tracking, optimized entry rendering, automatic interaction tracking, and live update semantics. Use the lower-level Web SDK directly for non-React integrations or custom framework adapters.

Common configuration

OptimizationRoot accepts the Web SDK configuration props directly and adds a React-specific liveUpdates prop.

Prop Required? Default Description
clientId Yes N/A Shared API key for Experience API and Insights API requests
environment No 'main' Contentful environment identifier
api No Web SDK defaults Experience API and Insights API endpoint and request options
app No undefined Application metadata attached to outgoing event context
defaults No undefined Initial state, commonly including consent or profile values
allowedEventTypes No ['identify', 'page'] Event types allowed before consent is explicitly set
autoTrackEntryInteraction No { views: false, clicks: false, hovers: false } Automatic entry interaction tracking inherited from the Web SDK
cookie No { domain: undefined, expires: 365 } Anonymous ID cookie settings inherited from the Web SDK
liveUpdates No false Whether OptimizedEntry components react continuously to SDK state
queuePolicy No SDK defaults Flush retry behavior and offline queue bounds
logLevel No 'error' Minimum log level for the default console sink
onEventBlocked No undefined Callback invoked when consent or guard logic blocks an event

Use OptimizationProvider directly only when an application or framework adapter must own a pre-built SDK instance:

<OptimizationProvider sdk={optimization}>
  <YourApp />
</OptimizationProvider>

For every Web SDK option that passes through this package, use the Web SDK README and generated reference documentation.

Core workflows

Provider and hook access

OptimizationRoot creates and tears down the Web SDK instance. Use useOptimization() when a component needs direct access to the instance:

import { useOptimization } from '@contentful/optimization-react-web'

function ConsentButton() {
  const { sdk } = useOptimization()
  return <button onClick={() => sdk?.consent(true)}>Accept</button>
}

OptimizedEntry

OptimizedEntry resolves a baseline Contentful entry and renders either the selected variant or the baseline entry:

import { OptimizedEntry } from '@contentful/optimization-react-web'

function HeroEntry({ baselineEntry }) {
  return (
    <OptimizedEntry baselineEntry={baselineEntry}>
      {(resolvedEntry) => <HeroCard entry={resolvedEntry} />}
    </OptimizedEntry>
  )
}

Use loadingFallback, direct children, wrapper props, and nested composition patterns when needed. The React Web guide covers those variants in context.

Entry interaction tracking

OptimizedEntry emits the Web SDK's data-ctfl-* tracking attributes for resolved entries. Enable automatic tracking in the root config when views, clicks, or hovers must be detected by the Web SDK:

<OptimizationRoot
  clientId="your-client-id"
  autoTrackEntryInteraction={{ views: true, clicks: true, hovers: false }}
>
  <YourApp />
</OptimizationRoot>

Use sdk.tracking.enableElement(...) from useOptimization() for manual element overrides.

Router page events

Router adapters emit page() events for supported client-side routers:

Router Import path Mounting rule
React Router @contentful/optimization-react-web/router/react-router Mount under a React Router data router and inside OptimizationRoot
Next.js Pages @contentful/optimization-react-web/router/next-pages Mount once in pages/_app.tsx inside OptimizationRoot
Next.js App Router @contentful/optimization-react-web/router/next-app Mount in a client provider used by app/layout.tsx
TanStack Router @contentful/optimization-react-web/router/tanstack-router Mount under the TanStack router tree and inside OptimizationRoot

All adapters support static and dynamic page payload enrichment. See the React Web integration guide for router-specific examples.

Live updates and preview

liveUpdates defaults to false, so optimized entries lock to the first resolved value. Set liveUpdates globally or per OptimizedEntry when entries must react to profile, flag, or preview changes:

<OptimizationRoot clientId="your-client-id" liveUpdates={true}>
  <OptimizedEntry baselineEntry={entry} liveUpdates={false}>
    {(resolvedEntry) => <Card entry={resolvedEntry} />}
  </OptimizedEntry>
</OptimizationRoot>

The browser preview panel is provided by @contentful/optimization-web-preview-panel. When the panel is open, live updates are forced on for all OptimizedEntry components so authors can inspect variant changes immediately.

Development harness

The package-local development harness runs from packages/web/frameworks/react-web-sdk/dev/. Launch it from the repo root:

pnpm --filter @contentful/optimization-react-web dev:launch

Use the harness for package development. Use the reference implementation for end-to-end integration behavior.

Related