+
+
+## Runtime boundary
+
+The Android SDK is a native Kotlin Android library published as
+`com.contentful.java:optimization-android`. Kotlin owns native app concerns such as persistence,
+networking, lifecycle handling, Compose helpers, XML Views helpers, preview-panel UI, and app-facing
+public APIs.
+
+Shared optimization behavior runs inside a local QuickJS context. That bridge lets the Android SDK
+use the same personalization, profile, consent, and event-delivery behavior as the JavaScript SDKs
+while exposing a Kotlin API to the application.
+
+Applications do not call the JavaScript layer directly. The public boundary is Kotlin:
+
+- `OptimizationClient` is the main facade for initialization, state, personalization, tracking, and
+ preview controls.
+- `OptimizationRoot`, `OptimizedEntry`, `OptimizationLazyColumn`, and `ScreenTrackingEffect` provide
+ Compose integration helpers.
+- `OptimizationManager`, `OptimizedEntryView`, `TrackingRecyclerView`, and `ScreenTracker` provide
+ XML Views integration helpers.
+- `PreviewPanelConfig` wires the in-app preview panel into Compose and XML Views integrations.
+
+This split also defines what the SDK does not own. The application still fetches Contentful entries,
+manages consent UX, controls routing, decides identity policy, and renders the final UI.
+
+## Lifecycle and coroutines
+
+`OptimizationClient` has two phases:
+
+| Phase | Behavior |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Uninitialized | The client exists, but the bridge is not loaded. Suspend APIs throw or return safe fallbacks depending on the call, and sync APIs no-op where appropriate. |
+| Initialized | The bridge is loaded, persisted state has been merged into configuration, SDK state is available, and lifecycle/network observers are active. |
+
+Compose apps usually let `OptimizationRoot` create the client and call `initialize(config)`. XML
+Views apps usually call `OptimizationManager.initialize(...)` from `Application.onCreate` before
+reading `OptimizationManager.client` from activities or fragments.
+
+`OptimizationClient` exposes async work as `suspend` functions. Call those methods from Compose
+effects, View event-handler coroutine scopes, lifecycle-aware coroutines, or another app-owned
+coroutine scope.
+
+The QuickJS runtime runs on a dedicated single-thread dispatcher owned by the SDK. Application code
+must use the public Kotlin APIs instead of trying to access the bridge directly.
+
+Typical apps keep one client alive for the app process lifetime. Use `destroy()` for test teardown
+or deliberate SDK reset flows.
+
+## Configuration and locale handoff
+
+Every Android integration builds an `OptimizationConfig`:
+
+```kotlin
+OptimizationConfig(
+ clientId = "your-client-id",
+ environment = "master",
+ contentfulLocales = ContentfulLocales(default = "en-US"),
+ locale = "en-US",
+ defaults = StorageDefaults(consent = true),
+ debug = BuildConfig.DEBUG,
+)
+```
+
+Only `clientId` is required. `environment` defaults to `"master"`. Base URL overrides belong only in
+integrations that need non-default Experience API or Insights API endpoints.
+
+Use `contentfulLocales` and `locale` when the application renders localized Contentful entries. The
+resolved `client.locale` belongs in the app-owned Contentful Delivery API request before entries are
+passed to `OptimizedEntry`, `OptimizedEntryView`, or `personalizeEntry(...)`.
+
+`OptimizationApiConfig.locale` is an explicit Experience API locale override. It does not replace
+the CDA locale used to fetch entries. For the full locale model, see
+[Locale handling in the Optimization SDK Suite](./locale-handling-in-the-optimization-sdk-suite.md).
+
+## State and persistence
+
+`OptimizationClient` publishes runtime state through Kotlin flows:
+
+| Surface | Description |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `state` | Snapshot of profile, consent, personalization readiness, and pending changes. |
+| `isInitialized` | `true` after initialization completes. |
+| `selectedPersonalizations` | The personalizations the visitor qualifies for. |
+| `isPreviewPanelOpen` | `true` while the in-app preview panel is visible. |
+| `previewState` | Preview override state used by the in-app preview panel. |
+| `events` | Raw event stream for debug surfaces and tests. |
+
+Compose code reads these values through `collectAsState()` or effects. XML Views code usually
+collects them from lifecycle-aware coroutines.
+
+The SDK persists state with `SharedPreferences`. `StorageDefaults` can seed values such as consent,
+profile, selected changes, and personalizations on first launch. Seeds are applied only when no
+persisted value exists, so an existing user choice is not overwritten.
+
+## Consent and event gates
+
+Consent is a three-state value: `true`, `false`, or unset. Until consent is granted, the SDK blocks
+most Analytics events. `identify` and `screen` are allowed before consent so the mobile journey can
+establish profile context and anonymous screen analytics.
+
+| Consent state | Event behavior |
+| ------------- | ----------------------------------------------------------- |
+| Unset | `identify` and `screen` can emit; other events are blocked. |
+| `true` | All event types can emit. |
+| `false` | `identify` and `screen` can emit; other events are blocked. |
+
+Call `client.consent(true)` when the visitor grants consent and `client.consent(false)` when the
+visitor rejects it. The value is persisted and restored on later launches.
+
+## Entry personalization boundary
+
+Entry personalization is a local decision once the app has both Contentful entry data and selected
+personalizations.
+
+The application provides:
+
+- A single-locale Contentful entry map.
+- Linked optimization references and variant entries in the Contentful payload.
+- The current `selectedPersonalizations` value from the client, when resolving directly.
+
+The SDK returns either the baseline entry or the resolved variant entry:
+
+```kotlin
+val result = client.personalizeEntry(
+ baseline = entry,
+ personalizations = client.selectedPersonalizations.value,
+)
+
+val resolvedEntry = result.entry
+val personalization = result.personalization
+```
+
+`personalizeEntry(...)` does not fetch Contentful entries, evaluate audiences, call the Experience
+API, or mutate state. Compose `OptimizedEntry` and XML Views `OptimizedEntryView` wrap the same
+boundary and add component-level behavior such as variant locking, live updates, and interaction
+tracking.
+
+For the full data model and fallback behavior, see
+[Entry personalization and variant resolution](./entry-personalization-and-variant-resolution.md).
+
+## Adapter surfaces
+
+The Android SDK exposes two public UI adapter packages over the same core client:
+
+| App style | Initialization path | Entry rendering path | Screen tracking path | Scroll tracking helper |
+| --------- | -------------------------------- | -------------------- | ---------------------- | ------------------------ |
+| Compose | `OptimizationRoot` | `OptimizedEntry` | `ScreenTrackingEffect` | `OptimizationLazyColumn` |
+| XML Views | `OptimizationManager.initialize` | `OptimizedEntryView` | `ScreenTracker` | `TrackingRecyclerView` |
+
+Both adapters use the same `OptimizationClient`, persistence model, bridge runtime, event gates,
+locale resolution, and preview override state. Choose the adapter that matches the UI framework of
+the screen you are integrating.
+
+## Tracking mechanics
+
+The Android SDK emits mobile screen events and Contentful entry interaction events:
+
+| Event type | Compose path | XML Views path |
+| ---------- | ------------------------------ | ---------------------------------- |
+| Screen | `ScreenTrackingEffect` | `ScreenTracker.trackScreen(...)` |
+| Entry view | `OptimizedEntry` view tracking | `OptimizedEntryView` view tracking |
+| Entry tap | `OptimizedEntry` tap tracking | `OptimizedEntryView` tap tracking |
+
+Entry view tracking uses these defaults:
+
+- Initial view event after 2 seconds at 80% visibility.
+- Periodic duration updates every 5 seconds while the entry remains visible.
+- Final duration update when the entry leaves view after a view event has already fired.
+
+`OptimizedEntry` and `OptimizedEntryView` can tune the visibility threshold, initial time, and
+update interval per entry. Use `OptimizationLazyColumn` in Compose and `TrackingRecyclerView` in XML
+Views when view timing needs scroll-aware visibility updates.
+
+Applications can also call `trackView(...)` and `trackClick(...)` directly when they need to emit
+events from a custom UI abstraction.
+
+## Live updates and preview behavior
+
+`OptimizedEntry` and `OptimizedEntryView` lock to the first resolved variant by default. Locking
+prevents content from changing while a visitor is reading it. Enable live updates when a component
+needs to react to profile changes or preview overrides without a reload.
+
+Android live-update precedence is:
+
+| Preview panel | Global default | Per-entry override | Result |
+| ------------- | -------------- | ------------------ | ------ |
+| Open | Any | Any | Live |
+| Closed | `true` | `null` | Live |
+| Closed | `false` | `true` | Live |
+| Closed | `true` | `false` | Locked |
+| Closed | `false` | `null` | Locked |
+
+When the preview panel is open, all `OptimizedEntry` and `OptimizedEntryView` components update live
+so audience and variant overrides apply immediately. When the panel closes, components keep the
+previewed variant as the locked value.
+
+Compose apps pass `PreviewPanelConfig` to `OptimizationRoot`. XML Views apps pass the optional
+preview content client to `OptimizationManager.initialize(...)` and call
+`OptimizationManager.attachPreviewPanel(...)` from activities that display the floating preview
+entry point.
+
+## Offline and app lifecycle delivery
+
+The Android SDK monitors network reachability and app lifecycle events:
+
+- When the device is offline, events queue in memory.
+- When connectivity returns, queued events flush automatically.
+- When the app moves toward the background, the SDK flushes queued events to reduce data loss.
+
+No configuration is required for this behavior. Queueing and flushing use the same event-delivery
+model for Compose and XML Views integrations.
+
+## Related documentation
+
+- [Optimization Android SDK README](../../packages/android/README.md) - Package installation, quick
+ start, and published package status.
+- [Integrating the Optimization Android SDK in a Jetpack Compose app](../guides/integrating-the-optimization-android-sdk-in-a-compose-app.md) -
+ Compose setup flow for `OptimizationRoot`, `OptimizedEntry`, screen tracking, and preview panel
+ mounting.
+- [Integrating the Optimization Android SDK in an XML Views app](../guides/integrating-the-optimization-android-sdk-in-a-views-app.md) -
+ XML Views setup flow for `OptimizationManager`, `OptimizedEntryView`, screen tracking, and preview
+ panel mounting.
+- [Android reference implementation](../../implementations/android-sdk/README.md) - Native Android
+ validation app with Compose and XML Views shells.
diff --git a/documentation/concepts/entry-personalization-and-variant-resolution.md b/documentation/concepts/entry-personalization-and-variant-resolution.md
index b08527cc..a6ca9a27 100644
--- a/documentation/concepts/entry-personalization-and-variant-resolution.md
+++ b/documentation/concepts/entry-personalization-and-variant-resolution.md
@@ -316,6 +316,19 @@ server-provided or request-local data because it avoids depending on ambient SDK
Provide optimization data before expecting personalized content. `page()`, `identify()`, `screen()`,
`track()`, and sticky `trackView()` can return the selected optimization data used by this method.
+The iOS SDK exposes the same local boundary through
+`OptimizationClient.personalizeEntry(baseline:personalizations:)`. UIKit apps usually pass
+`client.selectedPersonalizations` during cell or view configuration. The method returns a
+`PersonalizedResult` containing the resolved `entry` and optional `personalization` metadata, and
+returns the baseline unchanged when no selected personalization matches the entry.
+
+The Android SDK exposes the same local boundary through
+`OptimizationClient.personalizeEntry(baseline = ..., personalizations = ...)`. XML Views apps
+usually rely on `OptimizedEntryView` or pass `client.selectedPersonalizations.value` when resolving
+directly. The method returns a `PersonalizedResult` containing the resolved `entry` and optional
+`personalization` metadata, and returns the baseline unchanged when no selected personalization
+matches the entry.
+
### Render with framework components
Use framework components when rendering is already inside a supported React tree. They subscribe to
@@ -347,6 +360,17 @@ React Native uses the same resolver inside its `OptimizedEntry` component. The c
React Native does not render DOM data attributes. It passes the resolved entry and optimization
metadata directly into its viewport and tap tracking hooks.
+SwiftUI uses the same resolver inside `OptimizedEntry`. The component passes non-optimized entries
+through unchanged, resolves optimized entries from the client's selected personalizations, can lock
+to the first resolved variant, can re-resolve when live updates are enabled, and can attach iOS view
+and tap tracking for the resolved entry.
+
+Android Compose uses the same resolver inside `OptimizedEntry`, and Android XML Views use it inside
+`OptimizedEntryView`. Both adapters pass non-optimized entries through unchanged, resolve optimized
+entries from the client's selected personalizations, can lock to the first resolved variant, can
+re-resolve when live updates are enabled, and can attach Android view and tap tracking for the
+resolved entry.
+
### Preview selected variants
Preview tooling changes selected variants by overriding `variantIndex` in `selectedOptimizations`.
diff --git a/documentation/concepts/ios-sdk-bridge.md b/documentation/concepts/ios-sdk-bridge.md
deleted file mode 100644
index 3bd98fdc..00000000
--- a/documentation/concepts/ios-sdk-bridge.md
+++ /dev/null
@@ -1,156 +0,0 @@
----
-title: iOS SDK bridge
----
-
-# iOS SDK bridge
-
-Use this document when you need the iOS-specific detail behind the JavaScriptCore bridge — context
-lifecycle, exception handling, callback closure registration, signpost markers, the Swift Package
-resource declaration. For the cross-platform architecture and the identify / screen /
-personalizeEntry call flow, read
-[Native mobile SDK architecture](./native-mobile-sdk-architecture.md) first.
-
-Table of Contents
+ + +- [Runtime boundary](#runtime-boundary) +- [Lifecycle and coroutines](#lifecycle-and-coroutines) +- [Configuration and locale handoff](#configuration-and-locale-handoff) +- [State and persistence](#state-and-persistence) +- [Consent and event gates](#consent-and-event-gates) +- [Entry personalization boundary](#entry-personalization-boundary) +- [Adapter surfaces](#adapter-surfaces) +- [Tracking mechanics](#tracking-mechanics) +- [Live updates and preview behavior](#live-updates-and-preview-behavior) +- [Offline and app lifecycle delivery](#offline-and-app-lifecycle-delivery) +- [Related documentation](#related-documentation) + + +
-
-
-## 1. The JavaScriptCore context
-
-[`JSContextManager`](../../packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Bridge/JSContextManager.swift)
-owns the `JSContext` for the lifetime of one `OptimizationClient`. Initialization runs in this fixed
-order:
-
-1. **Create the context** with `JSContext()` and install a global exception handler that surfaces
- uncaught JS errors via `onLog("exception", message)`.
-2. **Enable remote inspection** (`ctx.isInspectable = true`) only when `config.debug` is `true` and
- the deployment target is iOS 16.4 / macOS 13.3 or newer. Release builds never expose this.
-3. **Register the five native polyfill bindings** via `NativePolyfills.register(in: ctx, logger:)`.
- The call returns a `TimerStore` that the manager retains for the lifetime of the context and uses
- for `cancelAll()` on teardown.
-4. **Evaluate the UMD bundle** loaded from
- `Bundle.module.url(forResource: "optimization-ios-bridge.umd", withExtension: "js")`. The eight
- polyfills are already prepended into the bundle text at build time, so a single `evaluateScript`
- call installs both the polyfills and `globalThis.__bridge`.
-5. **Sanity check** `typeof __bridge` — anything other than `"object"` throws
- `OptimizationError.bridgeError`.
-6. **Register the three push-back globals**: `__nativeOnStateChange`, `__nativeOnEventEmitted`, and
- `__nativeOnOverridesChanged`. Each is a Swift `@convention(block) (String) -> Void` closure that
- the JS bundle invokes whenever the relevant signal changes; the manager parses the JSON and
- re-emits on `DispatchQueue.main`.
-7. **Call `__bridge.initialize(Table of Contents
- -- [1. The JavaScriptCore context](#1-the-javascriptcore-context) -- [2. Native polyfill bindings](#2-native-polyfill-bindings) -- [3. Async callback registration](#3-async-callback-registration) -- [4. Threading model](#4-threading-model) -- [5. Bundle resource declaration](#5-bundle-resource-declaration) -- [6. Diagnostics: exceptions and signposts](#6-diagnostics-exceptions-and-signposts) - -
+
+
+## Runtime boundary
+
+The iOS SDK is a native Swift Package named `ContentfulOptimization`. Swift owns native app concerns
+such as persistence, networking, lifecycle handling, SwiftUI helpers, UIKit preview-panel
+presentation, and app-facing public APIs.
+
+Shared optimization behavior runs inside a local JavaScriptCore context. That bridge lets the iOS
+SDK use the same personalization, profile, consent, and event-delivery behavior as the JavaScript
+SDKs while exposing a Swift API to the application.
+
+Applications do not call the JavaScript layer directly. The public boundary is Swift:
+
+- `OptimizationClient` is the main facade for initialization, state, personalization, tracking, and
+ preview controls.
+- `OptimizationRoot`, `OptimizedEntry`, `OptimizationScrollView`, and `.trackScreen(name:)` provide
+ SwiftUI integration helpers.
+- `PreviewPanelViewController` provides the UIKit preview-panel host.
+
+This split also defines what the SDK does not own. The application still fetches Contentful entries,
+manages consent UX, controls routing, decides identity policy, and renders the final UI.
+
+## Lifecycle and main actor
+
+`OptimizationClient` has two phases:
+
+| Phase | Behavior |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Uninitialized | The client exists, but the bridge is not loaded. Async APIs throw `OptimizationError.notInitialized`; sync APIs return safe defaults or no-op where appropriate. |
+| Initialized | The bridge is loaded, persisted state has been merged into configuration, SDK state is available, and lifecycle/network observers are active. |
+
+SwiftUI apps usually let `OptimizationRoot` call `initialize(config:)`. UIKit apps usually call
+`initialize(config:)` from scene or app startup before passing the client into view controllers.
+
+`OptimizationClient` is `@MainActor`. Call it from main-thread contexts such as SwiftUI view tasks,
+SwiftUI event handlers, view-controller lifecycle methods, or `Task { @MainActor in ... }` blocks.
+The compiler can flag background calls as concurrency errors.
+
+Typical apps keep one `OptimizationClient` alive for the app or scene lifetime. Use `destroy()` for
+test teardown or deliberate SDK reset flows.
+
+## Configuration and locale handoff
+
+Every iOS integration builds an `OptimizationConfig`:
+
+```swift
+OptimizationConfig(
+ clientId: "your-client-id",
+ environment: "master",
+ contentfulLocales: ContentfulLocales(default: "en-US"),
+ locale: "en-US",
+ defaults: StorageDefaults(consent: true),
+ debug: true
+)
+```
+
+Only `clientId` is required. `environment` defaults to `"master"`. Base URL overrides belong only in
+integrations that need non-default Experience API or Insights API endpoints.
+
+Use `contentfulLocales` and `locale` when the application renders localized Contentful entries. The
+resolved `client.locale` belongs in the app-owned Contentful Delivery API request before entries are
+passed to `OptimizedEntry` or `personalizeEntry(...)`.
+
+`OptimizationApiConfig.locale` is an explicit Experience API locale override. It does not replace
+the CDA locale used to fetch entries. For the full locale model, see
+[Locale handling in the Optimization SDK Suite](./locale-handling-in-the-optimization-sdk-suite.md).
+
+## State and persistence
+
+`OptimizationClient` is an `ObservableObject`. It publishes runtime state that SwiftUI and UIKit
+code can observe:
+
+| Surface | Description |
+| -------------------------- | ----------------------------------------------------------------------------- |
+| `state` | Snapshot of profile, consent, personalization readiness, and pending changes. |
+| `isInitialized` | `true` after initialization completes. |
+| `selectedPersonalizations` | The personalizations the visitor qualifies for. |
+| `isPreviewPanelOpen` | `true` while the in-app preview panel is visible. |
+| `eventPublisher` | Raw event stream for debug surfaces and tests. |
+
+SwiftUI code reads these values through `@EnvironmentObject`. UIKit code can subscribe through
+Combine publishers such as `client.$state` and `client.$selectedPersonalizations`.
+
+The SDK persists state with `UserDefaults`. `StorageDefaults` can seed values such as consent,
+profile, selected changes, and personalizations on first launch. Seeds are applied only when no
+persisted value exists, so an existing user choice is not overwritten.
+
+## Consent and event gates
+
+Consent is a three-state value: `true`, `false`, or unset. Until consent is granted, the SDK blocks
+most Analytics events. `identify` and `screen` are allowed before consent so the mobile journey can
+establish profile context and anonymous screen analytics.
+
+| Consent state | Event behavior |
+| ------------- | ----------------------------------------------------------- |
+| Unset | `identify` and `screen` can emit; other events are blocked. |
+| `true` | All event types can emit. |
+| `false` | `identify` and `screen` can emit; other events are blocked. |
+
+Call `client.consent(true)` when the visitor grants consent and `client.consent(false)` when the
+visitor rejects it. The value is persisted and restored on later launches.
+
+## Entry personalization boundary
+
+Entry personalization is a local, synchronous decision once the app has both Contentful entry data
+and selected personalizations.
+
+The application provides:
+
+- A single-locale Contentful entry dictionary.
+- Linked optimization references and variant entries in the Contentful payload.
+- The current `selectedPersonalizations` value from the client, when resolving directly.
+
+The SDK returns either the baseline entry or the resolved variant entry:
+
+```swift
+let result = client.personalizeEntry(
+ baseline: entry,
+ personalizations: client.selectedPersonalizations
+)
+
+let resolvedEntry = result.entry
+let personalization = result.personalization
+```
+
+`personalizeEntry` does not fetch Contentful entries, evaluate audiences, call the Experience API,
+or mutate state. SwiftUI `OptimizedEntry` wraps the same boundary and adds component-level behavior
+such as variant locking, live updates, and interaction tracking.
+
+For the full data model and fallback behavior, see
+[Entry personalization and variant resolution](./entry-personalization-and-variant-resolution.md).
+
+## Tracking mechanics
+
+The iOS SDK emits mobile screen events and Contentful entry interaction events:
+
+| Event type | SwiftUI path | UIKit path |
+| ---------- | ------------------------------ | ------------------------------- |
+| Screen | `.trackScreen(name:)` | `client.screen(name:)` |
+| Entry view | `OptimizedEntry` view tracking | App-computed `TrackViewPayload` |
+| Entry tap | `OptimizedEntry` tap tracking | App-emitted `TrackClickPayload` |
+
+SwiftUI entry view tracking uses these defaults:
+
+- Initial view event after 2 seconds at 80% visibility.
+- Periodic duration updates every 5 seconds while the entry remains visible.
+- Final duration update when the entry leaves view after a view event has already fired.
+
+`OptimizedEntry` can tune the visibility threshold, initial time, and update interval per entry.
+Wrap scrollable content in `OptimizationScrollView` when view timing needs an accurate viewport.
+
+UIKit does not have automatic component visibility tracking. UIKit apps compute visibility and
+duration through their own table, collection, or view-controller callbacks, then emit
+`TrackViewPayload` and `TrackClickPayload` directly.
+
+## Live updates and preview behavior
+
+SwiftUI `OptimizedEntry` locks to the first resolved variant by default. Locking prevents content
+from changing while a visitor is reading it. Enable live updates when a component needs to react to
+profile changes or preview overrides without a reload.
+
+SwiftUI live-update precedence is:
+
+| Preview panel | Global default | Per-entry override | Result |
+| ------------- | -------------- | ------------------ | ------ |
+| Open | Any | Any | Live |
+| Closed | `true` | `nil` | Live |
+| Closed | `false` | `true` | Live |
+| Closed | `true` | `false` | Locked |
+| Closed | `false` | `nil` | Locked |
+
+When the preview panel is open, all SwiftUI `OptimizedEntry` components update live so audience and
+variant overrides apply immediately. When the panel closes, SwiftUI components keep the previewed
+variant as the locked value.
+
+UIKit apps choose their own live-update policy. Redraw views when `client.selectedPersonalizations`
+changes for live behavior, or keep a selected-personalizations snapshot for locked behavior. Use
+`client.isPreviewPanelOpen` when the app needs to redraw in live mode only while previewing.
+
+## Offline and app lifecycle delivery
+
+The iOS SDK monitors network reachability and app lifecycle events:
+
+- When the device is offline, events queue in memory.
+- When connectivity returns, queued events flush automatically.
+- When the app moves toward the background, the SDK flushes queued events to reduce data loss.
+
+No configuration is required for this behavior. Queueing and flushing use the same event-delivery
+model for SwiftUI and UIKit integrations.
+
+## Related documentation
+
+- [Optimization iOS SDK README](../../packages/ios/ContentfulOptimization/README.md) - Package
+ installation, quick start, and published package status.
+- [Integrating the Optimization iOS SDK in a SwiftUI app](../guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md) -
+ SwiftUI setup flow for `OptimizationRoot`, `OptimizedEntry`, screen tracking, and preview panel
+ mounting.
+- [Integrating the Optimization iOS SDK in a UIKit app](../guides/integrating-the-optimization-ios-sdk-in-a-uikit-app.md) -
+ UIKit setup flow for direct `OptimizationClient` usage, manual entry resolution, tracking, and
+ preview panel mounting.
+- [iOS reference implementation](../../implementations/ios-sdk/README.md) - Native iOS validation
+ app with SwiftUI and UIKit shells.
diff --git a/documentation/concepts/native-mobile-sdk-architecture.md b/documentation/concepts/native-mobile-sdk-architecture.md
deleted file mode 100644
index f707af66..00000000
--- a/documentation/concepts/native-mobile-sdk-architecture.md
+++ /dev/null
@@ -1,257 +0,0 @@
----
-title: Native mobile SDK architecture
----
-
-# Native mobile SDK architecture
-
-Use this document to understand how the native iOS and Android SDKs share one TypeScript core by
-running it inside an embedded JavaScript engine on the device, and how that JavaScript core reaches
-back out to native primitives — `URLSession`, `OkHttp`, `DispatchQueue`, `Handler`, `OSLog`,
-`Logcat` — through a small set of polyfill bindings registered before the bundle evaluates.
-
-For platform-specific nuances, see [iOS SDK bridge](./ios-sdk-bridge.md) and
-[Android SDK bridge](./android-sdk-bridge.md). For step-by-step contributor onboarding, see
-[Contributing to the iOS SDK](../guides/contributing-to-the-ios-sdk.md) and
-[Contributing to the Android SDK](../guides/contributing-to-the-android-sdk.md).
-
-Table of Contents
+ + +- [Runtime boundary](#runtime-boundary) +- [Lifecycle and main actor](#lifecycle-and-main-actor) +- [Configuration and locale handoff](#configuration-and-locale-handoff) +- [State and persistence](#state-and-persistence) +- [Consent and event gates](#consent-and-event-gates) +- [Entry personalization boundary](#entry-personalization-boundary) +- [Tracking mechanics](#tracking-mechanics) +- [Live updates and preview behavior](#live-updates-and-preview-behavior) +- [Offline and app lifecycle delivery](#offline-and-app-lifecycle-delivery) +- [Related documentation](#related-documentation) + + +
-
-
-## 1. One TypeScript core, two UMD bundles
-
-The SDK is one TypeScript source tree under
-[`packages/universal/optimization-js-bridge/src/`](../../packages/universal/optimization-js-bridge/),
-compiled by Rslib into two UMD bundles that differ only in which package name they stamp into
-analytics `library.name`:
-
-| Bundle | Consumer | Engine |
-| ------------------------------------ | --------------------------------------------- | --------------------------------------- |
-| `optimization-ios-bridge.umd.js` | [`packages/ios`](../../packages/ios/) | JavaScriptCore (`JSContext`) |
-| `optimization-android-bridge.umd.js` | [`packages/android`](../../packages/android/) | QuickJS (`io.github.dokar3:quickjs-kt`) |
-
-The bridge package's `postbuild` script copies each UMD into the corresponding native package — the
-iOS bundle into `Sources/ContentfulOptimization/Resources/`, the Android bundle into
-`src/main/assets/`. From there it is packaged as a Swift Package resource or an Android asset and
-read into memory at runtime by the platform's context manager.
-
-The UMD exposes a single `globalThis.__bridge` object with methods like `identify`, `screen`,
-`personalizeEntry`, `flush`, `consent`, `reset`, `getProfile`, `getPreviewState`, and the preview-
-panel override mutators. Native code never imports a JavaScript symbol by any other path.
-
-## 2. Polyfills are prepended at build time
-
-The bundle assumes a browser-ish global environment — `console`, `setTimeout`, `fetch`,
-`crypto.randomUUID`, `URL`, `URLSearchParams`, `AbortController`, `TextEncoder`. Neither
-JavaScriptCore nor QuickJS ships those. The bridge build prepends eight polyfill scripts to the
-emitted UMD as raw text before the IIFE, so each polyfill's top-level `var` and `function`
-declarations bind on the global object exactly as if they had been loaded as separate scripts.
-
-The prepend is implemented by a custom rspack plugin in
-[`rslib.config.ts`](../../packages/universal/optimization-js-bridge/rslib.config.ts) (the built-in
-`BannerPlugin` is unsuitable because it would template-substitute `[id]` inside polyfill code such
-as `__timerCallbacks[id]`). The concatenation helper lives in
-[`lib/build-tools/src/rslib.ts`](../../lib/build-tools/src/rslib.ts) as `concatPolyfills`.
-
-The load order is load-bearing — `timers` must precede `abort-controller`, `console` must come first
-so anything that logs during its own initialization can do so:
-
-| Order | Polyfill | Installs on `globalThis` | Native binding it consumes |
-| ----- | ------------------- | ---------------------------------------------------------------------------- | -------------------------------------------- |
-| 1 | `console` | `console.log/warn/error/info/debug` | `__nativeLog` |
-| 2 | `timers` | `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `__timerFired` | `__nativeSetTimeout`, `__nativeClearTimeout` |
-| 3 | `fetch` | `fetch`, `__fetchComplete` | `__nativeFetch` |
-| 4 | `crypto` | `crypto.randomUUID`, `crypto.getRandomValues` | `__nativeRandomUUID` |
-| 5 | `url` | `URL`, `URLSearchParams` | — |
-| 6 | `abort-controller` | `AbortController`, `AbortSignal.timeout` | — |
-| 7 | `promise-utilities` | `queueMicrotask`, `Promise.withResolvers` (when missing) | — |
-| 8 | `text-encoding` | `TextEncoder`, `TextDecoder` (when missing) | — |
-
-The native polyfill bindings — the `__native*` globals in the right column — must already exist on
-the global object when the prepended polyfills evaluate. That ordering is the responsibility of the
-per-platform context manager described next.
-
-## 3. Native polyfill bindings
-
-Each platform's context manager registers the same five `__native*` globals into the JS engine
-before the UMD evaluates. The contract is identical; the implementation is platform-native:
-
-| Binding | iOS implementation | Android implementation |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `__nativeLog` | `@convention(block)` closure → `JSContextManager.onLog` | `__native.log` (via `qjs.define`) → `NativeImpl.log` |
-| `__nativeSetTimeout` | `DispatchQueue.main.asyncAfter`, work item stored in `TimerStore`, fires `__timerFired(id)` in JS | `scope.launch { delay(ms); evaluateJS("__timerFired(id)") }`, job stored in `TimerStore` |
-| `__nativeClearTimeout` | Cancels the `DispatchWorkItem` in `TimerStore` | Cancels the `Job` in `TimerStore` |
-| `__nativeRandomUUID` | `UUID().uuidString.lowercased()` | `UUID.randomUUID().toString()` |
-| `__nativeFetch` | `URLSession.shared.dataTask`, response delivered to `__fetchComplete(callbackId, status, headers, body, error)` on main queue | `OkHttpClient.newCall(...).enqueue`, response delivered to `__fetchComplete(...)` via `scope.launch { evaluateJS(...) }` |
-
-On iOS the five globals are set directly on the `JSContext` via `setObject(_:forKeyedSubscript:)`.
-On Android the `quickjs-kt` `qjs.define("__native") { function(...) }` DSL exposes the methods on a
-`__native` object, and a five-line bootstrap script aliases each one to the matching `__native*`
-global — that way the prepended polyfills can call `__nativeFetch(...)` on either platform without
-caring how the binding was installed.
-
-Detail beyond this point — JavaScriptCore exception handlers, `os_signpost` markers, the
-`quickjs-kt` single-threaded executor — is platform-specific. See
-[iOS SDK bridge](./ios-sdk-bridge.md) and [Android SDK bridge](./android-sdk-bridge.md).
-
-## 4. End-to-end call flow
-
-The flow below is illustrated for iOS. Android uses the same flow with the engine substitutions
-listed above (`JSContext.evaluateScript` ↔ `qjs.evaluate`, `URLSession` ↔ `OkHttp`,
-`DispatchQueue.main` ↔ a coroutine on `Dispatchers.Main`).
-
-### Sequence diagram
-
-```mermaid
-sequenceDiagram
- autonumber
- participant App as Swift caller
- participant Client as OptimizationClient
- participant CBM as BridgeCallbackManager
- participant Ctx as JSContextManager
- participant Bridge as __bridge (JS)
- participant Fetch as fetch polyfill (JS)
- participant Native as __nativeFetch (Swift)
- participant URL as URLSession
-
- App->>Client: identify(userId, traits)
- Client->>CBM: registerCallback(prefix: "identify")
- CBM-->>Ctx: setObject(success/error closures)
- CBM-->>Client: ("__identifyCallback_N_success", "..._error")
- Client->>Ctx: evaluateScript("__bridge.identify(payload, success, error)")
- Ctx->>Bridge: __bridge.identify(payload, onSuccess, onError)
- Bridge->>Fetch: fetch(insightsUrl, { ... })
- Fetch->>Native: __nativeFetch(url, method, headers, body, callbackId)
- Native->>URL: URLSession.shared.dataTask(...)
- URL-->>Native: (data, response, error)
- Native->>Ctx: __fetchComplete(callbackId, status, headers, body, err)
- Ctx->>Fetch: __fetchComplete(...)
- Fetch-->>Bridge: resolve(Response)
- Bridge->>Ctx: onSuccess(JSON.stringify(result))
- Ctx->>CBM: success closure fires
- CBM->>CBM: setObject(nil) for both names
- CBM-->>Client: completion(.success(json))
- Client-->>App: returns [String: Any]?
-
- Note over App,Client: personalizeEntry skips the Fetch / URLSession lanes:Table of Contents
- -- [1. One TypeScript core, two UMD bundles](#1-one-typescript-core-two-umd-bundles) -- [2. Polyfills are prepended at build time](#2-polyfills-are-prepended-at-build-time) -- [3. Native polyfill bindings](#3-native-polyfill-bindings) -- [4. End-to-end call flow](#4-end-to-end-call-flow) - - [Sequence diagram](#sequence-diagram) - - [Async path: identify and screen](#async-path-identify-and-screen) - - [Sync path: personalizeEntry](#sync-path-personalizeentry) -- [5. State push-back from JS to native](#5-state-push-back-from-js-to-native) -- [6. Threading and lifecycle](#6-threading-and-lifecycle) -- [Where to go next](#where-to-go-next) - -evaluateScript returns the JSON result synchronously. -``` - -### Async path: identify and screen - -The methods that round-trip through the Insights API — `identify`, `page`, `screen`, `trackView`, -`trackClick`, `flush` — are all async on the Swift / Kotlin surface because the JS-side handlers -return a `Promise`. The bridge cannot pass JS function objects back through `evaluateScript`'s -return value, so it uses a name-passing convention instead: - -1. `OptimizationClient.identify(userId, traits)` builds a JSON payload and calls - `bridgeCallAsyncJSON(method: "identify")` - ([`OptimizationClient.swift:120–131`](../../packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationClient.swift)). -2. `BridgeCallbackManager.registerCallback` mints a unique id `N` and registers two Swift closures - on the JS global as `__identifyCallback_N_success` and `__identifyCallback_N_error` - ([`BridgeCallbackManager.swift:21–47`](../../packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Bridge/BridgeCallbackManager.swift)). -3. `JSContextManager.callAsync` evaluates - `__bridge.identify({"userId":...,"traits":...}, __identifyCallback_N_success, __identifyCallback_N_error)` - ([`JSContextManager.swift:88–141`](../../packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Bridge/JSContextManager.swift)). -4. The JS bridge calls into `CoreStateful.identify(payload)`, which eventually invokes the `fetch` - polyfill. `fetch` allocates a callback id, registers its own resolver, and calls - `__nativeFetch(url, method, headersJSON, body, callbackId)`. -5. The Swift fetch binding runs `URLSession.shared.dataTask`, then delivers the response on the main - queue by calling - `ctx.objectForKeyedSubscript("__fetchComplete")?.call(withArguments: [callbackId, status, headers, body, errorMsg])` - ([`NativePolyfills.swift:117–175`](../../packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Polyfills/NativePolyfills.swift)). -6. `__fetchComplete` resolves the JS-side fetch promise; the resulting chain inside `__bridge` runs - `onSuccess(JSON.stringify(result))` (or `onError(message)`), which invokes the matching Swift - closure registered in step 2. -7. The Swift closure clears both registered globals and resumes the awaiting - `withCheckedThrowingContinuation`, returning a `[String: Any]?` to the original caller. - -The error path is symmetric. If `__bridge.identify` rejects, the JS bundle calls -`__identifyCallback_N_error(message)`, the Swift error closure surfaces an -`OptimizationError.bridgeError`, and both globals are cleared. - -`screen(name, properties)` follows exactly the same pattern with a different method name in step 3. - -### Sync path: personalizeEntry - -`personalizeEntry` is purely a local resolution against the in-memory profile and the -personalizations already loaded; it does no network I/O. The bridge implements it as a synchronous -function that returns a JSON string, so the call shape collapses: - -1. `OptimizationClient.personalizeEntry(baseline, personalizations)` JSON-encodes its arguments and - calls `bridge.callSync(method: "personalizeEntry", args: ...)` - ([`OptimizationClient.swift:188–223`](../../packages/ios/ContentfulOptimization/Sources/ContentfulOptimization/Core/OptimizationClient.swift)). -2. `JSContextManager.callSync` runs - `ctx.evaluateScript("__bridge.personalizeEntry(
-
-
-## Scope and capabilities
-
-The SwiftUI integration uses the SDK's SwiftUI-native API surface:
-
-- `OptimizationRoot` initializes `OptimizationClient`, injects it as an `@EnvironmentObject`, and
- seeds global tracking defaults.
-- `OptimizedEntry` renders a personalized Contentful entry and attaches view and tap tracking.
-- `OptimizationScrollView` provides an accurate viewport context for view tracking inside scroll
- views.
-- `.trackScreen(name:)` emits a screen event when a view appears.
-- `PreviewPanelOverlay` renders a developer-only FAB that opens the preview panel sheet.
-
-## Reference app
-
-See the SwiftUI demo at
-[Colorful-Team-Org/OptimizationiOSSDKDemo — SwiftUIDemo](https://github.com/Colorful-Team-Org/OptimizationiOSSDKDemo)
-(local checkout at
-[`../../../optimization-ios-demo/SwiftUIDemo`](../../../optimization-ios-demo/SwiftUIDemo)). It
-exercises every pattern in this guide end-to-end against real Contentful content and is worth
-reading alongside this document.
-
-## The integration flow
-
-A typical SwiftUI integration is:
-
-1. Install the SDK and build an `OptimizationConfig`.
-2. Wrap the app's root content in `OptimizationRoot`.
-3. Collect consent (or pre-grant it for demos).
-4. Fetch Contentful entries with `include: 10`.
-5. Render each entry through `OptimizedEntry`, optionally inside `OptimizationScrollView`.
-6. Opt views/taps tracking on or off via `OptimizationRoot(trackViews:trackTaps:)` and
- `OptimizedEntry(trackViews:trackTaps:)`.
-7. Mark each screen with `.trackScreen(name:)`.
-8. Gate `PreviewPanelOverlay` on a debug flag.
-
-## 1. Initialize with OptimizationRoot
-
-`OptimizationRoot` owns the `OptimizationClient` instance, initializes it in a `.task {}` block, and
-shows a `ProgressView` until `isInitialized` flips to `true`. All SwiftUI views in the tree can then
-read the client via `@EnvironmentObject`.
-
-```swift
-import ContentfulOptimization
-import SwiftUI
-
-@main
-struct MyApp: App {
- var body: some Scene {
- WindowGroup {
- OptimizationRoot(
- config: OptimizationConfig(
- clientId: "your-client-id",
- environment: "master",
- contentfulLocales: ContentfulLocales(default: "en-US"),
- locale: "en-US",
- defaults: StorageDefaults(consent: true), // demo: pre-grant
- debug: true
- ),
- trackViews: true,
- trackTaps: false,
- liveUpdates: true
- ) {
- RootView()
- }
- }
- }
-}
-```
-
-Available arguments:
-
-| Argument | Type | Default | Description |
-| ------------- | -------------------- | ------- | ---------------------------------------------------------------- |
-| `config` | `OptimizationConfig` | — | Client ID, environment, API base URLs, debug flag, and defaults. |
-| `trackViews` | `Bool` | `true` | Default for `OptimizedEntry` view tracking. |
-| `trackTaps` | `Bool` | `false` | Default for `OptimizedEntry` tap tracking. |
-| `liveUpdates` | `Bool` | `false` | Default for `OptimizedEntry` live update behavior. |
-| `content` | `@ViewBuilder` | — | App content that gets the injected client. |
-
-Elsewhere, read the client with:
-
-```swift
-struct SomeView: View {
- @EnvironmentObject private var client: OptimizationClient
- // client.state, client.selectedPersonalizations, client.identify(...), ...
-}
-```
-
-## 2. Handle consent
-
-See [Consent](./integrating-the-ios-sdk-fundamentals.md#consent) in the fundamentals guide for the
-consent model. In SwiftUI, a minimal banner looks like:
-
-```swift
-struct ConsentBanner: View {
- @EnvironmentObject private var client: OptimizationClient
-
- var body: some View {
- VStack {
- Text("We use analytics to personalize content.")
- HStack {
- Button("Accept") { client.consent(true) }
- Button("Reject") { client.consent(false) }
- }
- }
- }
-}
-```
-
-To gate the banner on whether a choice has been made, observe `client.state.consent`:
-
-```swift
-struct ConsentGateTable of Contents
- - -- [Scope and capabilities](#scope-and-capabilities) -- [Reference app](#reference-app) -- [The integration flow](#the-integration-flow) -- [1. Initialize with OptimizationRoot](#1-initialize-with-optimizationroot) -- [2. Handle consent](#2-handle-consent) -- [3. Personalize entries with OptimizedEntry](#3-personalize-entries-with-optimizedentry) - - [Basic usage](#basic-usage) - - [Render prop signature](#render-prop-signature) - - [OptimizationScrollView for scrollable content](#optimizationscrollview-for-scrollable-content) - - [Tuning visibility thresholds](#tuning-visibility-thresholds) -- [4. Track entry interactions](#4-track-entry-interactions) - - [Global defaults on OptimizationRoot](#global-defaults-on-optimizationroot) - - [Per-entry overrides](#per-entry-overrides) -- [5. Enable or disable live updates](#5-enable-or-disable-live-updates) -- [6. Track screen views](#6-track-screen-views) -- [7. Preview panel](#7-preview-panel) -- [A complete example](#a-complete-example) - - -
-
-
-## Scope and capabilities
-
-The UIKit integration is more explicit than the SwiftUI one: the SDK does not ship UIKit-native
-views equivalent to `OptimizedEntry` or `OptimizationScrollView`. Instead, you work with
-`OptimizationClient` directly and attach tracking yourself.
-
-UIKit apps typically use:
-
-- `OptimizationClient` as a long-lived property on the `SceneDelegate`, passed down into view
- controllers.
-- `client.personalizeEntry(baseline:personalizations:)` called in cell configuration or view
- controller setup.
-- `client.trackView(_:)` and `client.trackClick(_:)` called from visibility callbacks and
- `UIControl` actions.
-- `client.screen(name:)` called from `viewDidAppear(_:)`.
-- `PreviewPanelViewController` (a `UIHostingController` subclass) mounted behind
- `PreviewPanelViewController.addFloatingButton(to:client:contentfulClient:)` for developer
- overrides.
-
-The preview panel's UI is itself SwiftUI, but `PreviewPanelViewController` wraps it in a
-`UIHostingController` so it drops cleanly into a UIKit navigation stack.
-
-## Reference app
-
-See the UIKit demo at
-[Colorful-Team-Org/OptimizationiOSSDKDemo — UIKitDemo](https://github.com/Colorful-Team-Org/OptimizationiOSSDKDemo)
-(local checkout at
-[`../../../optimization-ios-demo/UIKitDemo`](../../../optimization-ios-demo/UIKitDemo)). It is
-functionally identical to the SwiftUI demo so you can compare side-by-side.
-
-## The integration flow
-
-A typical UIKit integration is:
-
-1. Install the SDK and build an `OptimizationConfig`.
-2. Create a shared `OptimizationClient` in `SceneDelegate` and call `initialize(config:)`.
-3. Collect consent (or pre-grant it for demos).
-4. Pass the client into root view controllers.
-5. Fetch Contentful entries with `include: 10`.
-6. In cell configuration, call `client.personalizeEntry(baseline:personalizations:)` and render the
- resolved entry.
-7. Track clicks from `UIControl` actions with `TrackClickPayload`; track views by reporting visible
- duration to `TrackViewPayload`.
-8. Call `client.screen(name:)` from `viewDidAppear(_:)`.
-9. Mount the preview panel behind a debug flag with
- `PreviewPanelViewController.addFloatingButton(...)`.
-
-## 1. Initialize in SceneDelegate
-
-Own the `OptimizationClient` from `SceneDelegate` so its lifetime matches the scene and its instance
-is straightforward to pass into view controllers.
-
-```swift
-import ContentfulOptimization
-import UIKit
-
-class SceneDelegate: UIResponder, UIWindowSceneDelegate {
- var window: UIWindow?
- let client = OptimizationClient()
- let contentfulClient = ContentfulHTTPPreviewClient(
- spaceId: AppConfig.contentfulSpaceId,
- accessToken: AppConfig.contentfulAccessToken,
- environment: AppConfig.contentfulEnvironment
- )
-
- func scene(
- _ scene: UIScene,
- willConnectTo session: UISceneSession,
- options connectionOptions: UIScene.ConnectionOptions
- ) {
- guard let windowScene = scene as? UIWindowScene else { return }
-
- try? client.initialize(config: OptimizationConfig(
- clientId: AppConfig.optimizationClientId,
- environment: AppConfig.optimizationEnvironment,
- contentfulLocales: ContentfulLocales(default: "en-US"),
- locale: "en-US",
- defaults: StorageDefaults(consent: true), // demo pre-grant
- debug: true
- ))
-
- let home = HomeViewController(client: client)
- let nav = UINavigationController(rootViewController: home)
-
- window = UIWindow(windowScene: windowScene)
- window?.rootViewController = nav
- window?.makeKeyAndVisible()
- }
-}
-```
-
-> [!IMPORTANT]
->
-> `OptimizationClient` is `@MainActor`, so `initialize(config:)` must be called on the main thread.
-> `scene(_:willConnectTo:options:)` already runs on the main thread, so the call above is safe.
-
-Pass `client` into each view controller's initializer. This gives every screen access to the
-singleton instance for calling `personalizeEntry`, tracking events, and observing
-`selectedPersonalizations`.
-
-## 2. Handle consent
-
-See [Consent](./integrating-the-ios-sdk-fundamentals.md#consent) in the fundamentals for the consent
-model. In UIKit, typical patterns are:
-
-- A dedicated consent view controller shown before the main navigation stack.
-- An inline banner pushed into the first screen.
-- A pre-grant via `StorageDefaults(consent: true)` for demos.
-
-Example consent actions:
-
-```swift
-@objc private func acceptTapped() { client.consent(true) }
-@objc private func rejectTapped() { client.consent(false) }
-```
-
-To observe the consent state reactively, subscribe to `client.$state`:
-
-```swift
-client.$state
- .map(\.consent)
- .removeDuplicates()
- .receive(on: RunLoop.main)
- .sink { [weak self] value in
- self?.updateConsentUI(value)
- }
- .store(in: &cancellables)
-```
-
-## 3. Personalize entries
-
-### Calling personalizeEntry
-
-Fetch Contentful entries into `[String: Any]` dictionaries (the demo app's `ContentfulService` uses
-raw `URLSession`; any JSON-returning Contentful client works). Call
-`personalizeEntry(baseline:personalizations:)` wherever you render the entry — typically in
-`tableView(_:cellForRowAt:)`:
-
-```swift
-func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
- let cell = tableView.dequeueReusableCell(
- withIdentifier: BlogPostCardCell.reuseIdentifier,
- for: indexPath
- ) as! BlogPostCardCell
-
- let baseline = posts[indexPath.row]
- let resolved = client.personalizeEntry(
- baseline: baseline,
- personalizations: client.selectedPersonalizations
- )
- cell.configure(with: resolved.entry)
- return cell
-}
-```
-
-`personalizeEntry` is synchronous and returns a `PersonalizedResult`:
-
-| Field | Type | Description |
-| ----------------- | ---------------- | ---------------------------------------------------------------- |
-| `entry` | `[String: Any]` | The resolved variant entry (or the baseline if nothing matched). |
-| `personalization` | `[String: Any]?` | The matched personalization metadata, or `nil` when baseline. |
-
-Use `personalization != nil` to decide whether a user saw a personalized variant — useful when
-composing tracking payloads.
-
-### Reloading on selectedPersonalizations changes
-
-When `client.selectedPersonalizations` changes (for example, after the user's audience qualification
-shifts), re-resolve and redraw affected cells. Observe the property via Combine:
-
-```swift
-client.$selectedPersonalizations
- .dropFirst()
- .receive(on: RunLoop.main)
- .sink { [weak self] _ in
- guard let self else { return }
- self.tableView.reloadData()
- }
- .store(in: &cancellables)
-```
-
-### Live updates vs locked variants
-
-UIKit does not have an automatic "lock to first variant" mechanism — you decide when to re-resolve
-based on whether you want to stay locked or update live. Two common patterns:
-
-- **Live updates**: call `personalizeEntry` inside `cellForRowAt` and reload the table when
- `selectedPersonalizations` changes (as above). The user sees the current best variant.
-- **Locked variants**: capture `client.selectedPersonalizations` at the time your screen loads,
- store it in the view controller, and pass that snapshot into every `personalizeEntry` call. Do not
- reload on change.
-
-A common compromise is to live-update while the preview panel is open (for developer feedback) and
-lock in production. You can check `client.isPreviewPanelOpen` to decide.
-
-## 4. Track entry interactions
-
-### Click tracking
-
-Wire up a tap action on the control and call `client.trackClick(_:)` with a `TrackClickPayload`:
-
-```swift
-ctaView.onButtonTap = { [weak self] in
- guard let self else { return }
- let sys = cta["sys"] as? [String: Any] ?? [:]
- let componentId = sys["id"] as? String ?? ""
- Task {
- try? await self.client.trackClick(TrackClickPayload(
- componentId: componentId,
- variantIndex: resolved.personalization != nil ? 1 : 0
- ))
- }
-}
-```
-
-`TrackClickPayload` fields:
-
-| Field | Type | Description |
-| -------------- | --------- | -------------------------------------------------- |
-| `componentId` | `String` | Typically `entry.sys.id`. |
-| `experienceId` | `String?` | The ID of the matching experience, if any. |
-| `variantIndex` | `Int` | `0` for baseline; `1+` for a personalized variant. |
-
-### View tracking
-
-UIKit does not have a visibility modifier, so you detect visibility yourself (e.g. via
-`collectionView(_:willDisplay:forItemAt:)` / `didEndDisplaying` or by observing cell visibility
-changes) and call `client.trackView(_:)` with a `TrackViewPayload`:
-
-```swift
-try? await client.trackView(TrackViewPayload(
- componentId: entryId,
- viewId: UUID().uuidString,
- experienceId: experienceId,
- variantIndex: variantIndex,
- viewDurationMs: durationMs,
- sticky: nil
-))
-```
-
-Strategy for computing `viewDurationMs`:
-
-1. In `willDisplay`, record the timestamp and start a periodic timer.
-2. On each timer tick (e.g. every 5 seconds), send a `TrackViewPayload` with the running duration.
-3. In `didEndDisplaying`, send a final payload and cancel the timer.
-
-If this level of visibility accounting is more than you need, the simpler path is to send one event
-per display with a short configurable duration. The SwiftUI `OptimizedEntry` uses the
-threshold-based algorithm described in the fundamentals; UIKit apps that want parity can port that
-logic or read `ViewTrackingController` in the SDK source as a reference.
-
-## 5. Track screen views
-
-Call `client.screen(name:)` from `viewDidAppear(_:)`:
-
-```swift
-override func viewDidAppear(_ animated: Bool) {
- super.viewDidAppear(animated)
- Task { try? await client.screen(name: "Home") }
-}
-```
-
-`screen` is async and throws, which is why it runs inside a `Task`. Use `try?` to silence errors
-unless you need to handle them.
-
-To include extra properties:
-
-```swift
-Task {
- try? await client.screen(
- name: "BlogPostDetail",
- properties: ["postId": postId]
- )
-}
-```
-
-## 6. Preview panel
-
-Attach the floating action button in the scene delegate (or from a root view controller's
-`viewDidLoad`), gated on a debug flag:
-
-```swift
-#if DEBUG
-PreviewPanelViewController.addFloatingButton(
- to: homeVC,
- client: client,
- contentfulClient: contentfulClient
-)
-#endif
-```
-
-`addFloatingButton(to:client:contentfulClient:)` adds a pinned button in the bottom-trailing corner
-of the host view controller and wires it up to present `PreviewPanelViewController` on tap. The
-preview panel's UI is SwiftUI wrapped in a `UIHostingController`, so it lives happily inside a UIKit
-navigation stack.
-
-While the panel is open, `client.isPreviewPanelOpen` is `true`. `PreviewPanelViewController` updates
-this for you in `viewDidAppear` / `viewWillDisappear`. Use it to decide whether to re-resolve
-entries live:
-
-```swift
-client.$isPreviewPanelOpen
- .receive(on: RunLoop.main)
- .sink { [weak self] _ in self?.tableView.reloadData() }
- .store(in: &cancellables)
-```
-
-The `contentfulClient` parameter is optional — without it the panel displays audiences and
-experiences by ID. Passing `ContentfulHTTPPreviewClient` enables rich names, variant labels, and
-traffic percentages. You can also implement `PreviewContentfulClient` directly if you already have a
-Contentful client you want to reuse.
-
-## A complete example
-
-The UIKit demo's scene delegate and home view controller together show the full pattern — SDK init
-in `scene(_:willConnectTo:options:)`, a `UITableView` that calls `personalizeEntry` in
-`cellForRowAt`, click tracking on the CTA button, screen tracking in `viewDidAppear`, and the
-preview panel FAB attached behind `debug: true`:
-
-```swift
-// UIKitDemo/UIKitDemo/SceneDelegate.swift
-class SceneDelegate: UIResponder, UIWindowSceneDelegate {
- var window: UIWindow?
- let client = OptimizationClient()
- let contentfulClient = ContentfulHTTPPreviewClient(
- spaceId: AppConfig.contentfulSpaceId,
- accessToken: AppConfig.contentfulAccessToken,
- environment: AppConfig.contentfulEnvironment
- )
-
- func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options: UIScene.ConnectionOptions) {
- guard let windowScene = scene as? UIWindowScene else { return }
-
- try? client.initialize(config: OptimizationConfig(
- clientId: AppConfig.optimizationClientId,
- environment: AppConfig.optimizationEnvironment,
- contentfulLocales: ContentfulLocales(default: "en-US"),
- locale: "en-US",
- defaults: StorageDefaults(consent: true),
- debug: true
- ))
-
- let homeVC = HomeViewController(client: client)
- let nav = UINavigationController(rootViewController: homeVC)
-
- window = UIWindow(windowScene: windowScene)
- window?.rootViewController = nav
- window?.makeKeyAndVisible()
-
- PreviewPanelViewController.addFloatingButton(
- to: homeVC,
- client: client,
- contentfulClient: contentfulClient
- )
- }
-}
-```
-
-```swift
-// UIKitDemo/UIKitDemo/Screens/HomeViewController.swift (excerpt)
-final class HomeViewController: UIViewController {
- private let client: OptimizationClient
- private let tableView = UITableView(frame: .zero, style: .grouped)
- private var cancellables = SetTable of Contents
- - -- [Scope and capabilities](#scope-and-capabilities) -- [Reference app](#reference-app) -- [The integration flow](#the-integration-flow) -- [1. Initialize in SceneDelegate](#1-initialize-in-scenedelegate) -- [2. Handle consent](#2-handle-consent) -- [3. Personalize entries](#3-personalize-entries) - - [Calling personalizeEntry](#calling-personalizeentry) - - [Reloading on selectedPersonalizations changes](#reloading-on-selectedpersonalizations-changes) - - [Live updates vs locked variants](#live-updates-vs-locked-variants) -- [4. Track entry interactions](#4-track-entry-interactions) - - [Click tracking](#click-tracking) - - [View tracking](#view-tracking) -- [5. Track screen views](#5-track-screen-views) -- [6. Preview panel](#6-preview-panel) -- [A complete example](#a-complete-example) - - -
-
-
-## 1. Prerequisites
-
-- The Node version pinned in [`.nvmrc`](../../.nvmrc) at the repo root.
-- `pnpm` (the pinned `packageManager` version is in the root [`package.json`](../../package.json);
- install via Corepack).
-- Android Studio (any recent stable release) with the Android SDK platform tools installed.
-- `JAVA_HOME` pointing at a JDK 17+ (AGP 8.7 requires it).
-- `ANDROID_HOME` exported and `adb` on `PATH`. An emulator image or a connected device.
-
-## 2. Fresh-clone bootstrap
-
-From the repository root:
-
-```sh
-pnpm install
-pnpm build:pkgs
-```
-
-`pnpm build:pkgs` builds every workspace package, including `@contentful/optimization-js-bridge`.
-Its `postbuild` script copies the freshly built `optimization-android-bridge.umd.js` into
-`packages/android/ContentfulOptimization/src/main/assets/`, which is where
-`AssetManager.open("optimization-android-bridge.umd.js")` expects to find it at runtime.
-
-Then open the reference impl in Android Studio:
-
-```sh
-cd implementations/android-sdk
-# Either launch Android Studio with this directory, or use the bootstrap script:
-./scripts/bootstrap.sh
-```
-
-`./scripts/bootstrap.sh` is the one-shot path: it starts the mock server, runs
-`./gradlew :app:assembleDebug`, installs the APK, and launches `MainActivity` on the connected
-device or emulator.
-
-To open in the IDE instead: launch Android Studio → **Open** → `implementations/android-sdk/` and
-let Gradle sync. Three run configurations appear in the toolbar once sync completes: **App**, **All
-UI Tests**, **Prepare Env**.
-
-## 3. How the IDE build chain wires together
-
-The reference impl wires the SDK module as a Gradle composite-build local module:
-
-```kotlin
-// implementations/android-sdk/settings.gradle.kts
-include(":ContentfulOptimization")
-project(":ContentfulOptimization").projectDir =
- file("../../packages/android/ContentfulOptimization")
-```
-
-`:app` depends on `project(":ContentfulOptimization")`, so a Gradle build of `:app` rebuilds the SDK
-module from source as a transitive task. There is no published AAR involved.
-
-For the JS bridge,
-[`packages/android/ContentfulOptimization/build.gradle.kts`](../../packages/android/ContentfulOptimization/build.gradle.kts)
-registers a `buildJsBridge` task that invokes
-`pnpm --filter @contentful/optimization-js-bridge build` and wires it as a dependency of `preBuild`:
-
-```kotlin
-val buildJsBridge = tasks.registerTable of Contents
- -- [1. Prerequisites](#1-prerequisites) -- [2. Fresh-clone bootstrap](#2-fresh-clone-bootstrap) -- [3. How the IDE build chain wires together](#3-how-the-ide-build-chain-wires-together) -- [4. The daily edit loop](#4-the-daily-edit-loop) -- [5. Running the reference app](#5-running-the-reference-app) -- [6. Validation cheatsheet](#6-validation-cheatsheet) -- [7. Common pitfalls](#7-common-pitfalls) - -
-
-
-## 1. Prerequisites
-
-- The Node version pinned in [`.nvmrc`](../../.nvmrc) at the repo root. The repository's
- `engines.node` constraint lives in the root [`package.json`](../../package.json).
-- `pnpm` (the pinned `packageManager` version is in the root `package.json`; install via Corepack:
- `corepack enable && corepack prepare pnpm@Table of Contents
- -- [1. Prerequisites](#1-prerequisites) -- [2. Fresh-clone bootstrap](#2-fresh-clone-bootstrap) -- [3. How the IDE build chain wires together](#3-how-the-ide-build-chain-wires-together) -- [4. The daily edit loop](#4-the-daily-edit-loop) -- [5. Running the reference app](#5-running-the-reference-app) -- [6. Validation cheatsheet](#6-validation-cheatsheet) -- [7. Common pitfalls](#7-common-pitfalls) - -
+
+
+## Scope and capabilities
+
+The Compose integration uses the SDK's Compose-native API surface:
+
+- `OptimizationRoot` initializes `OptimizationClient`, provides it through Compose locals, and
+ defines global tracking and live-update defaults.
+- `OptimizedEntry` resolves a personalized Contentful entry and can attach view and tap tracking.
+- `OptimizationLazyColumn` provides viewport context for view tracking inside lazy lists.
+- `ScreenTrackingEffect` emits screen events from a composable screen.
+- `PreviewPanelConfig` enables a developer-only preview panel entry point.
+
+The SDK does not replace your Contentful delivery client. Your application still owns Contentful
+fetching, consent UX, identity policy, navigation, and rendering.
+
+## The integration flow
+
+Most Compose integrations follow this sequence:
+
+1. Add the Maven dependency and create an `OptimizationConfig`.
+2. Wrap the app's root content in `OptimizationRoot`.
+3. Collect consent, or seed consent for demos and trusted internal contexts.
+4. Fetch Contentful entries with linked optimization references.
+5. Render each Contentful entry through `OptimizedEntry`.
+6. Enable view and tap tracking where they fit the screen.
+7. Mark screens with `ScreenTrackingEffect`.
+
+Optional additions include live updates when entries need to react to optimization state changes
+after initial render, and the preview panel when authors or engineers need local audience and
+variant overrides.
+
+The Android reference implementation in this repository demonstrates the same SDK behavior in
+Compose and XML Views shells:
+
+- [Android reference implementation](../../implementations/android-sdk/README.md)
+
+## 1. Add the package and create the config
+
+Add the Android SDK from Maven Central as described in the
+[Optimization Android SDK README](../../packages/android/README.md). In an Android application
+module, the dependency looks like this:
+
+```kotlin
+dependencies {
+ implementation("com.contentful.java:optimization-android:Table of Contents
+ + +- [Scope and capabilities](#scope-and-capabilities) +- [The integration flow](#the-integration-flow) +- [1. Add the package and create the config](#1-add-the-package-and-create-the-config) +- [2. Initialize with OptimizationRoot](#2-initialize-with-optimizationroot) +- [3. Handle consent](#3-handle-consent) +- [4. Personalize entries with OptimizedEntry](#4-personalize-entries-with-optimizedentry) + - [Fetch entries in the expected shape](#fetch-entries-in-the-expected-shape) + - [Render resolved entries](#render-resolved-entries) + - [Use OptimizationLazyColumn for scrollable content](#use-optimizationlazycolumn-for-scrollable-content) +- [5. Track entry interactions](#5-track-entry-interactions) + - [Set global tracking defaults](#set-global-tracking-defaults) + - [Override tracking per entry](#override-tracking-per-entry) +- [6. Track screen views](#6-track-screen-views) +- [Live updates](#live-updates) +- [Preview panel](#preview-panel) +- [Complete example](#complete-example) +- [Reference implementations to compare against](#reference-implementations-to-compare-against) + + +
+
+
+## Scope and capabilities
+
+The XML Views integration uses the SDK's View-based adapter surface:
+
+- `OptimizationManager` initializes one process-wide `OptimizationClient` and stores global tracking
+ and live-update defaults.
+- `OptimizedEntryView` resolves a personalized Contentful entry and can attach view and tap
+ tracking.
+- `TrackingRecyclerView` nudges descendant `OptimizedEntryView` instances to re-check visibility
+ while lists scroll.
+- `ScreenTracker` emits screen events from Activity or Fragment lifecycle methods.
+- `OptimizationManager.attachPreviewPanel(...)` mounts the developer-only preview panel entry point.
+
+The SDK does not replace your Contentful delivery client. Your application still owns Contentful
+fetching, consent UX, identity policy, navigation, and rendering.
+
+## The integration flow
+
+Most XML Views integrations follow this sequence:
+
+1. Add the Maven dependency and create an `OptimizationConfig`.
+2. Initialize `OptimizationManager` from `Application.onCreate`.
+3. Collect consent, or seed consent for demos and trusted internal contexts.
+4. Read `OptimizationManager.client` from activities or fragments that render Contentful content.
+5. Fetch Contentful entries with linked optimization references.
+6. Render each Contentful entry through `OptimizedEntryView`.
+7. Enable view and tap tracking where they fit the screen.
+8. Emit screen events from Activity or Fragment lifecycle methods.
+
+Optional additions include live updates when entries need to react to optimization state changes
+after initial render, and the preview panel when authors or engineers need local audience and
+variant overrides.
+
+The Android reference implementation in this repository demonstrates the same SDK behavior in
+Compose and XML Views shells:
+
+- [Android reference implementation](../../implementations/android-sdk/README.md)
+
+## 1. Add the package and create the config
+
+Add the Android SDK from Maven Central as described in the
+[Optimization Android SDK README](../../packages/android/README.md). In an Android application
+module, the dependency looks like this:
+
+```kotlin
+dependencies {
+ implementation("com.contentful.java:optimization-android:Table of Contents
+ + +- [Scope and capabilities](#scope-and-capabilities) +- [The integration flow](#the-integration-flow) +- [1. Add the package and create the config](#1-add-the-package-and-create-the-config) +- [2. Initialize with OptimizationManager](#2-initialize-with-optimizationmanager) +- [3. Handle consent](#3-handle-consent) +- [4. Personalize entries with OptimizedEntryView](#4-personalize-entries-with-optimizedentryview) + - [Fetch entries in the expected shape](#fetch-entries-in-the-expected-shape) + - [Render resolved entries](#render-resolved-entries) + - [Use TrackingRecyclerView for scrollable content](#use-trackingrecyclerview-for-scrollable-content) +- [5. Track entry interactions](#5-track-entry-interactions) + - [Set global tracking defaults](#set-global-tracking-defaults) + - [Override tracking per entry](#override-tracking-per-entry) +- [6. Track screen views](#6-track-screen-views) +- [Live updates](#live-updates) +- [Preview panel](#preview-panel) +- [Complete example](#complete-example) +- [Reference implementations to compare against](#reference-implementations-to-compare-against) + + +
+
+
+## Scope and capabilities
+
+The SwiftUI integration uses the SDK's SwiftUI-native API surface:
+
+- `OptimizationRoot` initializes `OptimizationClient`, injects it into the environment, and defines
+ global tracking and live-update defaults.
+- `OptimizedEntry` resolves a personalized Contentful entry and can attach view and tap tracking.
+- `OptimizationScrollView` provides viewport context for view tracking inside scrollable content.
+- `.trackScreen(name:)` emits screen events when SwiftUI views appear.
+- `PreviewPanelOverlay` renders a developer-only preview panel entry point.
+
+The SDK does not replace your Contentful delivery client. Your application still owns Contentful
+fetching, consent UX, identity policy, navigation, and rendering.
+
+## The integration flow
+
+Most SwiftUI integrations follow this sequence:
+
+1. Add the Swift Package and create an `OptimizationConfig`.
+2. Wrap the app's root content in `OptimizationRoot`.
+3. Collect consent, or seed consent for demos and trusted internal contexts.
+4. Fetch Contentful entries with linked optimization references.
+5. Render each Contentful entry through `OptimizedEntry`.
+6. Enable view and tap tracking where they fit the screen.
+7. Mark screens with `.trackScreen(name:)`.
+
+Optional additions include live updates when entries need to react to optimization state changes
+after initial render, and the preview panel when authors or engineers need local audience and
+variant overrides.
+
+The iOS reference implementation in this repository demonstrates the same SDK behavior in SwiftUI
+and UIKit shells:
+
+- [iOS reference implementation](../../implementations/ios-sdk/README.md)
+
+## 1. Add the package and create the config
+
+Add `ContentfulOptimization` through Swift Package Manager as described in the
+[Optimization iOS SDK README](../../packages/ios/ContentfulOptimization/README.md). Then create an
+`OptimizationConfig` with the Optimization client ID and the Contentful locale information your app
+uses when fetching entries:
+
+```swift
+let config = OptimizationConfig(
+ clientId: "your-client-id",
+ environment: "master",
+ contentfulLocales: ContentfulLocales(default: "en-US"),
+ locale: "en-US",
+ defaults: StorageDefaults(consent: true),
+ debug: true
+)
+```
+
+Only `clientId` is required. Use `defaults: StorageDefaults(consent: true)` only when the app can
+start with consent already granted, such as a demo or an internal validation app. For production
+apps, connect `client.consent(true)` and `client.consent(false)` to the app's consent UI.
+
+Use `contentfulLocales` and `locale` when the same screen renders localized Contentful entries. For
+the full locale model, see
+[Locale handling in the Optimization SDK Suite](../concepts/locale-handling-in-the-optimization-sdk-suite.md).
+
+## 2. Initialize with OptimizationRoot
+
+Wrap your root SwiftUI content in `OptimizationRoot`. It owns the `OptimizationClient`, initializes
+the SDK, and provides the ready client to descendant views as an environment object.
+
+```swift
+import ContentfulOptimization
+import SwiftUI
+
+@main
+struct MyApp: App {
+ var body: some Scene {
+ WindowGroup {
+ OptimizationRoot(
+ config: config,
+ trackViews: true,
+ trackTaps: false,
+ liveUpdates: false
+ ) {
+ RootView()
+ }
+ }
+ }
+}
+```
+
+Inside the provider tree, read the client from the environment:
+
+```swift
+struct AccountControls: View {
+ @EnvironmentObject private var client: OptimizationClient
+
+ var body: some View {
+ Button("Identify") {
+ Task {
+ try? await client.identify(userId: "user-123", traits: ["plan": "pro"])
+ }
+ }
+ }
+}
+```
+
+`OptimizationClient` is `@MainActor`. Call it from SwiftUI view tasks, event handlers, or explicit
+main-actor tasks. For lifecycle details, see
+[iOS SDK runtime and interaction mechanics](../concepts/ios-sdk-runtime-and-interaction-mechanics.md#lifecycle-and-main-actor).
+
+## 3. Handle consent
+
+The SDK blocks most Analytics events until consent is granted. `identify` and `screen` remain
+allowed before consent so a mobile journey can establish profile context and anonymous screen
+analytics.
+
+```swift
+struct ConsentBanner: View {
+ @EnvironmentObject private var client: OptimizationClient
+
+ var body: some View {
+ VStack {
+ Text("We use analytics to personalize content.")
+ HStack {
+ Button("Accept") { client.consent(true) }
+ Button("Reject") { client.consent(false) }
+ }
+ }
+ }
+}
+```
+
+Use `client.state.consent` to decide whether the consent UI still needs to render:
+
+```swift
+struct ConsentGateTable of Contents
+ + +- [Scope and capabilities](#scope-and-capabilities) +- [The integration flow](#the-integration-flow) +- [1. Add the package and create the config](#1-add-the-package-and-create-the-config) +- [2. Initialize with OptimizationRoot](#2-initialize-with-optimizationroot) +- [3. Handle consent](#3-handle-consent) +- [4. Personalize entries with OptimizedEntry](#4-personalize-entries-with-optimizedentry) + - [Fetch entries in the expected shape](#fetch-entries-in-the-expected-shape) + - [Render resolved entries](#render-resolved-entries) + - [Use OptimizationScrollView for scrollable content](#use-optimizationscrollview-for-scrollable-content) +- [5. Track entry interactions](#5-track-entry-interactions) + - [Set global tracking defaults](#set-global-tracking-defaults) + - [Override tracking per entry](#override-tracking-per-entry) +- [6. Track screen views](#6-track-screen-views) +- [Live updates](#live-updates) +- [Preview panel](#preview-panel) +- [Complete example](#complete-example) +- [Reference implementations to compare against](#reference-implementations-to-compare-against) + + +
+
+
+## Scope and capabilities
+
+The UIKit integration uses `OptimizationClient` directly. The SDK does not provide UIKit-native view
+equivalents for `OptimizedEntry` or `OptimizationScrollView`, so the application decides where to
+resolve entries and when to emit interaction tracking.
+
+UIKit apps typically use:
+
+- `OptimizationClient` as a long-lived object owned by `SceneDelegate` or an app-level coordinator.
+- `client.personalizeEntry(baseline:personalizations:)` during cell or view configuration.
+- `client.trackView(_:)` and `client.trackClick(_:)` from visibility callbacks and control actions.
+- `client.screen(name:)` from view-controller lifecycle methods.
+- `PreviewPanelViewController` behind a debug or internal-build flag.
+
+The SDK does not replace your Contentful delivery client. Your application still owns Contentful
+fetching, consent UX, identity policy, navigation, and rendering.
+
+## The integration flow
+
+Most UIKit integrations follow this sequence:
+
+1. Add the Swift Package and create an `OptimizationConfig`.
+2. Create a shared `OptimizationClient` and call `initialize(config:)`.
+3. Collect consent, or seed consent for demos and trusted internal contexts.
+4. Pass the client into the view controllers that render Contentful content.
+5. Fetch Contentful entries with linked optimization references.
+6. Resolve entries in cell or view configuration with
+ `client.personalizeEntry(baseline:personalizations:)`.
+7. Track taps from controls and track views from visibility-duration logic.
+8. Emit screen events from view-controller lifecycle methods.
+
+Optional additions include live-update redraws when selected personalizations change, and the
+preview panel when authors or engineers need local audience and variant overrides.
+
+The iOS reference implementation in this repository demonstrates the same SDK behavior in SwiftUI
+and UIKit shells:
+
+- [iOS reference implementation](../../implementations/ios-sdk/README.md)
+
+## 1. Add the package and create the config
+
+Add `ContentfulOptimization` through Swift Package Manager as described in the
+[Optimization iOS SDK README](../../packages/ios/ContentfulOptimization/README.md). Then create an
+`OptimizationConfig` with the Optimization client ID and the Contentful locale information your app
+uses when fetching entries:
+
+```swift
+let config = OptimizationConfig(
+ clientId: "your-client-id",
+ environment: "master",
+ contentfulLocales: ContentfulLocales(default: "en-US"),
+ locale: "en-US",
+ defaults: StorageDefaults(consent: true),
+ debug: true
+)
+```
+
+Only `clientId` is required. Use `defaults: StorageDefaults(consent: true)` only when the app can
+start with consent already granted, such as a demo or an internal validation app. For production
+apps, connect `client.consent(true)` and `client.consent(false)` to the app's consent UI.
+
+Use `contentfulLocales` and `locale` when the same screen renders localized Contentful entries. For
+the full locale model, see
+[Locale handling in the Optimization SDK Suite](../concepts/locale-handling-in-the-optimization-sdk-suite.md).
+
+## 2. Initialize in SceneDelegate
+
+Own the `OptimizationClient` from `SceneDelegate` when the client lifetime needs to match the scene.
+Pass that same instance into the root view controller and any child controller that resolves entries
+or tracks events.
+
+```swift
+import ContentfulOptimization
+import UIKit
+
+class SceneDelegate: UIResponder, UIWindowSceneDelegate {
+ var window: UIWindow?
+ let client = OptimizationClient()
+
+ func scene(
+ _ scene: UIScene,
+ willConnectTo session: UISceneSession,
+ options connectionOptions: UIScene.ConnectionOptions
+ ) {
+ guard let windowScene = scene as? UIWindowScene else { return }
+
+ try? client.initialize(config: config)
+
+ let home = HomeViewController(client: client)
+ let navigation = UINavigationController(rootViewController: home)
+
+ window = UIWindow(windowScene: windowScene)
+ window?.rootViewController = navigation
+ window?.makeKeyAndVisible()
+ }
+}
+```
+
+`OptimizationClient` is `@MainActor`. View-controller lifecycle methods already run on the main
+thread, but asynchronous callbacks that call the client must return to the main actor first. For
+lifecycle details, see
+[iOS SDK runtime and interaction mechanics](../concepts/ios-sdk-runtime-and-interaction-mechanics.md#lifecycle-and-main-actor).
+
+## 3. Handle consent
+
+The SDK blocks most Analytics events until consent is granted. `identify` and `screen` remain
+allowed before consent so a mobile journey can establish profile context and anonymous screen
+analytics.
+
+Connect the app's consent controls to the client:
+
+```swift
+@objc private func acceptTapped() {
+ client.consent(true)
+}
+
+@objc private func rejectTapped() {
+ client.consent(false)
+}
+```
+
+To react to consent changes, subscribe to `client.$state`:
+
+```swift
+client.$state
+ .map(\.consent)
+ .removeDuplicates()
+ .receive(on: RunLoop.main)
+ .sink { [weak self] value in
+ self?.updateConsentUI(value)
+ }
+ .store(in: &cancellables)
+```
+
+## 4. Personalize entries
+
+### Resolve entries in view code
+
+Fetch entries from Contentful as single-locale JSON-shaped dictionaries and include linked
+optimization references in the payload. Then resolve each entry where the UIKit view configures its
+content:
+
+```swift
+func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
+ let cell = tableView.dequeueReusableCell(
+ withIdentifier: BlogPostCardCell.reuseIdentifier,
+ for: indexPath
+ ) as! BlogPostCardCell
+
+ let resolved = client.personalizeEntry(
+ baseline: posts[indexPath.row],
+ personalizations: client.selectedPersonalizations
+ )
+
+ cell.configure(with: resolved.entry)
+ return cell
+}
+```
+
+`personalizeEntry` is synchronous. It returns the baseline entry unchanged when the SDK has no
+matching selected personalization, when the entry has no optimization references, or when the linked
+variant data is not present in the Contentful payload. For details, see
+[Entry personalization and variant resolution](../concepts/entry-personalization-and-variant-resolution.md).
+
+### React to selected personalization changes
+
+When `client.selectedPersonalizations` changes, the app decides whether visible UIKit views need to
+re-resolve entries. A table or collection view can redraw affected cells:
+
+```swift
+client.$selectedPersonalizations
+ .dropFirst()
+ .receive(on: RunLoop.main)
+ .sink { [weak self] _ in
+ self?.tableView.reloadData()
+ }
+ .store(in: &cancellables)
+```
+
+For locked content, capture `client.selectedPersonalizations` when the screen loads and pass that
+snapshot into each `personalizeEntry` call.
+
+## 5. Track entry interactions
+
+### Track taps
+
+Emit tap events from `UIControl` actions or gesture handlers:
+
+```swift
+ctaView.onButtonTap = { [weak self] in
+ guard let self else { return }
+
+ Task { @MainActor in
+ try? await self.client.trackClick(TrackClickPayload(
+ componentId: ctaEntryId,
+ experienceId: experienceId,
+ variantIndex: variantIndex
+ ))
+ }
+}
+```
+
+Use `entry.sys.id` as `componentId`. Set `variantIndex` to `0` for the baseline entry and to the
+selected variant index when `personalizeEntry` returns personalization metadata.
+
+### Track views
+
+UIKit apps compute visibility and duration in application code, then send a `TrackViewPayload`:
+
+```swift
+Task { @MainActor in
+ try? await client.trackView(TrackViewPayload(
+ componentId: entryId,
+ viewId: viewId,
+ experienceId: experienceId,
+ variantIndex: variantIndex,
+ viewDurationMs: durationMs,
+ sticky: nil
+ ))
+}
+```
+
+A common table or collection view pattern is:
+
+1. Record a timestamp when a cell becomes visible.
+2. Emit periodic duration updates while it remains visible.
+3. Emit a final duration update when it stops being visible.
+
+For the default SwiftUI thresholds and shared event-delivery behavior, see
+[iOS SDK runtime and interaction mechanics](../concepts/ios-sdk-runtime-and-interaction-mechanics.md#tracking-mechanics).
+
+## 6. Track screen views
+
+Call `client.screen(name:)` from `viewDidAppear(_:)`:
+
+```swift
+override func viewDidAppear(_ animated: Bool) {
+ super.viewDidAppear(animated)
+
+ Task { @MainActor in
+ try? await client.screen(name: "Home")
+ }
+}
+```
+
+Include properties when the screen name needs additional context:
+
+```swift
+Task { @MainActor in
+ try? await client.screen(
+ name: "BlogPostDetail",
+ properties: ["postId": postId]
+ )
+}
+```
+
+## Live updates
+
+UIKit does not lock or re-resolve entries automatically. The app chooses between two patterns:
+
+- **Live updates** - Resolve entries during cell or view configuration and redraw when
+ `selectedPersonalizations` changes.
+- **Locked variants** - Capture selected personalizations when the screen loads and keep resolving
+ against that snapshot.
+
+The preview panel sets `client.isPreviewPanelOpen` while it is visible. Use that value when the app
+needs to redraw in live mode for preview sessions and keep production screens locked.
+
+## Preview panel
+
+Gate the preview panel behind a debug or internal-build flag. `PreviewPanelViewController` adds a
+floating button to a host view controller and presents the panel when tapped.
+
+```swift
+#if DEBUG
+PreviewPanelViewController.addFloatingButton(
+ to: home,
+ client: client,
+ contentfulClient: contentfulClient
+)
+#endif
+```
+
+The `contentfulClient` parameter is optional. Passing a `PreviewContentfulClient` enables audience
+and experience names in the panel; without it, the panel displays identifiers.
+
+The preview panel's UI is SwiftUI wrapped for UIKit, so it can be presented from a UIKit navigation
+stack without changing the rest of the app.
+
+## Complete example
+
+This example combines scene-level initialization, entry resolution in table-cell configuration,
+screen tracking, selected-personalization redraws, and preview-panel mounting:
+
+```swift
+final class HomeViewController: UIViewController {
+ private let client: OptimizationClient
+ private var posts: [[String: Any]] = []
+ private var cancellables = SetTable of Contents
+ + +- [Scope and capabilities](#scope-and-capabilities) +- [The integration flow](#the-integration-flow) +- [1. Add the package and create the config](#1-add-the-package-and-create-the-config) +- [2. Initialize in SceneDelegate](#2-initialize-in-scenedelegate) +- [3. Handle consent](#3-handle-consent) +- [4. Personalize entries](#4-personalize-entries) + - [Resolve entries in view code](#resolve-entries-in-view-code) + - [React to selected personalization changes](#react-to-selected-personalization-changes) +- [5. Track entry interactions](#5-track-entry-interactions) + - [Track taps](#track-taps) + - [Track views](#track-views) +- [6. Track screen views](#6-track-screen-views) +- [Live updates](#live-updates) +- [Preview panel](#preview-panel) +- [Complete example](#complete-example) +- [Reference implementations to compare against](#reference-implementations-to-compare-against) + + +
+
+ 
+
+
Contentful Personalization & Analytics
+ +Optimization Android SDK
+ +
+
+[Guides](https://contentful.github.io/optimization/documents/Documentation.Guides.html) ·
+[Reference](https://contentful.github.io/optimization) · [Contributing](../../CONTRIBUTING.md)
+
+
+
+> [!WARNING]
+>
+> The Optimization SDK Suite is pre-release (alpha). Breaking changes can be published at any time.
+
+The Optimization Android SDK is a pre-release Kotlin Android library for native Android
+applications. It is part of the [Contentful Optimization SDK Suite](../../README.md) and runs shared
+optimization behavior through a local QuickJS bridge while Kotlin code owns native app concerns such
+as persistence, networking, lifecycle handling, Jetpack Compose UI, XML Views UI, and preview-panel
+UI.
+
+
+
+
+## Getting started
+
+### Requirements
+
+- Android `minSdk` 24 or later.
+- Java 11 bytecode support in the consuming Android project.
+- A Kotlin Android application built with Jetpack Compose or XML Views.
+- Maven Central configured in the consuming build.
+
+### Add the dependency
+
+Add the SDK to your Android application module:
+
+```kotlin
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ implementation("com.contentful.java:optimization-android: