Integrate the Optimization Next.js SDK in a Next.js Pages Router app

Overview

Use this guide to add Contentful personalization to a Next.js Pages Router site you already have. By the end of the quick start, one piece of content will be personalized per visitor in the server-rendered HTML — resolved in getServerSideProps, no flash of default content, no rewrite of how your app fetches or renders.

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.
• When a page is requested, Contentful’s Experience API looks at the current visitor 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 — personalized first paint (the quick start below). getServerSideProps resolves the visitor’s variants on the server and hands that state to the page, so the visitor sees their variant in the server HTML. This is complete and shippable on its own.
• Milestone 2 — browser takeover (opt-in, later). After the page loads, the browser SDK takes ownership of personalization from the server-resolved state, so content can re-personalize live when consent, identity, or the profile changes — without a page reload. The profile is the anonymous id the SDK uses to keep the same visitor consistent across requests. See Browser takeover and live updates.

This guide uses @contentful/optimization-nextjs. The /pages-router factory gives you app-local components for the browser, and /pages-router/server prepares the serializable state your pages hand to the browser from getServerSideProps. Your app keeps ownership of Contentful fetching, consent policy, identity, routing, caching, and rendering.

If your app uses the App Router, use the Next.js App Router guide instead.

Quick start

Most Pages Router + Contentful sites share one shape: getServerSideProps fetches the entries a page needs, and the page component renders them through your own components. This quick start assumes that shape. In the snippets that change an existing file, lines prefixed with + are what you add and - lines are what you replace; the rest is a typical app for context — match the changes 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 Personalizing entries.

It proves one result: one entry renders its personalized variant in the server HTML. It assumes your app may personalize on startup. If personalization must wait for consent, keep this structure and add the Consent, identity, profile, and reset step before you ship.

1. Install the adapter package.

   Copy this:

   1
   pnpm add @contentful/optimization-nextjs

2. Create one module that binds the browser components to your config. You do this once and import the components from it everywhere. Use the same environment-variable convention your app already uses for Contentful. The snippets import it as @/lib/optimization, which assumes the file is at lib/optimization.ts and your tsconfig maps @/* to the project root — adjust the specifier to match your own paths.

   The defaults below seed two consent flags: consent (the SDK may personalize and send events for this visitor) and persistenceConsent (the SDK may store the anonymous profile-id cookie so results stay consistent). The quick start turns both on; the consent section makes them depend on a real choice.

   Adapt this to your use case: replace the placeholder values and the import path; the config keys are explained in How the SDK fits your app.

   1
   // lib/optimization.ts
   2
   import { createNextjsPagesRouterOptimization } from '@contentful/optimization-nextjs/pages-router'
   3
   4
   export const APP_LOCALE = 'en-US'
   5
   6
   export const { NextPagesAutoPageTracker, OptimizationRoot, OptimizedEntry } =
   7
     createNextjsPagesRouterOptimization({
   8
       clientId: process.env.NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID ?? '',
   9
       environment: process.env.NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main',
   10
       locale: APP_LOCALE,
   11
       // consent: allowed to personalize and send events for this visitor.
   12
       // persistenceConsent: allowed to store a profile-id cookie so results stay consistent.
   13
       defaults: { consent: true, persistenceConsent: true },
   14
       app: { name: 'my-next-pages-app', version: '1.0.0' },
   15
     })

3. Create a server-only module that prepares the Optimization state your pages hand to the browser. This is where server-side resolution happens: the helper reads the visitor’s cookies, asks the Experience API who they are, resolves their variants, and returns serializable state plus the ctfl-opt-aid cookie that keeps the same visitor consistent next request. You are only configuring it — not writing that logic.

   Adapt this to your use case: replace the placeholder values and the import path. APP_LOCALE is imported from './optimization' (step 2) so both the server and browser use one locale definition — adjust if your app stores the locale elsewhere.

   1
   // lib/optimization-server.ts
   2
   import { createNextjsPagesRouterOptimization } from '@contentful/optimization-nextjs/pages-router/server'
   3
   import type { GetServerSidePropsContext } from 'next'
   4
   import { APP_LOCALE } from './optimization'
   5
   6
   const { getServerSideOptimizationProps } = createNextjsPagesRouterOptimization({
   7
     clientId: process.env.NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID ?? '',
   8
     environment: process.env.NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main',
   9
     locale: APP_LOCALE,
   10
     app: { name: 'my-next-pages-app', version: '1.0.0' },
   11
     // Per-request decision: may the server personalize? `true` always personalizes;
   12
     // the consent section makes it read your recorded choice per request.
   13
     server: { consent: true },
   14
   })
   15
   16
   export function getOptimizationProps(context: GetServerSidePropsContext) {
   17
     return getServerSideOptimizationProps(context)
   18
   }

4. Mount the bound root and page tracker once in pages/_app.tsx. Keep everything your app shell already renders — Head, navigation, providers, styles. You are adding a wrapper, not replacing the file. Put the root around everything so any part of the app can be personalized later too.

   Adapt this to your use case: the + lines are the additions; the rest is a typical pages/_app.tsx for context.

   1
   // pages/_app.tsx
   2
   +import { NextPagesAutoPageTracker, OptimizationRoot } from '../../../../lib/optimization'
   3
   +// NextjsPagesRouterOptimizationPageProps: the shape of pageProps.contentfulOptimization the root reads.
   4
   +import type { NextjsPagesRouterOptimizationPageProps } from '@contentful/optimization-nextjs/pages-router/server'
   5
    import type { AppProps } from 'next/app'
   6
   7
   +interface OptimizationAppPageProps {
   8
   +  readonly contentfulOptimization?: NextjsPagesRouterOptimizationPageProps
   9
   +}
   10
   11
   -export default function App({ Component, pageProps }: AppProps) {
   12
   +export default function App({ Component, pageProps }: AppProps<OptimizationAppPageProps>) {
   13
   +  const optimization = pageProps.contentfulOptimization
   14
      return (
   15
   +    <OptimizationRoot
   16
   +      clientDefaults={optimization?.clientDefaults}
   17
   +      serverOptimizationState={optimization?.serverOptimizationState}
   18
   +    >
   19
   +      {/* "skip" when the server already reported this page view; the helper decides. */}
   20
   +      <NextPagesAutoPageTracker initialPageEvent={optimization?.initialPageEvent} />
   21
          <Component {...pageProps} />
   22
   +    </OptimizationRoot>
   23
      )
   24
    }

5. In a personalized page’s getServerSideProps, fetch your entries and call the helper together, merge the returned props, and wrap each entry in OptimizedEntry where the page renders it. Keep your fetch and your components as they are.

   The two type names from /pages-router/server look alike, so keep them straight: NextjsPagesRouterOptimizationProps (used here) is what you spread into your page’s own returned props — it carries the contentfulOptimization field. NextjsPagesRouterOptimizationPageProps (used in step 4) is the shape of that one field, which _app.tsx reads from pageProps.

   Adapt this to your use case: getPageBySlug(...) stands in for your existing fetch — yours takes whatever route params it needs. The + lines are the additions; the merge of optimization.props and the entry wrap are the pattern to copy.

   1
   // pages/[slug].tsx
   2
   +import { OptimizedEntry } from '../../../../lib/optimization'
   3
   +import { getOptimizationProps } from '../../../../lib/optimization-server'
   4
   +import type { NextjsPagesRouterOptimizationProps } from '@contentful/optimization-nextjs/pages-router/server'
   5
    import { getPageBySlug } from '../../../../lib/contentful' // your existing fetch
   6
    import type { Entry } from 'contentful'
   7
    import type { GetServerSideProps } from 'next'
   8
   9
   -type PageProps = { entries: Entry[] }
   10
   +type PageProps = NextjsPagesRouterOptimizationProps & { entries: Entry[] }
   11
   12
    export const getServerSideProps: GetServerSideProps<PageProps> = async (context) => {
   13
   -  const entries = await getPageBySlug(context.params?.slug)
   14
   -  return { props: { entries } }
   15
   +  const [entries, optimization] = await Promise.all([
   16
   +    getPageBySlug(context.params?.slug), // your fetch, keyed by the route's params
   17
   +    getOptimizationProps(context),
   18
   +  ])
   19
   +  // Spread the helper's props so pageProps.contentfulOptimization reaches pages/_app.tsx.
   20
   +  return { props: { ...optimization.props, entries } }
   21
    }
   22
   23
    export default function Page({ entries }: PageProps) {
   24
      return entries.map((entry) => (
   25
   -    <YourCard key={entry.sys.id} entry={entry} />
   26
   +    <OptimizedEntry key={entry.sys.id} baselineEntry={entry}>
   27
   +      
   28
   +      {(resolved) => <YourCard entry={resolved as YourEntryType} />}
   29
   +    </OptimizedEntry>
   30
      ))
   31
    }

6. Check that it works. In Contentful, author a variant on an entry your page renders and attach it to an experience — for a first test, target all visitors so you match it automatically. Load the page, View Source (or disable JavaScript), and search the raw HTML for the variant’s text. It must be present in the server HTML and stay on screen after the page hydrates. If you see the original content instead, work through Troubleshooting. (This is the authored variant Before you start covers in more detail.)

You now have personalization working end to end. 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; your Contentful fetch requirements and the baseline-fallback contract; browser takeover and live updates; interaction tracking; and production hardening. Read straight through to understand the pieces, 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 Next.js Pages Router app with React and React DOM installed, and its own Contentful fetching already working.
• 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 — the server helper, the root, entry wrapping, consent, tracking — 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 two modules you created in the quick start — the browser binding (lib/optimization.ts) and the server helper (lib/optimization-server.ts) — what each config key does, and how to make startup depend on real consent.

The Next.js adapter is a thin layer between three things you already have or control: your Contentful data, Contentful’s Experience API, and your React components. Unlike the App Router, the Pages Router split is explicit: one module binds the browser components, and a separate server-only module prepares the state your pages pass through pageProps.

Import from these subpaths, not the package root: @contentful/optimization-nextjs itself is not an import path, so always reach for /pages-router, /pages-router/server, or /client.

The config you pass to the browser factory (/pages-router) breaks 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). For personalized pages this is overridden per request by the clientDefaults the server helper returns (see the handoff section).
4. app is your app’s name and version, sent as metadata.
5. api overrides the Experience and Insights endpoints. Set it only for a mock, a proxy, or non-default hosts; omit it otherwise. Optional factory keys trackEntryInteraction, liveUpdates, and onStatesReady are covered in their own sections.

The server helper (/pages-router/server) takes the same project fields plus one required key, server.consent, which decides per request whether the server may personalize. It accepts a boolean or a function of the getServerSideProps context. The browser factory has no server key — server policy lives only here.

The quick start used always-on defaults and server.consent: true to get you a result. For production, make startup depend on real consent: seed the browser defaults off, and make server.consent a function that reads your app’s recorded choice from the request. The server helper then derives clientDefaults from what you return, so the browser starts in the same consent state.

CONSENT_COOKIE below is your cookie, not an SDK cookie — you name it, you write it (from your consent UI or Consent Management Platform (CMP)), and you read it here. The SDK never touches it; it only personalizes based on what your server.consent function returns. (The one SDK-managed cookie is ctfl-opt-aid, from the state handoff.) The Consent, identity, profile, and reset section shows the browser component that writes this cookie.

Adapt this to your use case: the browser module from step 2 with defaults turned off, and the server module from step 3 with server.consent reading real consent per request.

1
// lib/optimization.ts — browser binding
2
import { createNextjsPagesRouterOptimization } from '@contentful/optimization-nextjs/pages-router'
3
4
export const APP_LOCALE = 'en-US'
5
6
export const { NextPagesAutoPageTracker, OptimizationRoot, OptimizedEntry } =
7
  createNextjsPagesRouterOptimization({
8
    clientId: process.env.NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID ?? '',
9
    environment: process.env.NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main',
10
    locale: APP_LOCALE,
11
    app: { name: 'my-next-pages-app', version: '1.0.0' },
12
    // Changed from step 2: start off. The server helper's clientDefaults win per request.
13
    defaults: { consent: false, persistenceConsent: false },
14
  })

Adapt this to your use case: the matching server helper, with request-owned consent.

1
// lib/optimization-server.ts — server helper
2
import { createNextjsPagesRouterOptimization } from '@contentful/optimization-nextjs/pages-router/server'
3
import type { GetServerSidePropsContext } from 'next'
4
import { APP_LOCALE } from './optimization'
5
6
const CONSENT_COOKIE = 'app-personalization-consent'
7
8
const { getServerSideOptimizationProps } = createNextjsPagesRouterOptimization({
9
  clientId: process.env.NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID ?? '',
10
  environment: process.env.NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main',
11
  locale: APP_LOCALE,
12
  app: { name: 'my-next-pages-app', version: '1.0.0' },
13
  server: {
14
    // Personalize only when your app has recorded consent for this visitor.
15
    consent: (context: GetServerSidePropsContext) =>
16
      context.req.cookies[CONSENT_COOKIE] === 'granted'
17
        ? { events: true, persistence: true }
18
        : false,
19
  },
20
})
21
22
export function getOptimizationProps(context: GetServerSidePropsContext) {
23
  return getServerSideOptimizationProps(context)
24
}

Create each of these modules exactly once. Sharing one browser binding keeps every OptimizedEntry under one SDK instance; sharing one server helper keeps the anonymous-id and consent policy consistent across routes.

Fetching Contentful entries

Integration category: Required for first integration

Your app owns the Contentful client. There are two supported ways to get a fetched entry to the SDK’s resolution hand-off, and this guide teaches the first:

• Manual (the quick-start default): you fetch the entry yourself and pass it in as baselineEntry. You keep your existing client, fetchers, caching, and rendering; the SDK only needs entries to arrive in a shape it can resolve.
• Managed (opt-in, server-side): you configure the server factory with contentful: { client } and let the SDK fetch entries by ID for you during server prefetch, then hand the results to the browser. See the managed note under Personalizing entries.

Either way the SDK sits at the same hand-off and returns the resolved variant — or the baseline entry when none applies. The fetch rules below apply to both paths.

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 page, its sections, and the linked variant entries. include: 10 is the common setting and is what most section-composed sites already use.
3. If you use .withoutUnresolvableLinks (common for deeply-linked pages), keep it; it does not interfere with variant resolution as long as the variant entries are published and within your include depth.
4. Use the same locale for Contentful and for the SDK when localized Experience responses and rendered content must line up.

Your existing fetch usually needs no change — most section-composed sites already fetch a page by slug with a generous include depth and a single locale. 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).

For the resolver contract, see Entry personalization and variant resolution. For the full locale model, see Locale handling in the Optimization SDK Suite.

The getServerSideProps state handoff and the profile cookie

Integration category: Required for first integration

This explains the server helper you configured in step 3 and called in step 5. There is no middleware or proxy in the Pages Router integration — all server work happens inside getServerSideProps when you call getServerSideOptimizationProps(context). On each request it:

1. Builds request context from the Pages Router context (cookies, headers, URL).
2. Reads the visitor’s ctfl-opt-aid cookie, asks the Experience API who they are, and resolves their variants.
3. Writes or clears the ctfl-opt-aid cookie on the response (via Set-Cookie) when persistence consent allows, so the same visitor stays consistent on later requests.
4. Returns a serializable props.contentfulOptimization object with three fields.

The returned props.contentfulOptimization carries exactly what pages/_app.tsx needs:

Two things you control here:

1. Consent policy lives in server.consent (from the previous section). Return false to fall back to baseline for that request. The server.consent resolver receives the GetServerSidePropsContext, so you read cookies with context.req.cookies[NAME] — not the App Router’s cookies.get(NAME).
2. Merging the props. Spread optimization.props into your page’s returned props (step 5) so pageProps.contentfulOptimization reaches pages/_app.tsx. If you forget the spread, the root gets no server state and every entry renders baseline.

Handle Experience API failure yourself. The render-layer fallbacks — no variant, denied consent, unresolved links, all-locale payloads — are automatic: OptimizedEntry receives the baseline entry and your UI is fine. A failed Experience API call is different. getServerSideOptimizationProps awaits the Experience request with no internal try/catch, so if the API is unavailable it throws, which rejects your getServerSideProps promise and serves Next.js’s 500 page instead of baseline content. If you want baseline HTML when the API is down, catch it and return your page’s props without contentfulOptimization. The root then gets no server state, so every OptimizedEntry renders its baseline.

Adapt this to your use case: wrap the helper call so an Experience outage degrades to baseline instead of a 500. The catch branch omits contentfulOptimization, so make it optional on your page-props type (Partial<NextjsPagesRouterOptimizationProps>) for both branches to type-check.

1
type PageProps = Partial<NextjsPagesRouterOptimizationProps> & { entries: Entry[] }
2
3
export const getServerSideProps: GetServerSideProps<PageProps> = async (context) => {
4
  const entries = await getPageBySlug(context.params?.slug) // your fetch, keyed by route params
5
  try {
6
    const optimization = await getOptimizationProps(context)
7
    return { props: { ...optimization.props, entries } }
8
  } catch {
9
    // Experience API unavailable: render baseline. No contentfulOptimization ⇒ no server state ⇒
10
    // every OptimizedEntry falls back to its baselineEntry, and _app.tsx reads undefined.
11
    return { props: { entries } }
12
  }
13
}

One cookie constraint matters: ctfl-opt-aid is written without HttpOnly on purpose — the browser SDK must read it to keep the same profile after takeover. It is the SDK’s cookie; match the name only if you read it directly. For how server and browser stay on the same profile, see Profile synchronization between client and server.

The bound root and page events

Integration category: Required for first integration

Step 4 mounted the root and tracker in pages/_app.tsx. Here is what they do and the one decision you have to get right. OptimizationRoot applies the server’s decisions (serverOptimizationState) and starting consent (clientDefaults) before its children render, then carries personalization state through your tree. NextPagesAutoPageTracker reports page events — a signal that a page was viewed — as the visitor navigates between Pages Router routes.

Two rules and one decision:

1. Configure behavior (defaults, trackEntryInteraction, onStatesReady, liveUpdates) in the browser factory, not as per-render props on the root. The root only takes the request-specific clientDefaults and serverOptimizationState.
2. Unlike the App Router tracker, NextPagesAutoPageTracker reads the Pages Router useRouter, not useSearchParams, so it does not need a Suspense boundary. Mount it directly under the root.
3. The decision: who owns the first page event. When the server personalized the page it already reported that view, so the helper returns initialPageEvent: 'skip' to stop the browser reporting a duplicate. Pass that value straight through, as in step 4. On a page with no server helper, pageProps.contentfulOptimization is undefined, so initialPageEvent is undefined and the tracker emits — which is correct for a browser-owned route.

getPagePayload lets you attach route-specific properties to each page event — for example, grouping routes by section for analytics filtering. It receives an emission context whose route fields (pathname, asPath, query, router) are nested under context, and returns properties merged into that page event. Destructure the route fields from context, not the top level.

Adapt this to your use case: attaching route-aware properties to page events. routeGroup is an arbitrary property name you choose.

1
<NextPagesAutoPageTracker
2
  initialPageEvent={optimization?.initialPageEvent}
3
  getPagePayload={({ context: { pathname } }) => ({
4
    properties: { routeGroup: pathname.startsWith('/account') ? 'account' : 'public' },
5
  })}
6
/>

The tracker deduplicates consecutive route keys, including React Strict Mode’s double effects, but it does not replace your page-event policy. Let the helper choose skip only when there is a matching server page event.

Personalizing entries

Integration category: Required for first integration

Step 5 showed the wrap. This explains the two things about it that matter everywhere, then covers a second app shape.

OptimizedEntry resolves the entry against the request’s decisions and renders the variant — or the baseline entry — through your render prop. Because the root hydrated serverOptimizationState before children rendered, the variant is already in the server HTML; no JavaScript is required for the visitor to see personalized content. The rule never changes: wherever a Contentful entry becomes a component, wrap it and render whatever the render prop hands back. Three facts hold everywhere:

• 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 works even before you author a variant.
• 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.

The quick-start example wrapped entries directly in the page. The other common shape is a renderer or registry that maps a content type to a component; wrap it there and every entry it renders is personalized — the wrap and the cast are identical:

Adapt this to your use case: a content-type-to-component renderer. The + lines are the additions; keep your existing guards.

1
// e.g. your renderer that maps a content type to a component (yours may be named differently)
2
+import { OptimizedEntry } from '../../../../lib/optimization'
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
 }

Letting the server fetch by ID (managed)

If you would rather the SDK fetch an entry for you than fetch it yourself, give the server helper a Contentful client and prefetch entries by ID. This is a server-side path: on the Pages Router the browser factory does not carry a Contentful client, so the browser never fetches by ID on its own — the server prefetches during getServerSideProps and hands the results to the browser through the same pageProps.

Three changes wire it up, and all three are required — skip the third and the entry never finds its prefetched baseline, so it silently renders nothing:

1. Add contentful: { client } to the server factory config from step 3 so the SDK can call getEntry() on your client.
2. Pass prefetchManagedEntries — a list of ManagedEntryDescriptor values, where strings are entry IDs and object descriptors can include { entryId, entryQuery? }. entryQuery is optional getEntry() query params such as include depth. Pass it as the second argument to getServerSideOptimizationProps. The helper fetches and resolves those entries during getServerSideProps and adds them to the state it returns.
3. Pass that state to the bound OptimizationRoot in _app.tsx as prefetchedManagedEntries, so a bound <OptimizedEntry entryId="..."> hydrates from the server-prefetched baseline with no client fetch.

client and entryId are your values; contentful, prefetchManagedEntries, and prefetchedManagedEntries are the SDK-defined keys.

When several uncached descriptors share the same normalized query, the server helper uses your client’s getEntries() method. Large getEntries() fetches are split into 100-ID chunks.

Apply them in that order — the root prop must exist before a page wraps an entry by id, or the page renders nothing. First, the server helper: this replaces the lib/optimization-server.ts from step 3 (it is the same module, with a Contentful client added and the prefetch list forwarded), not a second module alongside it.

Adapt this to your use case: the step-3 server helper with a Contentful client attached and a prefetch list forwarded. getYourContentfulClient() and the entry ID are yours.

1
// lib/optimization-server.ts — server helper, managed variant
2
import { createNextjsPagesRouterOptimization } from '@contentful/optimization-nextjs/pages-router/server'
3
import type { GetServerSidePropsContext } from 'next'
4
import { APP_LOCALE } from './optimization'
5
import { getYourContentfulClient } from './contentful' // your existing client
6
7
const { getServerSideOptimizationProps } = createNextjsPagesRouterOptimization({
8
  clientId: process.env.NEXT_PUBLIC_OPTIMIZATION_CLIENT_ID ?? '',
9
  environment: process.env.NEXT_PUBLIC_OPTIMIZATION_ENVIRONMENT ?? 'main',
10
  locale: APP_LOCALE,
11
  app: { name: 'my-next-pages-app', version: '1.0.0' },
12
  server: { consent: true },
13
  // Managed fetching: the SDK calls getEntry() on your client during server prefetch.
14
  contentful: { client: getYourContentfulClient() },
15
})
16
17
export function getOptimizationProps(context: GetServerSidePropsContext) {
18
  return getServerSideOptimizationProps(context, {
19
    // Fetched and resolved on the server; handed to the browser as prefetchedManagedEntries.
20
    prefetchManagedEntries: [{ entryId: 'your-entry-id' }],
21
  })
22
}

Next, forward the prefetched entries from _app.tsx by passing one more prop on the OptimizationRoot from step 4 — the state field the helper populated alongside serverOptimizationState:

Adapt this to your use case: the one added prop on the OptimizationRoot from step 4.

1
 <OptimizationRoot
2
   clientDefaults={optimization?.clientDefaults}
3
   serverOptimizationState={optimization?.serverOptimizationState}
4
+  prefetchedManagedEntries={optimization?.prefetchedManagedEntries}
5
 >

Finally, the page wraps the entry by id instead of passing a baselineEntry — the entry is already in the server-handed state, so no client fetch happens:

Follow this pattern: a managed entry, wrapped by id.

1
<OptimizedEntry entryId="your-entry-id">
2
  {(resolved) => <YourCard entry={resolved as YourEntryType} />}
3
</OptimizedEntry>

The manual baselineEntry path stays the default for this guide: it keeps your fetch and caching in your own code. Reach for the managed path only when letting the SDK fetch by ID is simpler than threading an entry through your props.

Browser takeover and live updates

Integration category: Common but policy-dependent

This is Milestone 2. First paint is already complete and shippable; add this only when some content must re-personalize after the page loads — 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 for the life of a request. The bound OptimizationRoot already renders a live-updates provider internally, so you do not mount one to get started — you choose the scope:

1. App-wide, static default: set liveUpdates: true in the browser factory config (createNextjsPagesRouterOptimization). The bound root passes it to its internal provider, so every live-capable entry re-resolves on state changes for the life of the app. Use this when live updates are simply always on.
2. App-wide, runtime-toggled: when the default must change at runtime — a consent-driven or author-driven switch — wrap the root’s children in your own LiveUpdatesProvider from /client and drive its globalLiveUpdates prop from your own state. A nested provider overrides the bound root’s internal default, so this is how you turn live updates on and off without a reload. This is the pattern the reference implementation uses (its GlobalLiveUpdatesProvider wraps LiveUpdatesProvider).
3. Per-entry: pass liveUpdates to the app-local OptimizedEntry. A per-entry value overrides the app-wide setting, so you can opt one entry in (liveUpdates) or out (liveUpdates={false}) independently. Unlike the App Router, the Pages Router OptimizedEntry accepts liveUpdates directly — you do not need a separate /client import for it.
4. Use /client hooks such as useOptimizedEntry() only when you need rendering control the wrapper does not offer.

Follow this pattern: the app-wide static switch, in the browser factory from step 2 of the quick start.

1
createNextjsPagesRouterOptimization({
2
  // ...clientId, environment, locale, defaults, app
3
  liveUpdates: true, // every live-capable entry re-resolves on browser state changes
4
})

Adapt this to your use case: a runtime toggle. Nest a LiveUpdatesProvider from /client inside the OptimizationRoot you mounted in step 4 and feed globalLiveUpdates from your own state (consent, an author switch, a feature flag), so live updates can flip on and off without a reload. The + lines are the additions to the pages/_app.tsx from step 4.

1
 // pages/_app.tsx
2
+import { LiveUpdatesProvider } from '@contentful/optimization-nextjs/client'
3
 // ...your other imports, including the bound root and tracker from step 4
4
5
 export default function App({ Component, pageProps }: AppProps<OptimizationAppPageProps>) {
6
   const optimization = pageProps.contentfulOptimization
7
+  const [liveUpdates, setLiveUpdates] = useState(false) // your own toggle / consent state
8
   return (
9
     <OptimizationRoot
10
       clientDefaults={optimization?.clientDefaults}
11
       serverOptimizationState={optimization?.serverOptimizationState}
12
     >
13
+      <LiveUpdatesProvider globalLiveUpdates={liveUpdates}>
14
         <NextPagesAutoPageTracker initialPageEvent={optimization?.initialPageEvent} />
15
         <Component {...pageProps} />
16
+      </LiveUpdatesProvider>
17
     </OptimizationRoot>
18
   )
19
 }

Adapt this to your use case: a single entry that re-resolves on profile changes, without turning on the app-wide default. In the Pages Router every component is client-rendered after SSR, so no directive is needed — but this entry only takes over once the browser SDK is running.

1
import { OptimizedEntry } from '../../../../lib/optimization'
2
import type { Entry } from 'contentful'
3
4
export function LiveEntry({ baselineEntry }: { baselineEntry: Entry }) {
5
  return (
6
    <OptimizedEntry baselineEntry={baselineEntry} liveUpdates>
7
      {(resolved) => <article>{String(resolved.fields.title ?? '')}</article>}
8
    </OptimizedEntry>
9
  )
10
}

For entries the browser owns, OptimizedEntry also accepts a loadingFallback prop (a node or a function returning one) for the brief window before optimization state resolves. It is rarely needed on server-first pages, which already have the resolved baseline in the HTML; the default is to render the baseline while loading.

To verify takeover, enable live updates, then trigger identifyUser(), setConsent(), or resetUser() from a browser component (see the next sections). Confirm that live entries re-resolve without a full reload and that entries with liveUpdates={false} stay put until the next render.

Entry interaction tracking

Integration category: Common but policy-dependent

Interaction tracking — views, clicks, and hovers on entries — is a browser behavior. OptimizedEntry renders the metadata the browser 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 factory trackEntryInteraction option only to opt out of an interaction type you must not observe.
2. Use OptimizedEntry props such as clickable, trackViews, trackClicks, trackHovers, viewDurationUpdateIntervalMs, and hoverDurationUpdateIntervalMs for per-entry control.
3. Page events can be allowed before full consent, but entry views, clicks, and hovers stay blocked until consent or allowedEventTypes permits them.

Follow this pattern: opting out of one detector globally.

1
createNextjsPagesRouterOptimization({
2
  // ...clientId, environment, locale, defaults, app
3
  trackEntryInteraction: { hovers: false }, // opt out only where policy requires it
4
})

For app-owned manual observation, useOptimization() from /client exposes the SDK; call sdk.trackView({ ... }) from your own component. Tracking uses the resolved entry id, not the baseline id. For mechanics, see Interaction tracking in Web SDKs.

Consent, identity, profile, and reset

Integration category: Common but policy-dependent

Consent, identity, and profile continuity are your application’s decisions. The SDK gives you the runtime controls; your app owns the consent record, the privacy notice, the CMP, the identity source, and cookie cleanup.

1. If policy permits accepted startup, return accepted server.consent and seed accepted browser defaults.
2. If policy depends on user choice, read the choice in server.consent (context.req.cookies[...]) and call setConsent() from the browser component that owns the decision.
3. Store the decision where the next request’s server.consent can read it — the same CMP, account preference, or cookie. Because server.consent reads context.req.cookies, a cookie is the simplest store.
4. Call identifyUser() when a visitor becomes known, and resetUser() (plus clearing your own profile cookies) on sign-out or withdrawal.

Adapt this to your use case: a control panel wired to the SDK actions. The hooks come from /client; the consent cookie is app-owned and matches the name your server.consent reads. useConsentState() returns the SDK’s current consent as a reactive value, so the useEffect below re-runs whenever it changes.

1
import {
2
  useConsentState,
3
  useOptimizationActions,
4
  useProfileState,
5
} from '@contentful/optimization-nextjs/client'
6
import { useEffect } from 'react'
7
8
const CONSENT_COOKIE = 'app-personalization-consent'
9
10
function persistConsent(consented: boolean): void {
11
  // Store where server.consent can read it on the next request.
12
  document.cookie = `${CONSENT_COOKIE}=${consented ? 'granted' : 'denied'}; Path=/; SameSite=Lax`
13
}
14
15
export function PersonalizationControls() {
16
  const { setConsent, identifyUser, resetUser } = useOptimizationActions()
17
  const consent = useConsentState()
18
  const profile = useProfileState()
19
  const isIdentified = Boolean(profile?.traits.identified)
20
21
  useEffect(() => {
22
    // Mirror consent changes to the cookie so server.consent reads them on the next request —
23
    // without this, server and browser consent state diverge.
24
    if (typeof consent === 'boolean') persistConsent(consent)
25
  }, [consent])
26
27
  return (
28
    <div>
29
      <button onClick={() => setConsent(consent !== true)} type="button">
30
        {consent === true ? 'Reject consent' : 'Accept consent'}
31
      </button>
32
      {isIdentified ? (
33
        <button onClick={() => resetUser()} type="button">
34
          Reset profile
35
        </button>
36
      ) : (
37
        <button
38
          onClick={() => void identifyUser({ userId: 'user-123', traits: { identified: true } })}
39
          type="button"
40
        >
41
          Identify
42
        </button>
43
      )}
44
    </div>
45
  )
46
}

With live updates enabled, identifyUser(), setConsent(), and resetUser() can change the selected variants in the browser and re-render affected entries without a reload. For consent design, see Consent management in the Optimization SDK Suite.

Optional integrations

Analytics forwarding

Integration category: Optional

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

1. Register browser subscriptions with the factory onStatesReady option so observers attach before child effects such as the route tracker emit events.
2. Dedupe forwarded events by messageId or a destination-specific key.
3. Store forwarded message ids in module or app state so remounts do not forward the same event again. To receive only future events, read the current messageId before subscribing and skip it.
4. Gate forwarding with the same consent and destination policy that governs the rest of your analytics stack.

Adapt this to your use case:

1
const forwardedMessageIds = new Set<string>()
2
3
export const { NextPagesAutoPageTracker, OptimizationRoot, OptimizedEntry } =
4
  createNextjsPagesRouterOptimization({
5
    // ...clientId, environment, locale, defaults, app
6
    onStatesReady: (states) => {
7
      // Subscribe before child effects, such as the route tracker, emit events.
8
      const initialMessageId = states.eventStream.current?.messageId
9
10
      const eventSubscription = states.eventStream.subscribe((event) => {
11
        if (!event) return
12
        if (forwardedMessageIds.has(event.messageId)) return
13
        if (event.messageId === initialMessageId) {
14
          forwardedMessageIds.add(event.messageId)
15
          return
16
        }
17
        if (!canForwardSdkEvent(event)) return
18
19
        forwardedMessageIds.add(event.messageId)
20
        analytics.track(`Contentful ${event.type}`, pickContentfulEventProperties(event))
21
      })
22
23
      const blockedSubscription = states.blockedEventStream.subscribe((blockedEvent) => {
24
        if (blockedEvent) diagnostics.recordBlockedOptimizationEvent(blockedEvent)
25
      })
26
27
      return () => {
28
        eventSubscription.unsubscribe()
29
        blockedSubscription.unsubscribe()
30
      }
31
    },
32
  })

forwardedMessageIds is intentionally module-scoped, not created inside onStatesReady: it lives for the lifetime of the app so a component remount that re-runs the subscription still skips ids it already forwarded. If your destination has its own idempotency key you can drop the Set and dedupe there instead.

See Forwarding Optimization SDK context to analytics and tag-management tools for request-local server mapping, subscription helpers, vendor examples, consent, dedupe, and governance guidance.

Merge tags and Custom Flags

Integration category: Optional

Use merge tags and Custom Flags when entries or components render profile-backed values that are not entry replacements.

1. Resolve Rich Text merge tag entries with the getMergeTagValue function passed to the OptimizedEntry render prop’s second argument.
2. Keep the SDK locale aligned with the rendered Contentful locale when merge tags reference localized profile fields such as location.city or location.country.
3. Use flag state from the browser SDK for components that must react after browser startup.
4. Treat flag-view and merge-tag events as consent-gated browser activity unless the server path owns the event.

Merge tags live inside Rich Text as embedded entry nodes, so getMergeTagValue takes a merge-tag entry node — not a plain field. You resolve them while rendering the Rich Text document: for each embedded entry, guard with isMergeTagEntry (from /api-schemas) and pass the node’s target to getMergeTagValue.

Follow this pattern:

1
import { OptimizedEntry } from '../../../../lib/optimization'
2
import { isMergeTagEntry } from '@contentful/optimization-nextjs/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. Use useMergeTagResolver() from /client only in browser components that need merge tags outside an OptimizedEntry render prop.

Preview panel

Integration category: Optional

Use the preview panel where authors or engineers need to inspect variant behavior — including forcing a specific variant to verify a targeted experience. Keep production loading explicit and gate attachment behind an application-owned flag.

1. Add the preview panel package only when your app needs browser authoring tooling.
2. Attach the panel from a component mounted under OptimizationRoot.
3. Wait until the browser SDK is ready before attaching.
4. Pass an app-owned Contentful client or pre-fetched preview entries to the attach function.
5. Enable it only when an approved environment sets your own NEXT_PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL flag to true. This is an app-owned env var you name, not an SDK value.
6. Verify with live updates, because the preview panel forces optimized entries to react to preview state.

Follow this pattern:

1
import { useOptimizationContext } from '@contentful/optimization-nextjs/client'
2
import { useEffect } from 'react'
3
4
export function PreviewPanelAttachment({ nonce }: { nonce?: string }) {
5
  // The context exposes the SDK instance; it is undefined until the browser SDK is ready.
6
  const { sdk } = useOptimizationContext()
7
  const enabled = process.env.NEXT_PUBLIC_OPTIMIZATION_ENABLE_PREVIEW_PANEL === 'true'
8
9
  useEffect(() => {
10
    if (!enabled || sdk === undefined) return // opt-in, and only after the SDK is ready
11
12
    void Promise.all([
13
      import('@contentful/optimization-web-preview-panel'),
14
      import('@/lib/contentful'), // your Contentful client module
15
    ])
16
      .then(async ([{ default: attachOptimizationPreviewPanel }, { client }]) => {
17
        await attachOptimizationPreviewPanel({ contentful: client, nonce })
18
      })
19
      .catch(() => undefined)
20
  }, [sdk, nonce, enabled])
21
22
  return null
23
}

A dynamic import only loads the attach function; your app must call attachOptimizationPreviewPanel(...) with a Contentful client, or with entries: { audiences, experiences } when you already loaded the preview definitions. entries takes precedence over contentful.

Advanced integrations

Mixed route strategies

Integration category: Advanced or production-only

Pages Router applications can mix route strategies. Choose the strategy per page instead of forcing one rendering model across the whole app.

1. Keep SEO-sensitive content in getServerSideProps pages so it appears in the initial HTML.
2. Use /client hooks for controls that call identifyUser(), setConsent(), resetUser(), live flag state, or manual tracking.
3. Reuse the same OptimizationRoot (mounted once in pages/_app.tsx) so every route shares one browser SDK instance and one profile.
4. Reuse the same Contentful locale and anonymous-id continuity across strategies.

Manual server and client escape hatches

Integration category: Advanced or production-only

Use manual helpers only when the Pages Router helper cannot express a route’s needs.

1. Use createNextjsOptimization() and getNextjsServerOptimizationData() from /server for direct request SDK control, custom server page payloads, or app-owned anonymous-id persistence.
2. Pass serverOptimizationState to a /client OptimizationRoot or OptimizationProvider only in manual server/client setups.
3. Use getServerTrackingAttributes() from /tracking-attributes only with manual resolveOptimizedEntry() results.

Caching and request policy

Integration category: Advanced or production-only

Personalized server rendering is request-specific. getServerSideProps already runs per request, so there is no static-generation trade to undo — but the state it returns is profile-specific and must not be shared.

1. Do not share serverOptimizationState across requests; it is profile-specific and tied to the request’s page event.
2. Cache raw Contentful entries by entry id, locale, environment, and include depth when your app cache policy permits — cache the fetch, not the resolved decisions.
3. Set response headers (Cache-Control) from getServerSideProps or the hosting layer so personalized HTML is not stored in shared caches unless the cache key varies on the full personalization context.

Strict consent and duplicate-event controls

Integration category: Advanced or production-only

Strict consent and duplicate-event controls are production policy work. Configure them only after your privacy, analytics, and platform owners agree on the event posture.

1. Use allowedEventTypes: [] in the browser factory when no SDK events can emit before consent.
2. Return false from server.consent while consent is unknown or denied.
3. Clear ctfl-opt-aid and your own consent or profile cookies when withdrawal must end profile continuity.
4. Keep the helper’s returned initialPageEvent by default. To override it, pass { initialPageEvent: 'emit' } as the optional second argument to getServerSideOptimizationProps — only when a route owns first page tracking outside the helper. The step-3 wrapper forwards only context, so widen it to forward options too: getOptimizationProps(context, options?) → getServerSideOptimizationProps(context, options).
5. Subscribe to states.blockedEventStream during validation to confirm the SDK blocks the events your policy expects it to block.

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 the browser factory and the server helper use the intended client id, environment, API endpoints, locale, app metadata, and log level.
• Confirm browser-exposed NEXT_PUBLIC_ variables contain only values safe to ship to the client.
• Confirm Contentful fetches use one concrete locale and include resolved optimization entries and variants.
• Confirm server.consent, browser consent (clientDefaults and factory defaults), anonymous-id persistence, and CMP or account state stay aligned across first load, navigation, opt-in, opt-out, sign-in, sign-out, and reset.
• Confirm the server path owns the initial page event and NextPagesAutoPageTracker does not duplicate it when the helper returns initialPageEvent: 'skip'.
• Confirm identifyUser(), setConsent(), and resetUser() re-resolve only the entries configured for live updates.
• Confirm entry views, clicks, hovers, flag views, page events, business events, and forwarded analytics events deliver only when policy permits them.
• Confirm baseline fallback renders automatically when variants are missing, consent is denied, links are unresolved, or CDA payloads are all-locale.
• Confirm an Experience API failure is handled the way you intend. getServerSideOptimizationProps throws on an API error, so unless you catch it in getServerSideProps the route returns a 500 rather than baseline HTML; see the state handoff.
• Confirm personalized HTML is not shared-cache safe unless the cache varies on every personalization input.

Copy this:

1
pnpm implementation:run -- nextjs-sdk_pages-router typecheck
2
pnpm implementation:run -- nextjs-sdk_pages-router lint
3
pnpm test:e2e:nextjs-sdk_pages-router

Troubleshooting

Reference implementations to compare against

• Next.js SDK Pages Router reference implementation: Working Pages Router application using getServerSideProps state handoff, app-local bound components, client takeover, live updates, consent controls, page events, entry interaction tracking, preview attachment, and Playwright E2E coverage.
• Next.js SDK App Router reference implementation: App Router equivalent using bound Server and Client Component exports.