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 pass request-scoped Experience API options as the final event-method argument:

await statelessOptimization.page(
  { profile: { id: 'profile-id' } },
  { locale: 'de-DE', preflight: false },
)
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. Consumers pass profile and request-scoped Experience options with each event call.

Common configuration

Shared Core configuration:

Stateful-only configuration:

Common api options:

In stateless environments, pass ip, locale, plainText, and preflight as the final argument to stateless event methods instead of constructor config.

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:

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