Contentful Personalization & Analytics

Optimization Node SDK

The Optimization Node SDK implements stateless server-side optimization behavior on top of the Optimization Core SDK. Use it for server rendering, server functions, and Node services that need request-scoped profile evaluation or event emission.

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

Getting started

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

pnpm install @contentful/optimization-node
Copy

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

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

Create the SDK once per module or process, then pass request-scoped Experience options to event methods inside each incoming request:

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

const requestOptions = { locale: 'en-US' }
const optimizationData = await optimization.page({ profile }, requestOptions)
Copy

When to use this package

Use @contentful/optimization-node for server-side rendering, server functions, and Node services that need stateless profile evaluation or event emission. Use the Web or React Web SDK alongside it when browser-side consent, anonymous ID persistence, automatic interaction tracking, or live updates are part of the same application.

Common configuration

The Node SDK is stateless. It does not maintain consent, profile, or browser persistence state between requests.

Common api options:

Request-scoped Experience options belong in the final argument to stateless event methods:

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

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

Core workflows

Request-scoped events

Build event context from the incoming request, then call page(), identify(), screen(), track(), or sticky trackView() when optimization data is needed:

app.get('/products/:slug', async (req, res) => {
  const optimizationData = await optimization.page(
    {
      profile: { id: req.cookies.profileId },
      properties: { path: req.path },
    },
    { locale: req.acceptsLanguages()[0] ?? 'en-US' },
  )

  res.render('product', { optimizationData })
})
Copy

In stateless runtimes, Insights-backed methods require a profile for delivery. Non-sticky trackView, trackClick, trackHover, and trackFlagView require payload.profile.id.

Content resolution

Fetch Contentful entries in your application layer, then resolve variants with returned optimization data:

const resolvedEntry = optimization.resolveOptimizedEntry(
  baselineEntry,
  optimizationData?.selectedOptimizations,
)
Copy

Use getMergeTagValue() for Contentful Rich Text merge tags and getFlag() for Custom Flags. The Node SDK is stateless, so getFlag() does not automatically emit flag-view tracking.

Caching guidance

Cache raw Contentful delivery payloads in your application layer, not profile-evaluated SDK event results.

The Node SDK integration guide covers request context, profile persistence, Contentful entry resolution, and hybrid Node + browser setups in detail.

Development harness

The package-local dev harness runs from packages/node/node-sdk/dev/ and reads .env from this package directory.

1. Start from .env.example and create or update packages/node/node-sdk/.env.

2. Prefer the repo-standard PUBLIC_... variable names shown in .env.example.

3. Start the harness from the repo root:

   pnpm --filter @contentful/optimization-node dev
   Copy

Related

• Integrating the Optimization Node SDK in a Node app - step-by-step server-side integration guide
• Node SDK generated reference - exported API reference
• Node reference implementation - server-rendered implementation using request-scoped SDK calls
• Node + Web reference implementation - hybrid SSR and browser implementation
• Optimization Web SDK - browser SDK used when the same application also needs client-side consent, persistence, tracking, or live updates