Optimization SDK
Overview
The Optimization SDK suite is an open-source developer kit built to serve both Contentful Personalization and Contentful Analytics across multiple platforms and frameworks.
Important:
The Optimization SDK is currently in beta. For more information, reach out to your Sales representative.
The beta includes the following JavaScript-based SDKs:
| Name | npm name | Purpose | Runtime |
|---|---|---|---|
| Core SDK | @contentful/optimization-core |
Platform-agnostic foundation | Any |
| Web SDK | @contentful/optimization-web |
Stateful browser SDK | Browser |
| Node SDK | @contentful/optimization-node |
Stateless server SDK | Node.js |
| React Web SDK | @contentful/optimization-react-web |
React integration layer with providers, hooks, components, and router adapters | React (web) |
| React Native SDK | @contentful/optimization-react-native |
Mobile SDK with offline-aware event handling | React Native |
To get a deeper understanding of what each SDK can do and which one to use for your setup, see Choose the right SDK.
As a best practice to validate your setup, we recommend using Live Events in the Contentful web app to verify that page, track, and component events are flowing correctly.
Useful resources
To understand how SDK features work, why they behave a certain way, or how the implementation makes runtime decisions, we recommend reading the following articles:
- Core state management: Explains how
CoreStatefulstores internal state using signals, why that state is protected from outside interference, and which consumer-facing surfaces are the correct way to observe and influence state. - Entry personalization and variant resolution: Explains how the SDK resolves a Contentful baseline entry to the selected entry variant, including data model expectations, fallback behavior, resolution paths, and preview overrides.
- Interaction tracking in Node and stateless environments: Explains what the Node SDK can track from a stateless server runtime, when browser observation is required, how the Web SDK can track server-generated HTML without owning personalization, and what a manual client-side tracking implementation must replace.
- Interaction tracking in Web SDKs: Explains how
@contentful/optimization-weband@contentful/optimization-react-webdetect browser entry views, clicks, hovers, Custom Flag views,pageevents, and custom events, including consent, profile, DOM, and delivery mechanics. - Profile synchronization between client and server: Explains how profile identity, profile data, cookies, browser storage, and Experience API responses work together when Node and Web SDK runtimes share a visitor journey.
- React Native SDK interaction tracking mechanics: Explains how the React Native SDK observes, gates, and emits tracking events, covering event types, the viewport state machine, default thresholds, consent gating, scroll context, screen tracking paths, and the configuration resolution order
