Contentful Personalization & Analytics

Optimization Core SDK

The Optimization Core SDK owns the platform-agnostic optimization state machine, event builders, queues, resolvers, and interceptors used by the application-facing SDKs. Web, React Web, Node, React Native, and native bridge layers build on this package.

We recommend starting application code with a platform SDK rather than Core directly. Use this README when building or maintaining SDK layers, and use Choosing the right SDK when deciding which application-facing package belongs in an integration. 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-core
Copy

Choose the stateful or stateless Core class based on the runtime layer you are building:

import { CoreStateful, CoreStateless } from '@contentful/optimization-core'

const statefulOptimization = new CoreStateful({ clientId: 'your-client-id' })
const statelessOptimization = new CoreStateless({ clientId: 'your-client-id' })
Copy

Stateful runtimes own durable in-process SDK state. Stateless runtimes bind request-scoped consent, profile state, event context, and Experience API options before calling event methods:

const requestOptimization = statelessOptimization.forRequest({
  consent: true,
  locale: 'en-US',
  eventContext: { locale: 'en-US' },
  experienceOptions: { preflight: false },
  profile: { id: 'profile-id' },
})

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

When to use this package

Use @contentful/optimization-core when you are building or maintaining an SDK layer that needs the shared optimization state machine, event builders, queueing, resolvers, or interceptors. Most application code uses a platform SDK such as Web, React Web, Node, or React Native instead of depending on Core directly.

Core variants

Stateful Core

CoreStateful is the basis for SDKs that run in stateful JavaScript runtimes such as browsers, mobile JavaScript containers, and native bridge runtimes. It maintains consent, profile, selected optimization, flag, event-stream, blocked-event, and preview-panel state as read-only observables.

Stateless Core

CoreStateless is the basis for SDKs that run in stateless environments such as Node servers and server-side functions. It does not store consent or profile state between requests. Consumers call forRequest() to create a request-bound event client with the consent, profile, event context, and Experience options for that one incoming request.

Common configuration

Shared Core configuration:

Consent and event configuration:

Core itself fails closed before consent. Platform SDKs set runtime-specific defaults for the event types that make sense in that runtime, such as browser identify/page, server identify/page, and mobile identify/screen.

Stateful-only configuration:

Persistence consent controls durable profile-continuity storage for SDKs with runtime storage: profile, anonymous ID, changes, and selected optimization caches. Event consent, stored consent decisions, and debug state are tracked separately.

Common api options:

When plainText is omitted, single-profile Experience mutation/event requests use text/plain. Pass plainText: false to send JSON. Experience batch profile updates still default to JSON.

In stateless environments, pass ip, locale, plainText, and preflight as experienceOptions when creating the request-bound client instead of constructor config. Pass request-specific Insights API options, such as a last-chance beacon sender, as insightsOptions.

Core-backed stateful SDKs can accept an initial top-level locale and runtime setLocale(locale) calls. They expose that SDK Experience API and default event locale through the live locale getter and states.locale observable. Stateless server SDKs should pass the request-scoped SDK locale as forRequest({ locale }); advanced callers can still pass experienceOptions.locale when no request locale is supplied.

Applications own Contentful CDA locale selection and pass that locale directly to their Contentful client. For the full locale model, see Locale handling in the Optimization SDK Suite.

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 Core SDK reference.

Package surface

Core exposes reusable primitives for SDK layers:

When a contentful.js client is available, prefer SDK-managed fetching. Configure contentful: { client, defaultQuery?, cache? }, then call fetchContentfulEntry(entryId, query?), fetchContentfulEntries(entries), prefetchManagedEntries(entries), or fetchOptimizedEntry(entryId, options?). Managed calls merge defaultQuery, per-entry query overrides, SDK locale fallback, and include: 10, then cache entries per SDK instance by default. For multiple uncached entries with the same normalized query, Core calls client.getEntries({ 'sys.id[in]': ids, limit: ids.length }), splitting large batches into 100-ID chunks. Same-tick uncached single-entry calls can join the same batch. Results preserve descriptor order and duplicates. Set contentful.cache: false to disable the cache or call clearContentfulEntryCache() to clear it. resolveOptimizedEntry() remains the manual path for entries the app already fetched. Stateful Core uses the current selectedOptimizations when omitted, request-bound stateless clients use the latest accepted Experience selections and request locale fallback for managed Contentful fetches, and root stateless callers pass explicit selectedOptimizations.

Do not pass all-locale CDA responses from withAllLocales or locale=*; optimization fields such as fields.nt_experiences and fields.nt_variants must be direct single-locale field values. See Entry personalization and variant resolution for the entry contract and Locale handling in the Optimization SDK Suite for the broader locale model.

Custom entry-source adapters

@contentful/optimization-core/entry-source is an advanced subpath for custom JavaScript runtime or framework adapters that cannot use an official Web, React Web, React Native, Node, or native SDK surface. It is not part of the root Core API posture and is not the preferred path for application integrations.

Import OptimizedEntrySourceController when an adapter accepts either a direct baselineEntry or an entryId that must be fetched through an SDK-managed contentful.js client. The controller owns the baselineEntry versus entryId source lifecycle, entryId + entryQuery fetch keying, SDK readiness/loading/error snapshots, stale request protection, and disconnect() cleanup. createOptimizedEntryLoadingEntry(entryId) creates a stable placeholder Contentful entry for adapter loading states.

The entry-source controller does not own rendering, variant resolution, tracking, consent, Experience API calls, or Contentful client creation. After a snapshot contains baselineEntry, the adapter still calls resolveOptimizedEntry(), renders the result, and wires any runtime-specific tracking.

The generated reference owns method arguments, return types, callback payload shapes, and inherited members. Keep this README focused on package role and maintainer orientation.

Preview support

Preview-panel helpers live under the internal preview-support entry. They are used by first-party preview surfaces to register preview state bridges, apply optimization overrides, and map Contentful entries for local authoring workflows.

Application code must not use preview support directly unless it is building a first-party preview surface.

Related

• Choosing the right SDK - package selection guidance for application integrations
• Core SDK generated reference - exported API reference
• Optimization Web SDK - browser SDK built on CoreStateful
• Optimization Node SDK - server SDK built on CoreStateless
• Optimization React Native SDK - mobile SDK built on CoreStateful
• Core preview support - internal preview helper entry