> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

# Optimization SDK

> An introduction to the Optimization SDK suite and how you can integrate it with your setup.

## 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.

The following JavaScript-based SDKs are supported:

| 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 |
| Next.js          | `@contentful/optimization-nextjs`       | Next.js integration for SSR, hybrid rendering, and client-side tracking        | Next.js      |

To get a deeper understanding of what each SDK can do and which one to use for your setup, see [Choose the right SDK](/personalization/optimization-sdk/choose-the-right-sdk).

As a best practice to validate your setup, we recommend using [Live Events](https://www.contentful.com/help/personalization/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](/personalization/optimization-sdk/core-state-management): Explains how `CoreStateful` stores 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](/personalization/optimization-sdk/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](/personalization/optimization-sdk/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](/personalization/optimization-sdk/interaction-tracking-in-web-sdks): Explains how `@contentful/optimization-web` and `@contentful/optimization-react-web` detect browser entry views, clicks, hovers, Custom Flag views, `page` events, and custom events, including consent, profile, DOM, and delivery mechanics.
* [Profile synchronization between client and server](/personalization/optimization-sdk/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](/personalization/optimization-sdk/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.