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.

[!IMPORTANT]

Upgrading from v1? Follow the v1-to-v2 migration guide before changing package versions.

Getting started

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

pnpm add @contentful/optimization-node

Add contentful too when the SDK will use your app-owned contentful.js client for managed entry fetching.

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

import ContentfulOptimization from '@contentful/optimization-node'

Create the SDK once per module or process, then bind consent and request context in each route:

const optimization = new ContentfulOptimization({
  spaceId: 'your-space-id',
  environment: 'master',
  locale: 'en-US',
})

function appPolicyAllowsOptimizationEvent(req: { cookies?: Record<string, string> }): boolean {
  return req.cookies?.['app-personalization-consent'] === 'granted'
}

async function renderRequest(
  req: { cookies?: Record<string, string>; headers: { 'accept-language'?: string } },
  profileId: string,
) {
  const appLocale = getAppLocale(req)
  const requestOptimization = optimization.forRequest({
    consent: {
      events: appPolicyAllowsOptimizationEvent(req),
      persistence: appPolicyAllowsOptimizationEvent(req),
    },
    locale: appLocale,
    eventContext: { locale: appLocale },
    profileId,
  })

  const { accepted, data } = await requestOptimization.page()

  return accepted ? data : undefined
}

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. For cross-SDK consent guidance, see Consent management in the Optimization SDK Suite.

Common api options:

Request-scoped Experience options belong in experienceOptions when creating the request-bound client:

Configure a shared default with api.location, then override it per incoming request with experienceOptions.location:

const optimization = new ContentfulOptimization({
  spaceId: 'your-space-id',
  api: { location: { countryCode: 'DE', city: 'Berlin' } },
})
const requestOptimization = optimization.forRequest({
  consent: true,
  experienceOptions: { location: { countryCode: 'FR', city: 'Paris' } },
})
await requestOptimization.page()

The request value replaces the whole default object; it does not merge fields. Pass experienceOptions: { location: {} } to replace the configured default with an explicit empty location instead of API geolocation. Event context.location takes precedence over matching request fields. An empty location does not clear an existing profile location, and request location does not lock location across later requests. See Location inputs and profile updates.

Request-scoped Insights options belong in insightsOptions:

Use the request-scoped top-level locale on forRequest() as the promoted path for localized Experience API responses and default event context. experienceOptions.locale remains available as an advanced low-level pass-through when locale is not supplied. If both are provided, request locale wins.

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

Choose the application Contentful locale in your router, i18n layer, or request policy. Pass that value directly to Contentful CDA requests, and pass the same value to forRequest({ locale: appLocale }) when Experience API responses and event context should use the same language. Merge tags that reference localized profile fields such as location.city and location.country then resolve in a language consistent with the rendered content. See Locale handling in the Optimization SDK Suite for the full locale model.

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, bind application-owned consent state with forRequest(), then call page(), identify(), screen(), track(), or sticky trackView() on the returned request object:

import type { Request } from 'express'

app.get('/products/:slug', async (req, res) => {
  const appLocale = getAppLocale(req)
  const requestOptimization = optimization.forRequest({
    consent: {
      events: appPolicyAllowsOptimizationEvent(req),
      persistence: appPolicyAllowsOptimizationEvent(req),
    },
    locale: appLocale,
    eventContext: {
      locale: appLocale,
    },
    profileId: req.cookies.profileId,
  })
  const { accepted, data: optimizationData } = await requestOptimization.page({
    properties: { path: req.path },
  })

  if (accepted && requestOptimization.canPersistProfile && optimizationData?.profile.id) {
    persistProfileId(res, optimizationData.profile.id)
  }

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

For default-on application policies that do not render an end-user consent UI, replace the request-specific consent lookup with accepted consent:

const requestOptimization = optimization.forRequest({
  consent: { events: true, persistence: true },
  locale: appLocale,
  eventContext: { locale: appLocale },
  profile,
})

Node SDK event calls fail closed except for the default pre-consent allowlist, identify and page. Those allowlisted events are sent with context.gdpr.isConsentGiven: false when request event consent is not granted. Pass allowedEventTypes: [] to require strict opt-in for all stateless event methods.

In stateless runtimes, non-sticky trackView, trackClick, trackHover, and trackFlagView require a full Profile supplied through forRequest({ profile }) or returned by an Experience call on the same request client. Use profileId for Experience API continuity.

For custom integrations that need an event payload before submission, use the request client's eventBuilder. It exposes buildIdentify, buildPageView, buildScreenView, and buildTrack with request event context and locale defaults. In this example, appConsent, appLocale, appUserAgent, and appUserId come from your application's request and identity handling:

const requestOptimization = optimization.forRequest({
  consent: appConsent,
  locale: appLocale,
  eventContext: { userAgent: appUserAgent },
})
const identifyEvent = requestOptimization.eventBuilder.buildIdentify({ userId: appUserId })

Construction does not send the event, check request consent, invoke interceptors, or update the request profile or selections. Built events use the shared builder's context.gdpr.isConsentGiven, which is false in the Node SDK, even when request consent is granted. Sending identifyEvent through a low-level API does not automatically apply request consent or SDK submission processing. For normal submission, use request-bound identify(), page(), screen(), or track(). The singleton's optimization.eventBuilder remains unbound to any request.

Content resolution

When a contentful.js client is available, prefer SDK-managed fetching by entry ID or content type and slug. Configure the client once, then call fetchOptimizedEntry() on a request-bound client after an accepted Experience API call. forRequest() clients use the latest selected optimizations when omitted; singleton calls require explicit selectedOptimizations.

const optimization = new ContentfulOptimization({
  spaceId: 'space-id',
  contentful: { client: contentfulClient },
  environment: 'master',
  locale: appLocale,
})

const requestOptimization = optimization.forRequest({ consent: true, profile })
await requestOptimization.page()
const { baselineEntry, entry } = await requestOptimization.fetchOptimizedEntry({
  contentType: 'productPage',
  slug: req.params.slug,
  entryQuery: { locale: appLocale },
})

Use fetchContentfulEntries() or prefetchManagedEntries() when a route knows several managed entry sources. A slug source accepts slugField when the content model does not use the default slug field. Slug lookup enforces its content-type, field selector, and two-result uniqueness limit after merging entryQuery; successful resolution uses the fetched entry's sys.id. Slug handoffs nest the normalized descriptor under managedEntry and retain that ID in entryId. Equivalent ID sources retain same-query batching and 100-ID chunking.

If your application already fetched the baseline entry, keep using the manual resolver:

const pageResult = await requestOptimization.page()
const resolvedEntry = optimization.resolveOptimizedEntry(
  baselineEntry,
  pageResult.accepted ? pageResult.data.selectedOptimizations : undefined,
)

Use one CDA locale in either path. For localized apps, configure your application locale. A request-bound client uses forRequest({ locale: appLocale }) as the managed Contentful query locale when neither contentful.defaultQuery nor the per-call query sets locale. Pass the same value to app-owned Contentful CDA requests and to forRequest({ locale: appLocale }) when MergeTags that read localized profile fields match the rendered entry language. Do not pass all-locale CDA responses from withAllLocales or locale=*; the resolver expects direct single-locale field values. See Entry personalization and variant resolution for the entry contract and Locale handling in the Optimization SDK Suite for request locale behavior.

Use getMergeTagValue() for Contentful Rich Text merge tags and getFlag() for Custom Flags. If a merge tag references localized profile fields such as location.city or location.country, its resolved value follows the localized profile data returned by the Experience API. 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 or with the SDK-managed entry cache, not profile-evaluated SDK event results. Use clearContentfulEntryCache() when an SDK instance must drop cached CDA entries.

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
   

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