Contentful Personalization & Analytics

Optimization Core SDK

The Optimization Core SDK encapsulates all platform-agnostic functionality and business logic. All other SDKs descend from the Core SDK.

Getting Started

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

pnpm install @contentful/optimization-core
Copy

Import either the stateful or stateless Core class, depending on the target environment; both CJS and ESM module systems are supported, ESM preferred:

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

Configure and initialize the Core SDK:

const optimization = new CoreStateful({ clientId: 'abc123' })
// or
const optimization = new CoreStateless({ clientId: 'abc123' })
Copy

Working with Stateless Core

The CoreStateless class is intended to be used as the basis for SDKs that would run in stateless environments such as Node-based servers and server-side functions in meta-frameworks such as Next.js.

In stateless environments, Core will not maintain any internal state, which includes user consent. These concerns should be handled by consumers to fit their specific architectural and design specifications.

Working with Stateful Core

The CoreStateful class is intended to be used as the basis for SDKs that would run in stateful environments such as Web front-ends and mobile applications (via JavaScript runtime containers).

In stateful environments, Core maintains state internally for consent, an event stream, and profile-related data that is commonly obtained from requests to the Experience API. These states are exposed externally as read-only observables.

Configuration

Top-level Configuration Options

The following configuration options apply only in stateful environments:

Configuration method signatures:

• getAnonymousId: () => string | undefined
• onEventBlocked: (event: BlockedEvent) => void

Analytics Options

The following configuration options apply only in stateful environments:

Configuration method signatures:

• beaconHandler: (url: string | URL, data: BatchInsightsEventArray) => boolean

• queuePolicy:

  {
    baseBackoffMs?: number,
    maxBackoffMs?: number,
    jitterRatio?: number,
    maxConsecutiveFailures?: number,
    circuitOpenMs?: number,
    onFlushFailure?: (context: QueueFlushFailureContext) => void,
    onCircuitOpen?: (context: QueueFlushFailureContext) => void,
    onFlushRecovered?: (context: QueueFlushRecoveredContext) => void
  }
  Copy

  Supporting callback payloads:

  type QueueFlushFailureContext = {
    consecutiveFailures: number
    queuedBatches: number
    queuedEvents: number
    retryDelayMs: number
  }
  
  type QueueFlushRecoveredContext = {
    consecutiveFailures: number
  }
  Copy

  Notes:

  • Invalid numeric values fall back to defaults.
  • jitterRatio is clamped to [0, 1].
  • maxBackoffMs is normalized to be at least baseBackoffMs.
  • Failed flush attempts include both false responses and thrown send errors.

Event Builder Options

Event builder options should only be supplied when building an SDK on top of Core or any of its descendent SDKs.

The channel option may contain one of the following values:

• web
• mobile
• server

The following configuration options apply only in stateful environments:

Configuration method signatures:

• getLocale: () => string | undefined

• getPageProperties:

  () => {
    path: string,
    query: Record<string, string>,
    referrer: string,
    search: string,
    title?: string,
    url: string
  }
  Copy

• getUserAgent: () => string | undefined

Fetch Options

Fetch options allow for configuration of a Fetch API-compatible fetch method and the retry/timeout logic integrated into the Optimization API Client. Specify the fetchMethod when the host application environment does not offer a fetch method that is compatible with the standard Fetch API in its global scope.

Configuration method signatures:

• fetchMethod: (url: string | URL, init: RequestInit) => Promise<Response>
• onFailedAttempt and onRequestTimeout: (options: FetchMethodCallbackOptions) => void

Personalization Options

The following configuration options apply only in stateful environments:

Configuration method signatures:

• queuePolicy:

  {
    maxEvents?: number,
    onDrop?: (context: PersonalizationOfflineQueueDropContext) => void,
    flushPolicy?: {
      baseBackoffMs?: number,
      maxBackoffMs?: number,
      jitterRatio?: number,
      maxConsecutiveFailures?: number,
      circuitOpenMs?: number,
      onFlushFailure?: (context: QueueFlushFailureContext) => void,
      onCircuitOpen?: (context: QueueFlushFailureContext) => void,
      onFlushRecovered?: (context: QueueFlushRecoveredContext) => void
    }
  }
  Copy

  Supporting callback payloads:

  type PersonalizationOfflineQueueDropContext = {
    droppedCount: number
    droppedEvents: ExperienceEventArray
    maxEvents: number
    queuedEvents: number
  }
  
  type QueueFlushFailureContext = {
    consecutiveFailures: number
    queuedBatches: number
    queuedEvents: number
    retryDelayMs: number
  }
  
  type QueueFlushRecoveredContext = {
    consecutiveFailures: number
  }
  Copy

  Notes:

  • Default maxEvents is 100.
  • If the queue is full while offline, oldest events are dropped first.
  • onDrop is best-effort; callback errors are swallowed.
  • flushPolicy uses the same normalization semantics as analytics.queuePolicy.

Core Methods

The methods in this section are available in both stateful and stateless Core classes. However, be aware that there are some minor differences in argument usage between stateful and stateless Core implementations.

Arguments marked with an asterisk (*) are always required.

Personalization Data Resolution Methods

getCustomFlag

Get the specified Custom Flag's value from the provided changes array, or from the current internal state in stateful implementations.

Arguments:

• name*: The name/key of the Custom Flag
• changes: Changes array

Returns:

• The resolved value for the specified Custom Flag, or undefined if it cannot be found.

personalizeEntry

Resolve a baseline Contentful entry to a personalized variant using the provided selected personalizations, or from the current internal state in stateful implementations.

Type arguments:

• S: Entry skeleton type
• M: Chain modifiers
• L: Locale code

Arguments:

• entry*: The entry to personalize
• personalizations: Selected personalizations

Returns:

• The resolved personalized entry variant, or the supplied baseline entry if baseline is the selected variant or a variant cannot be found.

getMergeTagValue

Resolve a "Merge Tag" to a value based on the current (or provided) profile. A "Merge Tag" is a special Rich Text fragment supported by Contentful that specifies a profile data member to be injected into the Rich Text when rendered.

Arguments:

• embeddedNodeEntryTarget*: The merge tag entry node to resolve
• profile: The user profile

Personalization and Analytics Event Methods

Only the following methods may return an OptimizationData object:

• identify
• page
• screen
• track
• trackComponentView (when payload.sticky is true)

trackComponentClick and trackFlagView return no data. When returned, OptimizationData contains:

• changes: Currently used for Custom Flags
• personalizations: Selected personalizations for the profile
• profile: Profile associated with the evaluated events

identify

Identify the current profile/visitor to associate traits with a profile.

Arguments:

• payload*: Identify event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

page

Record a personalization page view.

Arguments:

• payload*: Page view event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

screen

Record a personalization screen view.

Arguments:

• payload*: Screen view event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

track

Record a personalization custom track event.

Arguments:

• payload*: Track event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

trackComponentView

Record an analytics component view event. When the payload marks the component as "sticky", an additional personalization component view is recorded. This method only returns OptimizationData when the component is marked as "sticky".

Arguments:

• payload*: Component view event builder arguments object, including an optional profile property with a PartialProfile value that requires only an id

trackComponentClick

Record an analytics component click event.

Returns:

• void

Arguments:

• payload*: Component click event builder arguments object

trackFlagView

Track a feature flag view via analytics. This is functionally the same as a non-sticky component view event.

Returns:

• void

Arguments:

• payload*: Component view event builder arguments object

Stateful-only Core Methods

consent

Updates the user consent state.

Arguments:

• accept: A boolean value specifying whether the user has accepted (true) or denied (false)

reset

Resets all internal state except consent. This method expects no arguments and returns no value.

flush

Flushes queued analytics and personalization events. This method expects no arguments and returns a Promise<void>.

destroy

Releases singleton ownership for stateful runtime usage. This is intended for explicit teardown paths, such as tests or hot-reload workflows. This method expects no arguments and returns no value.

registerPreviewPanel (preview tooling only)

Registers a preview consumer object and exposes internal signal references used by first-party preview tooling.

Arguments:

• previewPanel: Required object that receives symbol-keyed signal bridge values

Returns:

• void

Bridge symbols:

• PREVIEW_PANEL_SIGNALS_SYMBOL: key used to expose internal signals
• PREVIEW_PANEL_SIGNAL_FNS_SYMBOL: key used to expose internal signalFns

Example:

import {
  PREVIEW_PANEL_SIGNAL_FNS_SYMBOL,
  PREVIEW_PANEL_SIGNALS_SYMBOL,
  type PreviewPanelSignalObject,
} from '@contentful/optimization-core'

const previewBridge: PreviewPanelSignalObject = {}
optimization.registerPreviewPanel(previewBridge)

const signals = previewBridge[PREVIEW_PANEL_SIGNALS_SYMBOL]
const signalFns = previewBridge[PREVIEW_PANEL_SIGNAL_FNS_SYMBOL]
Copy

Core States (CoreStateful only)

states is available on CoreStateful and exposes signal-backed observables for runtime state.

Available state streams:

• consent: Current consent state (boolean | undefined)
• blockedEventStream: Latest blocked-call metadata (BlockedEvent | undefined)
• eventStream: Latest emitted analytics/personalization event (AnalyticsEvent | PersonalizationEvent | undefined)
• flags: Resolved Custom Flags (Flags | undefined)
• canPersonalize: Whether personalization selections are available (boolean; personalizations !== undefined)
• profile: Current profile (Profile | undefined)
• personalizations: Current selected personalizations (SelectedPersonalizationArray | undefined)
• previewPanelAttached: Preview panel attachment state (boolean)
• previewPanelOpen: Preview panel open state (boolean)

Each observable provides:

• current: Deep-cloned snapshot of the latest value
• subscribe(next): Immediately emits current, then emits future updates
• subscribeOnce(next): Emits the first non-nullish value, then auto-unsubscribes

current and callback payloads are deep-cloned snapshots, so local mutations do not affect Core's internal signal state.

Update behavior:

• blockedEventStream updates whenever a call is blocked by consent guards.
• eventStream updates when a valid event is accepted for send/queue.
• flags, profile, and personalizations update from Experience API responses.
• canPersonalize updates whenever personalizations becomes defined or undefined.
• consent updates from defaults and optimization.consent(...).
• previewPanelAttached and previewPanelOpen are controlled by preview tooling and are preserved across reset().

Example: read the latest snapshot synchronously:

const profile = optimization.states.profile.current
if (profile) console.log(`Current profile: ${profile.id}`)
Copy

Example: subscribe and clean up:

const sub = optimization.states.profile.subscribe((profile) => {
  if (!profile) return
  console.log(`Profile ${profile.id} updated`)
})

// later (component unmount / teardown)
sub.unsubscribe()
Copy

Example: wait for first available profile:

optimization.states.profile.subscribeOnce((profile) => {
  console.log(`Profile ${profile.id} loaded`)
})
Copy

Interceptors

Interceptors may be used to read and/or modify data flowing through the Core SDK.

Life-cycle Interceptors

• event: Intercepts an event's data before it is queued and/or emitted
• state: Intercepts state data retrieved from an Experience API call before updating the SDK's internal state

Example interceptor usage:

optimization.interceptors.event((event) => {
  event.properties.timestamp = new Date().toISOString()
})
Copy