Integrate the Optimization iOS SDK in a UIKit app

Overview

Use this guide to add Contentful personalization to a UIKit app with the ContentfulOptimization Swift Package. By the end of the quick start, the SDK is running in your scene and one screen event has passed the SDK’s consent gate, with a visible label confirming it.

New to personalization? Here is the whole idea in five points:

• In Contentful you author variants of an entry and attach them to an experience — a rule that decides which visitors see which variant.
• As the app runs, Contentful’s Experience API looks at who the visitor is and picks the variant for each experience. Swapping a fetched entry for its picked variant is called resolving the entry.
• The Experience API also returns a profile: the anonymous, per-visitor identity and state used to keep personalization consistent across requests or app launches.
• Your app hands a Contentful entry to the SDK at the point where that entry becomes output. The SDK gives back the selected variant, or the original entry when no variant applies—the baseline fallback.
• You render the returned entry with the same application components you already use.

The iOS SDK persists the profile in UserDefaults across app launches when persistence consent allows it.

That is enough to start. The guide introduces policy and optional capabilities at the point you need them.

You will get there in two milestones:

• Milestone 1 — the SDK initialized in your scene and one accepted screen event (the quick start below). Once your app also hands the SDK a fetched Contentful entry, that entry resolves to a variant or the baseline through resolveOptimizedEntry (the Contentful fetching and entry resolution section). This is complete and shippable on its own.
• Milestone 2 — the opt-in layers (later). Consent handoff, interaction tracking, identity, Custom Flags, live updates, the preview panel, runtime locale changes, and offline delivery, each introduced by the section that needs it. Start with Consent and privacy-policy handoff.

This guide uses ContentfulOptimization. UIKit apps drive the SDK through the imperative OptimizationClient: you create and initialize one client, hold it for the scene or app lifetime, and inject it into the view controllers that track events or resolve entries. The SDK does not replace your app’s Contentful client — your UIKit app still owns Contentful fetching, link resolution, consent UX, identity policy, navigation, caching, and rendering. If your app renders through SwiftUI views instead, use the Integrate the Optimization iOS SDK in a SwiftUI app guide.

Quick start

Most UIKit + Contentful apps share one shape: a SceneDelegate builds the window and a root view controller, and a UIViewController presents content. This quick start assumes that shape and proves the smallest result: the SDK initializes in your scene and one screen event is accepted, and a visible label flips to confirm it. It owns one OptimizationClient in the scene, initializes it, injects it into the first view controller, and tracks the current screen from viewDidAppear(_:).

This quick start assumes your application policy permits Optimization to start with accepted consent and renders no end-user consent UI, so it seeds StorageDefaults(consent: true) — the shorthand that accepts both consent axes at once. If personalization must wait for a consent decision, keep this structure and add the Consent and privacy-policy handoff step before you ship, which explains the two axes and the split form that sets them separately.

1. Add the ContentfulOptimization Swift Package to your app target from https://github.com/contentful/optimization.swift (in Xcode: File > Add Package Dependencies), then build and run the app target once so Swift Package Manager resolves and compiles the package. The package supports iOS 15+ and macOS 12+.

2. Own one client in your existing SceneDelegate, initialize it, and inject it into your first view controller. initialize(config:) is synchronous and throws (it runs bridge setup inline on the main actor), so call it with try/try? and no await.

   Adapt this to your use case:

   1
    import UIKit
   2
   +import ContentfulOptimization
   3
   4
    final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
   5
        var window: UIWindow?
   6
   7
   +    // Own one client for the whole scene, then inject this same instance
   8
   +    // into the view controllers that track events or resolve entries.
   9
   +    let client = OptimizationClient()
   10
   11
        func scene(
   12
            _ scene: UIScene,
   13
            willConnectTo _: UISceneSession,
   14
            options _: UIScene.ConnectionOptions
   15
        ) {
   16
            guard let windowScene = scene as? UIWindowScene else { return }
   17
   18
   +        // Synchronous throws, not async: call with try/try? and no await.
   19
   +        // StorageDefaults seeds accepted consent at startup for this proof.
   20
   +        try? client.initialize(config: OptimizationConfig(
   21
   +            clientId: "your-optimization-client-id",
   22
   +            defaults: StorageDefaults(consent: true),
   23
   +            logLevel: .debug,
   24
   +            onEventBlocked: { blocked in
   25
   +                // If the label reads "blocked", this prints why.
   26
   +                print("Optimization blocked \(blocked.method): \(blocked.reason)")
   27
   +            }
   28
   +        ))
   29
   30
   -        let home = HomeViewController()
   31
   +        let home = HomeViewController(client: client)
   32
            window = UIWindow(windowScene: windowScene)
   33
            window?.rootViewController = UINavigationController(rootViewController: home)
   34
            window?.makeKeyAndVisible()
   35
        }
   36
    }

   The unchanged lines above are illustrative context to match against your own SceneDelegate, not a block to paste over it. StorageDefaults is an SDK config type; StorageDefaults(consent: true) grants both consent axes at startup.

3. Track the current screen from a view controller and reflect the outcome in a label. HomeViewController below is illustrative app shape — adapt it to a screen you already render, keeping the client-injection initializer and the trackCurrentScreen call in viewDidAppear.

   Adapt this to your use case:

   1
   import ContentfulOptimization
   2
   import UIKit
   3
   4
   final class HomeViewController: UIViewController {
   5
       private let client: OptimizationClient
   6
       private let statusLabel = UILabel()
   7
   8
       init(client: OptimizationClient) {
   9
           self.client = client
   10
           super.init(nibName: nil, bundle: nil)
   11
       }
   12
   13
       @available(*, unavailable)
   14
       required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
   15
   16
       override func viewDidLoad() {
   17
           super.viewDidLoad()
   18
           statusLabel.text = "Waiting for Optimization"
   19
           statusLabel.textAlignment = .center
   20
           statusLabel.translatesAutoresizingMaskIntoConstraints = false
   21
           view.addSubview(statusLabel)
   22
           NSLayoutConstraint.activate([
   23
               statusLabel.centerXAnchor.constraint(equalTo: view.centerXAnchor),
   24
               statusLabel.centerYAnchor.constraint(equalTo: view.centerYAnchor),
   25
           ])
   26
       }
   27
   28
       override func viewDidAppear(_ animated: Bool) {
   29
           super.viewDidAppear(animated)
   30
           Task { @MainActor in
   31
               // Track the current screen once UIKit has made it visible.
   32
               let result = try? await client.trackCurrentScreen(name: "Home")
   33
               statusLabel.text = result?.accepted == true
   34
                   ? "Optimization screen event accepted"
   35
                   : "Optimization screen event blocked"
   36
           }
   37
       }
   38
   }

4. Verify the first run. Launch the app; the label reads Optimization screen event accepted. trackCurrentScreen returns an EventEmissionResult — an SDK result type whose accepted flag is true when the event passed the SDK’s local consent and allow-list gate and was emitted or queued for delivery. accepted does not confirm that Contentful received the event, only that the local gate let it through. Because StorageDefaults(consent: true) grants consent and screen is on the SDK’s default pre-consent allow-list, the event is accepted. If the label reads Optimization screen event blocked instead, there are two causes to tell apart. If the consent gate rejected the event, the onEventBlocked callback prints a line prefixed Optimization blocked naming the reason and method — search the Xcode console for that prefix. If instead the client never initialized (for example a wrong clientId), try? in step 2 swallowed the thrown error, so onEventBlocked never fires; the SDK’s logLevel: .debug output under the com.contentful.optimization subsystem shows the failed init. To see the init error directly, temporarily replace try? with a do { try client.initialize(...) } catch { print(error) } block.

Before you start

The sections below walk the integration in order. First, gather the few things you can only get from outside this guide:

• A UIKit app and Xcode, with your own Contentful fetching already working and the ability to add a Swift package and run an Xcode build. The SDK is added through Swift Package Manager and supports iOS 15+ and macOS 12+.
• Contentful delivery credentials — space ID, delivery token, environment, and one concrete locale — read from your app’s configuration layer.
• At least one entry with a variant attached to an experience, authored in Contentful. Without an authored variant, the integration can still run correctly while returning the baseline, so you cannot yet distinguish working personalization from a content-authoring gap. For the first personalized-content test, target all visitors so the test request or visitor matches automatically.
• Your Optimization project values — client ID and environment, from your Optimization project settings. The environment defaults to main, so pass it only when your setup differs. The Experience API (which picks variants) and the Insights API (which receives event and interaction delivery) each have a base URL that defaults correctly; you only set them for mocks or non-default hosts (see Package installation and SDK configuration).

You do not need a setup inventory up front. Everything else — consent, entry resolution, screen tracking, interaction tracking, identity, live updates, preview, runtime locale changes, offline delivery — is introduced by the section that needs it.

Core integration

Package installation and SDK configuration

Integration category: Required for first integration

Add the package from https://github.com/contentful/optimization.swift, then build and run the app target once in Xcode so Swift Package Manager resolves and compiles it before you wire the client. Most apps add it through Xcode’s File > Add Package Dependencies; SwiftPM-manifest targets add it in Package.swift.

Adapt this to your use case:

1
dependencies: [
2
    .package(url: "https://github.com/contentful/optimization.swift.git", from: "<version>"),
3
],
4
targets: [
5
    .target(
6
        name: "MyApp",
7
        dependencies: [
8
            .product(name: "ContentfulOptimization", package: "optimization.swift"),
9
        ]
10
    ),
11
],

Configure the SDK with your Optimization client ID and the environment that matches your Contentful setup. Only clientId is required by the initializer.

1. Pass clientId from your configuration layer.
2. Pass environment only when it is not the default main.
3. Pass locale when Experience API requests and event context must use the same language as the Contentful entries you render.
4. Set api base URLs (experienceBaseUrl/insightsBaseUrl) only for mock, staging, or other non-default endpoints — both default correctly otherwise.
5. Keep logLevel at its default .error in production unless your operational policy allows more verbose logging.

Adapt this to your use case:

1
let appLocale = "en-US"
2
3
let config = OptimizationConfig(
4
    clientId: "your-optimization-client-id",
5
    // environment defaults to "main"; pass it only when your setup differs.
6
    // Keep SDK event and Experience locale aligned with rendered CDA entries.
7
    locale: appLocale
8
)

For package-level installation notes, see the Optimization iOS SDK README.

Client lifetime and UIKit injection

Integration category: Required for first integration

UIKit integrations use OptimizationClient directly. Keep one initialized client alive for the scene or app lifetime, then inject that instance into every controller or view that resolves entries or tracks events.

1. Create the client in SceneDelegate, AppDelegate, or an app-level dependency container, and call initialize(config:) before presenting content that uses Optimization.
2. Pass the initialized client through initializers instead of creating separate clients in child controllers.
3. Return to the main actor before calling the client from asynchronous callbacks; OptimizationClient is @MainActor.
4. Gate UI on readiness when needed: the client publishes isInitialized, so observe client.$isInitialized when a screen must wait for setup before it reads SDK state.

Adapt this to your use case:

1
final class ProductViewController: UIViewController {
2
    private let client: OptimizationClient
3
4
    // Inject the app-owned client instead of creating a new one here.
5
    init(client: OptimizationClient) {
6
        self.client = client
7
        super.init(nibName: nil, bundle: nil)
8
    }
9
10
    @available(*, unavailable)
11
    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
12
13
    override func viewDidAppear(_ animated: Bool) {
14
        super.viewDidAppear(animated)
15
        Task { @MainActor in
16
            // Hop back to the main actor before any client call.
17
            _ = try? await client.trackCurrentScreen(name: "ProductList")
18
        }
19
    }
20
}

Use destroy() only for test teardown or a deliberate SDK teardown flow, not for normal navigation between UIKit screens. For lifecycle and main-actor mechanics, see iOS SDK runtime and interaction mechanics.

Consent and privacy-policy handoff

Integration category: Common but policy-dependent

Consent policy belongs to your application. The SDK provides the runtime gate; your app or CMP owns notice, user choices, consent records, jurisdiction logic, and withdrawal behavior. Consent has two independent axes: event consent (may the SDK personalize and emit events) and persistence consent (may the SDK store profile continuity in UserDefaults).

1. Use StorageDefaults(consent: true) at startup only when application policy permits SDK activity at launch.
2. Leave defaults unset when the app must collect a choice before gated events can emit, and call consent(...) from the app-owned banner, CMP callback, or settings flow.
3. Use consent(_:) for the boolean shorthand that sets both axes, or consent(events:persistence:) to set them independently.
4. Pass allowedEventTypes: [] for strict opt-in, so no SDK event emits before event consent.
5. Observe client.$state when the UI must reflect event consent or persistence consent.

Adapt this to your use case:

1
@objc private func acceptTapped() {
2
    // Boolean consent sets both event emission and durable profile continuity.
3
    client.consent(true)
4
}
5
6
@objc private func rejectTapped() {
7
    client.consent(false)
8
}
9
10
@objc private func allowEventsOnlyTapped() {
11
    // Split consent: emit events but keep profile continuity session-only.
12
    client.consent(events: true, persistence: false)
13
}

When allowedEventTypes is unset, the SDK’s default pre-consent allow-list lets identify and screen emit before event consent, so a mobile journey can establish profile context and anonymous screen analytics. Entry views, entry taps, and custom track events are blocked until consent is accepted. A custom allowedEventTypes replaces that default, and allowedEventTypes: [] blocks every SDK event until consent is accepted. consent(false) clears both axes, purges queues, and clears durable continuity while in-memory state stays usable until reset or teardown.

Adapt this to your use case:

1
let config = OptimizationConfig(
2
    clientId: "your-optimization-client-id",
3
    // Replaces the default pre-consent allow-list of identify and screen with
4
    // strict opt-in: nothing emits until consent is accepted.
5
    allowedEventTypes: []
6
)

For the full consent responsibility model, see Consent management in the Optimization SDK Suite.

Contentful fetching and entry resolution

Integration category: Required for first integration

The iOS SDK has no fetch-by-ID path, so your app always owns the Contentful Delivery API fetch. You fetch the entry, hand it to the SDK, and the SDK resolves it locally against the selected optimizations for the current visitor.

client.selectedOptimizations (plural) is the SDK’s current set of selected optimizations — one selection per experience the visitor’s profile matched, published on the client and updated from Experience API responses. resolveOptimizedEntry(baseline:selectedOptimizations:) returns a ResolvedOptimizedEntry — an SDK result type that wraps the resolved entry, the single selectedOptimization (singular) that was applied to it, and an optimizationContextId identifying the optimization context, the profile-and-selection state that produced the variant. Note the one-letter difference: selectedOptimizations is the set you pass in (or the SDK resolves against), while selectedOptimization is the one selection returned on the result.

1. Fetch entries with one concrete Contentful locale. Do not pass all-locale payloads (locale=* or all-locale helpers) into entry resolution — they fall back to baseline.
2. Include linked entries deeply enough to resolve the optimization links. nt_experiences (plural) is the SDK-fixed link field the SDK reads on an optimized entry; it links that entry’s nt_experience (singular) experiences, and each experience links its nt_variants and nt_audience entries. These are SDK-owned Optimization content-model names, not names you choose; your fetch must include deeply enough to pull them back in one payload. include: 10 is the reference implementation’s pattern.
3. Keep the app’s Contentful locale aligned with SDK locale when rendered content and events must use the same language.
4. Resolve entries during view, cell, or wrapper configuration.
5. Render result.entry. Use result.selectedOptimization and result.optimizationContextId only when building tracking payloads.

Follow this pattern:

1
// contentfulEntryService is reader-owned: your app's CDA fetch and link resolution.
2
let entry = try await contentfulEntryService.fetchEntry(
3
    id: entryId,
4
    include: 10,
5
    // Resolve and pass one concrete CDA locale, not locale=* payloads.
6
    locale: appLocale
7
)
8
9
let result = client.resolveOptimizedEntry(
10
    baseline: entry,
11
    selectedOptimizations: client.selectedOptimizations
12
)
13
14
// Always render result.entry; it is the variant when one applies, or the
15
// baseline entry otherwise. contentView is reader-owned UI.
16
contentView.configure(with: result.entry)

resolveOptimizedEntry is synchronous and fail-soft: it never throws or breaks the UI. It returns the baseline entry unchanged (with selectedOptimization and optimizationContextId nil) when the client is not initialized, when the entry is not optimized, when no selected optimization matches, when linked optimization data is missing, or when the selected variant is not present in the payload. Passing nil for selectedOptimizations tells the resolver to use the SDK’s current selection state; passing an explicit snapshot resolves against exactly that (used for locked screens in Live updates and locked variants). For deeper resolver mechanics, see Entry optimization and variant resolution.

Screen and navigation tracking

Integration category: Required for first integration

The quick start tracked one screen. Real UIKit navigation repeats lifecycle callbacks across modal, tab, and navigation-controller transitions, so choose the method that matches the event you want.

Use trackCurrentScreen(name:properties:routeKey:) for UIKit lifecycle and navigation tracking: it deduplicates the current route in the SDK by routeKey (which defaults to name), so a repeat of the same current screen is skipped and a blocked attempt is retried once consent allows. Use screen(name:properties:) only for intentional one-off raw screen events, which carry no dedupe.

1. Emit from viewDidAppear(_:) so UIKit has completed the visible transition.
2. Use a stable screen name that maps to your analytics model.
3. Pass a stable routeKey when several instances of one destination should still count as the same current screen, or when the default name-based key would collide.
4. Add properties only when the downstream analysis needs them.

Adapt this to your use case:

1
override func viewDidAppear(_ animated: Bool) {
2
    super.viewDidAppear(animated)
3
    Task { @MainActor in
4
        // entryId is reader-owned: the value that identifies this destination.
5
        _ = try? await client.trackCurrentScreen(
6
            name: "ProductDetail",
7
            properties: ["entryId": entryId],
8
            // Stable route key prevents duplicate current-screen events when the
9
            // lifecycle callback repeats for the same destination.
10
            routeKey: "product-detail-\(entryId)"
11
        )
12
    }
13
}

For shared tracking mechanics and event delivery, see iOS SDK runtime and interaction mechanics.

Entry interaction tracking

Integration category: Common but policy-dependent

UIKit does not automatically infer when a user tapped a Contentful entry or when an entry met a visibility threshold, so your app owns the geometry and the app decides whether these events are allowed by its Analytics and privacy policy. Entry views deliver on the wire as component events; entry taps as component_click.

Entry taps. Build a TrackingMetadata (an SDK helper type that derives componentId/experienceId/variantIndex from an entry and its selected optimization) from the resolution you already rendered, then pass its fields to a TrackClickPayload (an SDK payload type). Building the metadata from the stored resolution — not by re-resolving at tap time — makes the tap carry the same optimization context that produced the rendered variant.

1. Resolve and render the entry, and store the ResolvedOptimizedEntry you rendered from.
2. On tap, build TrackingMetadata from the stored baseline entry and its selectedOptimization.
3. Call client.trackClick(TrackClickPayload(...)) from a UIControl action or gesture recognizer. For gesture recognizers, gate the dispatch to the completed gesture state instead of suppressing later taps for the view’s lifetime.

Adapt this to your use case:

1
// Reader-owned: your view or cell stores the resolution it rendered from.
2
private var latestBaselineEntry: [String: Any]?
3
private var latestResolution: ResolvedOptimizedEntry?
4
5
func configure(with entry: [String: Any]) {
6
    // entry is a reader-owned Contentful entry your app fetched.
7
    let result = client.resolveOptimizedEntry(
8
        baseline: entry,
9
        selectedOptimizations: client.selectedOptimizations
10
    )
11
    latestBaselineEntry = entry
12
    latestResolution = result
13
    contentView.configure(with: result.entry) // contentView is reader-owned UI.
14
}
15
16
@objc private func primaryButtonTapped() {
17
    guard let entry = latestBaselineEntry, let result = latestResolution else { return }
18
19
    // TrackingMetadata carries the optimization context that produced the
20
    // rendered variant, so the tap matches what the visitor actually saw.
21
    let metadata = TrackingMetadata(
22
        entry: entry,
23
        optimizationContextId: result.optimizationContextId,
24
        selectedOptimization: result.selectedOptimization
25
    )
26
27
    Task { @MainActor in
28
        try? await client.trackClick(TrackClickPayload(
29
            componentId: metadata.componentId,
30
            experienceId: metadata.experienceId,
31
            optimizationContextId: metadata.optimizationContextId,
32
            variantIndex: metadata.variantIndex
33
        ))
34
    }
35
}

Entry views. Feed app-owned scroll or layout geometry to a ViewTrackingController — the SDK’s imperative view-timing engine for UIKit — and it applies the same timing model and emits a TrackViewPayload (an SDK payload type) through the client for you. The controller uses the default model: an initial view event once the entry accumulates 2 seconds (dwellTimeMs) at 80% visibility (minVisibleRatio), periodic duration updates every 5 seconds (viewDurationUpdateIntervalMs) while visible, and a final duration event when visibility ends once at least one event has fired. It also pauses on backgrounding and re-evaluates on foreground, and dedupes its own sticky views, so you only own the geometry and the call site.

Follow this pattern:

1
final class OptimizedEntryView: UIView {
2
    private let client: OptimizationClient
3
    private let entry: [String: Any]
4
    private weak var scrollView: UIScrollView?
5
    private var trackingController: ViewTrackingController?
6
    private var offsetObservation: NSKeyValueObservation?
7
8
    // Call site: resolve the entry when the view is configured, then (re)build
9
    // the controller for that resolution — the same place you render the entry.
10
    func configure() {
11
        let result = client.resolveOptimizedEntry(baseline: entry)
12
        rebuildTracking(result: result)
13
        // ...render result.entry with your own view code...
14
    }
15
16
    // Rebuild the controller whenever a newly resolved variant changes the
17
    // tracking metadata, ending the previous visibility cycle first.
18
    private func rebuildTracking(result: ResolvedOptimizedEntry) {
19
        trackingController?.onDisappear()
20
        trackingController = ViewTrackingController(
21
            client: client,
22
            entry: entry,
23
            optimizationContextId: result.optimizationContextId,
24
            selectedOptimization: result.selectedOptimization
25
        )
26
        emitVisibility()
27
        // Call site: feed geometry on every scroll change so the controller can
28
        // run its timing model. Also call emitVisibility() on layout changes.
29
        offsetObservation = scrollView?.observe(\.contentOffset, options: [.new]) { [weak self] _, _ in
30
            Task { @MainActor in self?.emitVisibility() }
31
        }
32
    }
33
34
    // Reader-owned geometry: your app computes the element's position and feeds
35
    // it to the controller, which owns timing, consent checks, and duplicate
36
    // duration-event prevention for the cycle.
37
    private func emitVisibility() {
38
        guard let controller = trackingController, let scrollView else { return }
39
        let frameInScroll = convert(bounds, to: scrollView)
40
        controller.updateVisibility(
41
            elementY: frameInScroll.minY,
42
            elementHeight: bounds.height,
43
            scrollY: scrollView.contentOffset.y,
44
            viewportHeight: scrollView.bounds.height
45
        )
46
    }
47
}

ViewTrackingController is the recommended path because it applies the SDK’s visibility timing for you. If your app already computes its own visibility and duration — or needs a single one-off view event — call client.trackView(TrackViewPayload(...)) directly instead of using the controller; it is the lower-level async throws primitive the controller wraps, and you then own the timing the controller would otherwise apply.

To opt an entry out of view or tap tracking, do not install its controller or gesture recognizer. For shared tracking mechanics, see iOS SDK runtime and interaction mechanics.

Identity, profile continuity, and reset

Integration category: Common but policy-dependent

Identity policy belongs to the application. The SDK can identify a visitor, update selected optimizations and changes (the inline field and flag values the Experience API returned for the visitor) from Experience API responses, persist profile-continuity state when allowed, and reset SDK-managed profile state, but it does not decide when a user becomes known or how account data is governed.

1. Call identify(userId:traits:) after sign-in or when the app has a stable application user ID.
2. Wait for SDK state or rendered content before assuming the profile has affected visible entries.
3. Call reset() on logout, account switch, or a privacy flow that must clear SDK-managed profile, selected-optimization, change, and anonymous-ID state.
4. Preserve or clear app-owned user identifiers according to your account and privacy policy; the SDK does not clear your application storage.

Adapt this to your use case:

1
Task { @MainActor in
2
    // identify links the app-owned user ID to the current mobile profile.
3
    _ = try? await client.identify(
4
        userId: user.id,
5
        traits: ["plan": user.plan]
6
    )
7
}

Copy this:

1
// reset() clears profile continuity but preserves consent state.
2
client.reset()

reset() clears profile continuity (profile, changes, selected optimizations, the anonymous ID, the current-screen dedupe tracker, and sticky-view keys) but preserves consent state, and it no-ops before initialization. When persistence consent is allowed, the SDK writes continuity to UserDefaults and publishes SDK state from an Experience response after that write settles. In tests and relaunch flows, wait for SDK-derived UI or state instead of adding arbitrary storage delays. The SDK persists to UserDefaults under the com.contentful.optimization. prefix, not to cookies, and provides no built-in cross-platform identity handoff — implement any web, server, or account continuity in application code. For the identifier model, see Consent management in the Optimization SDK Suite.

Optional integrations

Custom events and analytics diagnostics

Integration category: Optional

Use custom events for business actions that are not tied to a Contentful entry swap, and the event streams for local diagnostics or app-owned analytics forwarding.

1. Call track(event:properties:) for a business event.
2. Subscribe to eventStream for accepted events; subscribe to blockedEventStream (or configure onEventBlocked at startup) for events stopped by consent or the allow-list.
3. Subscribe before the events you want to observe fire — eventStream is a passthrough publisher that does not replay earlier events to late subscribers.

Copy this:

1
Task { @MainActor in
2
    // A custom business event, not tied to a Contentful entry swap.
3
    _ = try? await client.track(event: "Purchase Completed", properties: ["sku": "ABC-123"])
4
}

Adapt this to your use case:

1
// eventStream is a passthrough publisher with no replay: subscribe before the
2
// events you want to observe fire, or you miss the earlier ones.
3
client.eventStream
4
    .sink { event in analyticsDebugStore.append(event) }
5
    .store(in: &cancellables)
6
7
// blockedEventStream surfaces events stopped by consent or the allow-list —
8
// the diagnostic for a missing event during integration.
9
client.blockedEventStream
10
    .sink { blocked in print("blocked \(blocked.method): \(blocked.reason)") }
11
    .store(in: &cancellables)

When forwarding SDK events to third-party destinations, apply the same app-owned consent policy, deduplication, and data-minimization rules that govern the destination. For destination mapping, consent, identity, dedupe, and governance guidance, see Forwarding Optimization SDK context to analytics and tag-management tools.

Custom Flags and MergeTag rendering

Integration category: Optional

Use Custom Flags when your Optimization data includes profile-backed feature values, and merge tags when it includes profile-driven text substitutions in Rich Text. Both read from SDK state separately from entry-variant resolution.

1. Read a flag once with getFlag(_:) when a synchronous value is enough.
2. Subscribe with flagPublisher(_:) when the UI must update as flag values change.
3. Resolve merge tags with getMergeTagValue(mergeTagEntry:) from your app-owned Rich Text renderer.

Copy this:

1
// Non-reactive one-shot read; returns nil before init or when unresolved.
2
let flagValue = client.getFlag("show-promo")

Adapt this to your use case:

1
// Subscribing registers an observeFlag subscription. A flag subscription emits
2
// a component flag-view event (an analytics exposure) when consent and profile
3
// allow, so treat it as tracked exposure, not a free read, and govern it like
4
// any other event.
5
client.flagPublisher("show-promo")
6
    .receive(on: RunLoop.main)
7
    .sink { [weak self] value in self?.applyPromoFlag(value) }
8
    .store(in: &cancellables)

nt_mergetag is the SDK-fixed Optimization content type for a merge tag — a profile-driven text substitution embedded inline in Rich Text; it is not a name you choose. Your app owns extracting the embedded nt_mergetag entry from the Rich Text node before calling the SDK, which resolves the selector against the current profile and returns the resolved string or nil.

Follow this pattern:

1
// mergeTagEntry is reader-owned: the expanded embedded-entry-inline node's
2
// data.target you extracted from Rich Text.
3
let resolved = client.getMergeTagValue(mergeTagEntry: mergeTagEntry)
4
// resolved is String?; fall back to the merge tag's configured value on nil.

For the deeper data model, see Entry optimization and variant resolution.

Live updates and locked variants

Integration category: Optional

UIKit apps choose whether optimized content updates live or locks to the first selected variant for the screen. There is no automatic locking in UIKit; you pick the policy by how you pass selectedOptimizations and whether you redraw on state changes.

1. To lock a screen, capture client.selectedOptimizations ?? [] once after the first resolution and pass that explicit snapshot to every resolveOptimizedEntry call on the screen. Do not pass nil for locked screens, because nil tells the resolver to use current SDK state.
2. To update live, pass nil (or the current client.selectedOptimizations) and subscribe to client.$selectedOptimizations to redraw affected views when selections change.
3. Treat client.isPreviewPanelOpen as a reason to redraw live: an open preview panel forces live updates so applied overrides appear immediately.

Adapt this to your use case:

1
private var lockedOptimizations: [[String: Any]] = []
2
private var hasLockedOptimizations = false
3
4
func lockVariantsForScreen() {
5
    guard !hasLockedOptimizations else { return }
6
    // Capture an explicit snapshot after the screen's first resolution.
7
    // Empty array locks to no selections; nil would ask for current SDK state.
8
    lockedOptimizations = client.selectedOptimizations ?? []
9
    hasLockedOptimizations = true
10
}
11
12
func render(entry: [String: Any]) {
13
    guard hasLockedOptimizations else { return }
14
    let result = client.resolveOptimizedEntry(
15
        baseline: entry,
16
        selectedOptimizations: lockedOptimizations
17
    )
18
    contentView.configure(with: result.entry)
19
}

Adapt this to your use case:

1
client.$selectedOptimizations
2
    // @Published fires in willSet, so hop to the next run-loop turn to read the
3
    // committed selections before re-resolving.
4
    .receive(on: RunLoop.main)
5
    .sink { [weak self] _ in
6
        guard self?.client.isPreviewPanelOpen == true || self?.liveUpdates == true else { return }
7
        self?.reloadVisibleContent()
8
    }
9
    .store(in: &cancellables)

For the precedence between live updates, locked variants, and preview-panel state, see iOS SDK runtime and interaction mechanics.

Preview panel

Integration category: Optional

PreviewPanelViewController hosts the SDK preview panel from a UIKit view controller. Gate it behind a debug or internal-build condition so production users cannot open local audience and variant overrides.

1. Create a PreviewContentfulClient (the built-in ContentfulHTTPPreviewClient fetches nt_audience and nt_experience definitions) for the space and environment holding your Optimization entries.
2. Add the floating button to a host controller with addFloatingButton(to:client:contentfulClient:), passing the same initialized OptimizationClient the rest of the app uses so overrides affect the same resolver and event state.
3. Keep the preview panel out of public production builds unless your release policy explicitly allows it for an internal audience.

Adapt this to your use case:

1
#if DEBUG
2
let previewContentfulClient = ContentfulHTTPPreviewClient(
3
    spaceId: "your-space-id",
4
    accessToken: "your-cda-token",
5
    environment: "main"
6
)
7
8
PreviewPanelViewController.addFloatingButton(
9
    to: homeViewController,
10
    // Pass the app-owned client so overrides affect the same resolver and state.
11
    client: client,
12
    contentfulClient: previewContentfulClient
13
)
14
#endif

Passing contentfulClient is what loads audience and experience definitions by name. Without it the panel can still open, but no definitions are loaded: the audience section is empty, audience and variant override controls are unavailable, and existing override summaries can fall back to raw identifiers.

Runtime locale changes

Integration category: Optional

Use this section when the app can change language or locale after SDK startup. The SDK locale and the Contentful CDA locale are separate inputs, even when they usually carry the same value.

1. Derive the next app locale from your navigation, i18n, account, or settings layer.
2. Call setLocale(_:) to update the SDK Experience and event locale. It updates the SDK locale only — it does not refetch Contentful entries or refresh profile state — and it throws before init or on an invalid locale.
3. Refetch Contentful entries with the same locale and re-resolve visible entries once the localized payload and SDK state are both ready.
4. Invalidate app-owned content caches using locale-aware cache keys.

Adapt this to your use case:

1
let nextLocale = "de-DE"
2
3
// Updates the SDK Experience/event locale only; throws on an invalid locale.
4
try client.setLocale(nextLocale)
5
6
// Reader-owned refetch in the same locale, then re-resolve and redraw.
7
entries = try await contentfulEntryService.fetchEntries(
8
    ids: entryIds,
9
    include: 10,
10
    locale: nextLocale
11
)
12
reloadVisibleContent()

For the full locale model, see Locale handling in the Optimization SDK Suite.

Advanced integrations

Offline delivery, queue observability, and app-owned caching

Integration category: Advanced or production-only

The iOS SDK monitors network reachability, queues events while offline, flushes when connectivity returns, and flushes as the app moves toward the background. No setup is required for the default offline path: NWPathMonitor drives the SDK online state and flushes on reconnect, and the app lifecycle handler flushes on willResignActive.

1. Add QueuePolicy only when production telemetry needs queue limits or lifecycle callbacks. The offline Experience queue holds up to 100 events by default (tunable via QueuePolicy.offlineMaxEvents); queues are in-memory only and do not survive process death.
2. Use queue callbacks for operational diagnostics, not for resending blocked or dropped events.
3. Keep Contentful entry caching in the application layer — the SDK does not cache CDA responses for UIKit rendering.
4. Call flush() only for deliberate release, test, or lifecycle flows; the SDK already flushes on background and reconnect.

Adapt this to your use case:

1
let config = OptimizationConfig(
2
    clientId: "your-optimization-client-id",
3
    queuePolicy: QueuePolicy(
4
        offlineMaxEvents: 500,
5
        onOfflineDrop: { event in
6
            // event is a QueueEvent with a type and a context dictionary.
7
            diagnostics.record("optimization-offline-drop", context: event.context)
8
        },
9
        onFlushFailure: { event in
10
            diagnostics.record("optimization-flush-failure", context: event.context)
11
        },
12
        onFlushRecovered: { event in
13
            diagnostics.record("optimization-flush-recovered", context: event.context)
14
        }
15
    )
16
)

Production checks

Before release, verify the UIKit integration against these checks:

• Credentials and runtime configuration — The app uses the intended Optimization client ID, Contentful environment, SDK locale, and CDA locale. Non-default API base URLs and .debug logging are absent from production builds unless explicitly approved.

• Consent behavior — Startup consent, CMP wiring, refusal, withdrawal, split event and persistence consent, and reset() behavior match the app’s legal and privacy requirements.

• Event delivery — Screen, custom, tap, view, identify, and flag-view events appear when allowed and are blocked or omitted when policy denies them.

• Content fallback behavior — Baseline entries render when selected optimizations are missing, unresolved links are returned, variants are out of range, or the visitor is not qualified.

• Duplicate tracking prevention — UIKit lifecycle hooks, reusable cells, gesture recognizers, and visibility observers do not emit duplicate screen, tap, or view events for one intended interaction or visibility cycle.

• Privacy and governance — Preview-panel access, event forwarding, profile IDs, user traits, app-owned caches, and diagnostics follow the app’s data-minimization and retention policy.

• Local validation path — Compare your integration against the iOS reference implementation. The repository’s maintainers validate UIKit behavior with an XCUITest suite driven from implementations/ios-sdk/; that runner is a maintainer command, not an app command.

  Reference excerpt:

  1
  # From implementations/ios-sdk/ in the optimization monorepo — a maintainer
  2
  # command that builds the JS bridge, starts the mock server, and runs XCUITest.
  3
  APP_SHELL=uikit ./scripts/run-e2e.sh

Troubleshooting

• Optimized entries always render the baseline — Confirm the app fetched a single-locale entry, requested enough include depth for nt_experiences and nt_variants, initialized the client, and has non-empty client.selectedOptimizations for the visitor.
• Tap or view events do not appear — Check consent, allowedEventTypes, the componentId from TrackingMetadata, UIKit gesture wiring, and whether the view reached the configured visibility threshold long enough to emit.
• Screen events appear more than once — Review viewDidAppear(_:) calls for modal, tab, and navigation-controller transitions, and prefer trackCurrentScreen with a stable routeKey over raw screen for lifecycle tracking.
• Preview panel opens but shows identifiers — Pass a PreviewContentfulClient that can fetch nt_audience and nt_experience entries from the correct space and environment.
• Identified variants disappear after relaunch — Verify persistence consent is true, wait for SDK-published profile or selected-optimization state before terminating tests, and confirm logout or withdrawal flows are not calling reset().

Reference implementations to compare against

• iOS reference implementation — Maintained SwiftUI and UIKit shells that exercise the native iOS bridge against the shared mock API: accepted-consent startup, single-locale CDA fetching, entry resolution, screen tracking, interaction tracking, Custom Flags and merge tags, live updates, offline queueing, and preview-panel overrides. Use it as the comparison and validation target for UIKit integration behavior.