Use this guide when you need to select the Optimization SDK package or native package that matches an application runtime before following an integration guide.
Choose the highest-level SDK that matches the app runtime. Framework and native SDKs own the runtime-specific setup around providers, hooks, screen or route tracking, persistence, preview tooling, and platform defaults. Use lower-level packages only when you are building SDK layers, tooling, tests, or first-party integrations that need shared SDK primitives or raw API access.
For mixed server and browser applications, use the adapter when one exists. Next.js App Router apps
use @contentful/optimization-nextjs; the adapter composes the Node SDK on the server with the
React Web SDK on the client and exposes Next.js-specific server, client, request-handler, and
esr, and tracking-attributes subpaths. Non-Next.js server-rendered apps can combine
@contentful/optimization-node on the server with @contentful/optimization-web or
@contentful/optimization-react-web in the browser.
Angular, Vue, Svelte, Web Components, and custom browser framework apps use
@contentful/optimization-web. Nest.js and other Node server frameworks use
@contentful/optimization-node unless the app is a Next.js App Router app covered by the Next.js
adapter.
For mobile apps, choose @contentful/optimization-react-native when the mobile app is built with
JavaScript or TypeScript in React Native. Choose the native iOS or Android SDK only for
platform-native apps that can accept alpha native API and setup changes.
Public package READMEs mark the Optimization SDK Suite as pre-release alpha. Plan for breaking changes while adopting these packages.
Use this table to choose the primary package and the next integration guide:
| Reader need | Choose | Why | Next guide |
|---|---|---|---|
| Nest.js app, Node server, server function, or SSR layer outside the Next.js adapter | @contentful/optimization-node |
It provides stateless, request-scoped profile evaluation, event emission, entry resolution, and caching guidance for Node runtimes. | Integrating the Optimization Node SDK in a Node app |
| Angular, Vue, Svelte, Web Components, non-React browser app, or custom browser framework app | @contentful/optimization-web |
It owns browser consent state, anonymous ID persistence, automatic entry interaction tracking, browser event delivery, and Web Components. | Integrating the Optimization Web SDK in a web app |
| React browser app outside Next.js App Router integration | @contentful/optimization-react-web |
It wraps the Web SDK with React providers, hooks, router page tracking, optimized entry rendering, interaction tracking, and live update semantics. | Integrating the Optimization React Web SDK in a React app |
| Next.js App Router app with server-personalized first paint that stays static after hydration | @contentful/optimization-nextjs |
It uses Next.js server, client, and request-handler entrypoints for SSR personalization, request URL capture, tracking markup, browser-side tracking, and state handoff. | Integrating the Optimization Next.js SDK in a Next.js app (SSR) |
| Next.js App Router app with server-personalized first paint and browser re-resolution after hydration | @contentful/optimization-nextjs |
It keeps the personalized initial HTML and then lets the browser SDK own reactive entry resolution, live updates, route events, and preview-panel attachment. | Integrating the Optimization Next.js SDK in a Next.js app (hybrid SSR + CSR takeover) |
| React Native app | @contentful/optimization-react-native |
It provides a stateful JavaScript mobile runtime with React providers, hooks, OptimizedEntry, screen tracking, optional offline-aware delivery, and preview-panel support. |
Integrating the Optimization React Native SDK in a React Native app |
| Native iOS app built with SwiftUI that accepts alpha native API and setup changes | ContentfulOptimization Swift Package |
It provides native Swift APIs, SwiftUI helpers, persistence, networking, lifecycle handling, screen tracking, entry rendering, and preview-panel UI. | Integrating the Optimization iOS SDK in a SwiftUI app |
| Native iOS app built with UIKit or direct client ownership that accepts alpha native API and setup changes | ContentfulOptimization Swift Package |
It exposes the same native iOS runtime through direct client APIs and UIKit-compatible preview, screen tracking, and entry-rendering patterns. | Integrating the Optimization iOS SDK in a UIKit app |
| Native Android app built with Jetpack Compose that accepts alpha native API and setup changes | com.contentful.java:optimization-android |
The Android AAR includes the stateful Kotlin client, Compose UI helpers, screen tracking, entry optimization, preview controls, and offline event delivery. | Integrating the Optimization Android SDK in a Jetpack Compose app |
| Native Android app built with Android Views or XML layouts that accepts alpha native API and setup changes | com.contentful.java:optimization-android |
The same Android AAR includes Android Views helpers such as OptimizationManager, OptimizedEntryView, ScreenTracker, preview controls, and the stateful client. |
Integrating the Optimization Android SDK in an Android Views app |
@contentful/optimization-web-preview-panel to a Web SDK or React
Web SDK integration when the browser app needs author preview overrides. It attaches to an
existing Contentful client and Web SDK instance; it is not a standalone SDK.@contentful/optimization-core when building or maintaining an SDK layer that
needs the shared state machine, event builders, queues, resolvers, interceptors, or preview
support. Application integrations start with a platform SDK.@contentful/optimization-api-client when building SDK layers, tooling,
tests, or first-party integrations that need direct Experience API or Insights API transport
without SDK state, consent handling, event builders, entry resolution, tracking, or platform
defaults.@contentful/optimization-api-schemas when you need shared runtime
validation schemas or inferred TypeScript types for Contentful CDA, Experience API, and Insights
API payloads.@contentful/optimization-js-bridge is internal bridge
infrastructure for the native iOS and Android SDKs. Native applications use the
ContentfulOptimization Swift Package or com.contentful.java:optimization-android instead.After choosing the package, follow the matching guide: