> 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/developers/docs/_mcp/server. # Choose the right SDK > A guide to help you decide which SDK is best for your setup. ## Overview 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. ## Recommendation 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. A Next.js App Router app installs `@contentful/optimization-nextjs`; `/app-router/server` is its normal Server Component import subpath. `/app-router/client` owns the Client Component binder and the direct `NextAppAutoPageTracker` export; use its binder when the app needs bound Client Components. These are entrypoints in one package, not separate packages to install. Next.js Pages Router apps install the same package and use its `/pages-router` entrypoints. 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. After choosing App Router or Pages Router, use [Render personalized Next.js routes with static, ISR, and edge handoffs](/personalization/optimization-sdk/render-personalized-nextjs-routes/) when individual Next.js routes need static generation, App Router Cache Components, Pages Router ISR, Edge runtime route handlers, or analytics-only handoff patterns. 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 or Pages Router app covered by the Next.js adapter. For JavaScript SDKs, pass an existing app-owned `contentful.js` client when the SDK should manage entry fetching. Keep manual fetching when the app needs full delivery control. Use Core only when building a custom runtime or framework adapter and no official package fits. For schema imports in a JavaScript app, use the `/api-schemas` pass-through from the application SDK that the app already installs. If no application SDK fits, use `@contentful/optimization-api-client/api-schemas` for Experience API and Insights API schemas and validation helpers. Use `@contentful/optimization-core/api-schemas` when you also need Contentful Content Delivery API (CDA) schemas; Core includes those schemas and passes through the API Client schema surface. 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 for platform-native apps. ## Decision table 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 request-scoped profile evaluation, event emission, managed fetching and prefetching by ID or content type and slug, entry resolution, and Node caching guidance. | [Integrate the Optimization Node SDK in a Node app](/personalization/optimization-sdk/integrate-the-node-sdk-into-a-node-app/) | | Angular, Vue, Svelte, Web Components, non-React browser app, or custom browser framework app | `@contentful/optimization-web` | It owns browser consent, anonymous ID persistence, managed fetching and prefetching by ID or content type and slug, interaction tracking, event delivery, and Web Components. | [Integrate the Optimization Web SDK in a web app](/personalization/optimization-sdk/integrate-the-web-sdk-in-a-web-app/) | | React browser app outside Next.js integration | `@contentful/optimization-react-web` | It adds React providers, hooks, route tracking, optimized entry rendering from `entryId` or a content-type/slug `managedEntry`, interaction tracking, and live updates to the Web SDK. | [Integrate the Optimization React Web SDK in a React app](/personalization/optimization-sdk/integrate-the-react-web-sdk-in-a-react-app/) | | Next.js App Router app with server-personalized first paint and browser re-resolution after hydration | `@contentful/optimization-nextjs` | Use `/app-router/server` for Server Components; `/app-router/client` owns the client binder and direct App Router tracker. | [Integrate the Optimization Next.js SDK in a Next.js App Router app](/personalization/optimization-sdk/integrate-the-optimization-sdk-in-a-nextjs-app-router-app/) | | Next.js Pages Router app with `getServerSideProps` personalization | `@contentful/optimization-nextjs/pages-router` plus `/pages-router/server` | Its `/pages-router` components and `/pages-router/server` request handoff helper pass browser handoff through `pageProps` and avoid duplicate initial page events. | [Integrate the Optimization Next.js SDK in a Next.js Pages Router app](/personalization/optimization-sdk/integrate-the-optimization-sdk-in-a-nextjs-pages-router-app/) | | Custom JavaScript runtime or framework adapter where no official SDK fits | `@contentful/optimization-core` plus `@contentful/optimization-core/entry-source` | Core provides shared state and resolution. The entry-source subpath manages `baselineEntry`, `entryId`, or content-type/slug `managedEntry`; adapters own rendering, tracking, and runtime policy. | [Build a custom JavaScript Optimization adapter](/personalization/optimization-sdk/build-a-custom-javascript-optimization-adapter/) | | 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. | [Integrate the Optimization React Native SDK in a React Native app](/personalization/optimization-sdk/integrate-the-react-native-sdk-in-a-react-native-app/) | | Native iOS app built with SwiftUI | `ContentfulOptimization` Swift Package | It provides native Swift APIs, SwiftUI helpers, persistence, networking, lifecycle handling, screen tracking, entry rendering, and preview-panel UI. | [Integrate the Optimization iOS SDK in a SwiftUI app](/personalization/optimization-sdk/integrate-the-optimization-ios-sdk-in-a-swiftui-app/) | | Native iOS app built with UIKit or direct client ownership | `ContentfulOptimization` Swift Package | It exposes the same native iOS runtime through direct client APIs and UIKit-compatible preview, screen tracking, and entry-rendering patterns. | [Integrate the Optimization iOS SDK in a UIKit app](/personalization/optimization-sdk/integrate-the-optimization-ios-sdk-in-a-uikit-app/) | | Native Android app built with Jetpack Compose | `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. | [Integrate the Optimization Android SDK in a Jetpack Compose app](/personalization/optimization-sdk/integrate-the-optimization-android-sdk-in-a-compose-app/) | | Native Android app built with Android Views or XML layouts | `com.contentful.java:optimization-android` | The same Android AAR includes Android Views helpers such as `OptimizationManager`, `OptimizedEntryView`, `ScreenTracker`, preview controls, and the stateful client. | [Integrate the Optimization Android SDK in an Android Views app](/personalization/optimization-sdk/integrate-the-optimization-android-sdk-in-a-views-app/) | ## Alternatives * **Browser preview panel** - Add `@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 a Web SDK instance and reads definitions from an existing Contentful client or pre-fetched audience and experience entries; it is not a standalone SDK. * **Core SDK** - Use `@contentful/optimization-core` when building or maintaining an SDK layer that needs the shared state machine, event builders, queues, resolvers, interceptors, or preview support. Use `@contentful/optimization-core/entry-source` only when building an adapter that must manage `baselineEntry`, `entryId`, or content-type/slug `managedEntry` sources before resolution. Application integrations start with a platform SDK. * **API client** - Use `@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. * **API schemas** - In a JavaScript application, use the installed application SDK's `/api-schemas` pass-through. For lower-level consumers, use `@contentful/optimization-api-client/api-schemas` for Experience API and Insights API schemas and validation helpers. Use `@contentful/optimization-core/api-schemas` for the aggregate surface, including Contentful CDA schemas and the API Client schema pass-throughs. `@contentful/optimization-api-schemas` is a deprecated compatibility facade and is not recommended for new integrations. * **Native JavaScript bridge** - `@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. ## Follow-up guides After choosing the package, follow the matching guide: | Runtime or task | Guide | | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Node servers and server-side rendering | [Integrate the Optimization Node SDK in a Node app](/personalization/optimization-sdk/integrate-the-node-sdk-into-a-node-app/) | | Browser apps without React | [Integrate the Optimization Web SDK in a web app](/personalization/optimization-sdk/integrate-the-web-sdk-in-a-web-app/) | | React browser apps | [Integrate the Optimization React Web SDK in a React app](/personalization/optimization-sdk/integrate-the-react-web-sdk-in-a-react-app/) | | Next.js App Router apps | [Integrate the Optimization Next.js SDK in a Next.js App Router app](/personalization/optimization-sdk/integrate-the-optimization-sdk-in-a-nextjs-app-router-app/) | | Next.js Pages Router apps | [Integrate the Optimization Next.js SDK in a Next.js Pages Router app](/personalization/optimization-sdk/integrate-the-optimization-sdk-in-a-nextjs-pages-router-app/) | | Next.js static, ISR-style, Edge runtime, and analytics-only routes | [Render personalized Next.js routes with static, ISR, and edge handoffs](/personalization/optimization-sdk/render-personalized-nextjs-routes/) | | Custom JavaScript adapter | [Build a custom JavaScript Optimization adapter](/personalization/optimization-sdk/build-a-custom-javascript-optimization-adapter/) | | React Native apps | [Integrate the Optimization React Native SDK in a React Native app](/personalization/optimization-sdk/integrate-the-react-native-sdk-in-a-react-native-app/) | | iOS SwiftUI apps | [Integrate the Optimization iOS SDK in a SwiftUI app](/personalization/optimization-sdk/integrate-the-optimization-ios-sdk-in-a-swiftui-app/) | | iOS UIKit apps | [Integrate the Optimization iOS SDK in a UIKit app](/personalization/optimization-sdk/integrate-the-optimization-ios-sdk-in-a-uikit-app/) | | Android Jetpack Compose apps | [Integrate the Optimization Android SDK in a Jetpack Compose app](/personalization/optimization-sdk/integrate-the-optimization-android-sdk-in-a-compose-app/) | | Android Views apps | [Integrate the Optimization Android SDK in an Android Views app](/personalization/optimization-sdk/integrate-the-optimization-android-sdk-in-a-views-app/) | | Analytics and tag-management forwarding | [Forward Optimization SDK context to analytics and tag-management tools](/personalization/optimization-sdk/forwarding-optimization-sdk-context-to-analytics-and-tag-management-tools/) |