From febe071cf91e5133700b415efc95a3e82cd4c6c8 Mon Sep 17 00:00:00 2001
From: Tim Beyer <tim.beyer@gmail.com>
Date: Mon, 20 Jul 2026 18:08:37 +0200
Subject: [PATCH] fix(docs): restore SDK capabilities dropped in iOS
 reconciliation

A content-loss audit of the reconciled guides against their pre-pipeline
versions found capabilities trimmed along with reader-owned scaffolding. Restore
them:

- SwiftUI: the tri-state consent gate (ConsentGate on state.consent == nil) that
  teaches consent has an undecided state, and the follow-up to emit a fresh
  Experience event after setLocale so profile-derived selections, flags, and
  MergeTags reflect the new locale.
- UIKit: the direct client.trackView(TrackViewPayload(...)) path as the
  lower-level alternative to ViewTrackingController for apps with their own
  visibility timing or a one-off view event.

All verified against Swift source. Passes pnpm guides:check and knowledge:check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...e-optimization-ios-sdk-in-a-swiftui-app.md | 22 ++++++++++++++++++-
 ...the-optimization-ios-sdk-in-a-uikit-app.md |  6 +++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/documentation/guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md b/documentation/guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md
index c1cab19a..38365c43 100644
--- a/documentation/guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md
+++ b/documentation/guides/integrating-the-optimization-ios-sdk-in-a-swiftui-app.md
@@ -298,7 +298,9 @@ choice. Apps that persist a user's own decision leave `StorageDefaults.consent`
    `client.consent(false)` after they reject.
 3. Use the split form when events are allowed but durable profile continuity must stay session-only.
 4. Read `client.state.consent` and `client.state.persistenceConsent` when consent UI must reflect SDK
-   state.
+   state. `client.state.consent` is tri-state — `true`, `false`, or `nil` when the visitor has not
+   decided yet — so gate the banner on `client.state.consent == nil` to show it only until a choice is
+   made.
 
 **Adapt this to your use case:**
 
@@ -319,6 +321,20 @@ struct ConsentBanner: View {
         }
     }
 }
+
+struct ConsentGate<Content: View>: View {
+    @EnvironmentObject private var client: OptimizationClient
+    @ViewBuilder var content: () -> Content
+
+    var body: some View {
+        // consent is nil until the visitor decides; show the banner only while undecided.
+        if client.state.consent == nil {
+            ConsentBanner()
+        } else {
+            content()
+        }
+    }
+}
 ```
 
 **Copy this:**
@@ -369,6 +385,10 @@ events use. Keep them aligned when rendered content and Experience responses mus
 4. When the app locale changes, call `client.setLocale(...)`, refetch entries with the new locale, and
    re-render. `setLocale(...)` updates only the SDK Experience/event locale; it does not refetch
    Contentful or refresh profile state, and it throws before initialization or on an invalid locale.
+5. After the locale change, emit a fresh Experience event — the `screen`, `identify`, or `page` call
+   your app already owns for the current state — when rendered output depends on SDK-derived profile
+   data, selected optimizations, flags, or MergeTags that must reflect the new locale. Without a new
+   event, those stay on the previous locale's response.
 
 **Adapt this to your use case:**
 
diff --git a/documentation/guides/integrating-the-optimization-ios-sdk-in-a-uikit-app.md b/documentation/guides/integrating-the-optimization-ios-sdk-in-a-uikit-app.md
index 197f5a58..a6cf73fa 100644
--- a/documentation/guides/integrating-the-optimization-ios-sdk-in-a-uikit-app.md
+++ b/documentation/guides/integrating-the-optimization-ios-sdk-in-a-uikit-app.md
@@ -615,6 +615,12 @@ final class OptimizedEntryView: UIView {
 }
 ```
 
+`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](../concepts/ios-sdk-runtime-and-interaction-mechanics.md#tracking-mechanics).