OSGKeyboard Privacy Policy
-
Last updated: August 19, 2026 · v2.0
+
Last updated: August 20, 2026 · v2.0
OSGKeyboard provides an iOS custom keyboard and a macOS menu-bar dictation app. iOS uses Apple's on-device speech APIs by default; macOS can use a downloaded local Qwen3-ASR model. The core local and user-configured-provider features do not require an OSGKeyboard account. On iOS, you may optionally sign in with Apple and choose managed credits instead of supplying provider credentials. This policy explains both paths.
What we collect
@@ -35,6 +35,7 @@
API credentials — stored in the iOS Keychain and shared between the main app and keyboard extension. When iCloud settings sync is enabled, keys replicate through iCloud Keychain (not iCloud KVS JSON).
Optional OSGKeyboard account and purchases — no account is required for local transcription or user-configured providers. If you choose Sign in with Apple, the account service processes the Apple identity token, a pseudonymous OSGKeyboard account identifier, optional display name, device-integrity evidence, credit balance, referral state, and StoreKit transaction identifiers needed to verify consumable credit purchases. Account session tokens stay in the main app's private Keychain; the keyboard extension receives only a short-lived, scope-limited managed-service grant. You can sign out or delete the account in the app.
App preferences — engine mode, language, and keyboard settings stored in App Group UserDefaults. Optional iCloud sync mirrors eligible preferences, usage statistics, and voice history through your private iCloud account. Clipboard-history consent and its suggestion-strip switch stay device-local and are not activated by iCloud settings sync.
+
Optional first-party product analytics — enabled by default and removable at any time in Settings. OSGKeyboard sends only fixed event names and fixed categories about app/keyboard sessions, AI feature outcomes and duration ranges, purchase-page interactions, and invitation actions, together with an app-scoped random installation identifier and safe app/OS version labels. It never includes keyboard input, audio, transcripts, cursor context, prompts, model output, contacts, file or device names, Apple identifiers, email, credentials, advertising identifiers, or free-form properties. Turning analytics off deletes queued events; turning it back on creates a new installation identifier.
Optional clipboard history — off by default. When you turn it on, the keyboard may read text from the clipboard on this device or from Universal Clipboard; iOS does not provide a reliable way to distinguish those sources. Up to 15 accepted text items are stored only in the local App Group shared by this device’s host app and keyboard extension. Turning history off stops capture, turns off the suggestion strip, and keeps existing items. Reset Settings also keeps them; only the separate confirmed “Clear clipboard history” action removes them. There is no fixed expiry. Secure fields immediately hide clipboard UI and are not captured. Conservative filters reject common OTP shapes, private-key headers, JWTs, Bearer tokens, recognizable provider-key prefixes, and common Luhn-valid 16-digit card numbers, but cannot identify every password or secret. A rejected item can still be pasted through iOS; it is simply not added to history. Clipboard history is not automatically sent to AI. If you insert an item and then actively use polish, the inserted text may be included as context sent to the provider you configured.
Personal dictionary and typing learning — personal terms may sync through your private iCloud account when enabled. Chinese candidate frequencies and English suggestion choices remain in the local App Group and can be cleared separately without deleting the personal dictionary. OSGKeyboard does not upload this learning data.
macOS local speech models — when selected, Qwen3-ASR model files are downloaded from Hugging Face and remain in the Mac app's local application-support directory until you remove them. Local inference does not send your audio to Hugging Face or OSGKeyboard.
@@ -44,7 +45,7 @@
What we do not collect
- We do not log or upload ordinary keystrokes.
- - We do not operate analytics, crash-reporting, or advertising SDKs.
+ - We do not use third-party analytics, crash-reporting, advertising SDKs, ATT, or IDFA.
- We do not sell personal data.
@@ -62,6 +63,7 @@
Settings remain on your device until you delete the app or reset settings. With iCloud sync enabled, API keys use iCloud Keychain; eligible preferences, statistics, dictionary data, and voice history may sync through your private iCloud account.
Voice history — successful transcripts may be saved in the main app’s History tab (up to 300 entries). With iCloud settings sync enabled, history may also sync across your devices.
Clipboard history — stays in this device’s App Group, is capped at 15 entries, does not sync through iCloud, and has no fixed expiry. Turning the feature off or resetting settings keeps existing items. Use the separately confirmed clear action to delete them.
+
Product analytics — queued events expire locally after 34 days and the service accepts events no older than 35 days. Account deletion and analytics opt-out delete the local queue. Analytics identifiers are not used for cross-app tracking or advertising.
Typing learning and Mac models — Chinese and English learning data stays local and can be cleared from typing settings. Downloaded Mac speech models remain until you remove the model or delete its local files.
Optional account — account profile, credit ledger, StoreKit audit records, and limited anti-abuse records are retained by the account service while the account is active. Account deletion removes the active profile and credentials; pseudonymous ledger, purchase-audit, and time-limited anti-abuse records may remain where required to prevent replay, fraud, or abuse.
@@ -71,7 +73,7 @@
OSGKeyboard 隐私政策
-
更新日期：2026 年 8 月 19 日 · v2.0
+
更新日期：2026 年 8 月 20 日 · v2.0
OSGKeyboard 包含 iOS 自定义键盘与 macOS 菜单栏听写应用。iOS 默认使用 Apple 端侧语音能力；macOS 可使用下载到本机的 Qwen3-ASR 模型。本地能力和用户自备服务商能力无需登录 OSGKeyboard 账号。iOS 用户也可以选择 Apple 登录并使用托管积分，无需自行填写服务商凭证。本政策同时说明这两条可选路径。
我们处理的数据
@@ -84,6 +86,7 @@
API 凭证 — 保存在设备 Keychain，在主 App 与键盘扩展间共享。开启 iCloud 设置同步后，经 iCloud 钥匙串同步（非 iCloud KVS JSON）。
可选 OSGKeyboard 账号与购买 — 本地转写和用户自备服务商无需账号。若你选择 Apple 登录，账号服务会处理 Apple 身份令牌、匿名化的 OSGKeyboard 账号标识、可选昵称、设备完整性证明、积分余额、邀请状态，以及核验消耗型积分包所需的 StoreKit 交易标识。账号会话令牌只保存在主 App 私有 Keychain；键盘扩展仅获得短时、限权的托管服务凭证。你可以在 App 内退出或注销账号。
应用偏好 — 引擎、语言等设置保存在 App Group。可选 iCloud 同步经私有 iCloud 账户镜像可同步的偏好、统计与语音历史。剪贴板历史采集许可与建议条开关仅属于本机，不会被 iCloud 设置同步开启。
+
可选第一方产品分析 — 默认开启，可随时在设置中关闭。OSGKeyboard 只发送固定事件名和固定分类，用于了解 App/键盘会话、AI 功能结果与耗时区间、购买页交互及邀请操作，并携带 App 范围内随机生成的安装标识和安全的 App/系统版本标识。绝不包含键盘输入、音频、转录、光标上下文、Prompt、模型输出、联系人、文件名、设备名、Apple 标识、邮箱、凭证、广告标识符或自由形式属性。关闭后会删除待发送事件；重新开启会生成新的安装标识。
可选剪贴板历史 — 默认关闭。开启后，键盘可能读取本机剪贴板或通用剪贴板中的文字；iOS 无法可靠区分两者来源。最多 15 条通过规则的文本仅保存在本机主 App 与键盘扩展共享的 App Group。关闭历史只会停止采集、关闭建议条并保留已有记录；重置设置同样不会清除，只有单独确认的「清空剪贴板历史」操作会删除。历史没有固定过期时间。进入安全输入框会立即隐藏剪贴板入口与正文，且不会采集。保守过滤会拒绝常见 OTP 形态、私钥头、JWT、Bearer Token、具有明确服务商前缀的密钥以及常见的通过 Luhn 校验的 16 位卡号，但无法识别所有密码或秘密。被拒绝的内容仍可通过 iOS 一次性粘贴，只是不进入历史。剪贴板历史不会自动发送给 AI；插入后若主动使用润色，已插入文字可能作为上下文发送给你配置的服务商。
个性词库与本地输入学习 — 个性词条可在开启后经你的私有 iCloud 账户同步。中文候选频率与英文候选选择偏好保存在本机 App Group，可在输入设置中单独清除且不影响个性词库，OSGKeyboard 不会上传这些学习数据。
macOS 本地语音模型 — 选择后，Qwen3-ASR 模型会从 Hugging Face 下载到 Mac 本地应用支持目录，直到你主动移除。本地推理不会把录音发送给 Hugging Face 或 OSGKeyboard。
@@ -93,7 +96,7 @@
我们不收集的内容
- 我们不会记录或上传你平时在键盘上的击键内容。
- - 我们不会集成分析、崩溃上报或广告 SDK。
+ - 我们不会集成第三方分析、崩溃上报或广告 SDK，也不使用 ATT 或 IDFA。
- 我们不会出售个人数据。
@@ -111,6 +114,7 @@
设置保留在设备上，直至卸载或重置。开启 iCloud 同步后，API 密钥走 iCloud 钥匙串；可同步的偏好、统计、词库与语音历史可能经私有 iCloud 账户同步。
语音历史 — 成功转写可保存在主 App「历史」页（最多 300 条）。开启 iCloud 设置同步后，历史也可能在多设备间同步。
剪贴板历史 — 仅保存在本机 App Group，上限 15 条，不经 iCloud 同步，也没有固定过期时间。关闭功能或重置设置会保留已有记录；需使用单独确认的清空操作才能删除。
+
产品分析 — 待发送事件会在本地满 34 天后过期，服务端只接受 35 天以内的事件。注销账号或关闭产品分析会删除本地队列。分析标识不会用于跨 App 跟踪或广告。
输入学习与 Mac 模型 — 中英文输入学习数据仅留本机，可在输入设置中单独清除。下载的 Mac 语音模型会保留到你移除模型或删除本地文件。
可选账号 — 账号有效期间，账号服务会保留资料、积分账本、StoreKit 审计记录及有限的反滥用记录。注销会删除有效资料与凭证；为防止交易重放、欺诈或滥用，匿名账本、购买审计及有时限的反滥用记录可能在必要范围内继续保留。
diff --git a/OSGKeyboard/Services/AnalyticsHostService.swift b/OSGKeyboard/Services/AnalyticsHostService.swift
new file mode 100644
index 0000000..993c58c
--- /dev/null
+++ b/OSGKeyboard/Services/AnalyticsHostService.swift
@@ -0,0 +1,284 @@
+// AnalyticsHostService.swift
+// OSGKeyboard · Main App
+//
+// Host-only analytics lifecycle. The shared module owns the wire contract,
+// SQLite queue and uploader; this type only connects iOS lifecycle signals.
+
+import BackgroundTasks
+import Foundation
+import Network
+import OSGKeyboardHostSupport
+import OSGKeyboardShared
+import OSLog
+import UIKit
+
+actor AnalyticsUploadSignal: AnalyticsUploadTriggering {
+ typealias Action = @Sendable () async -> Void
+
+ private var action: Action?
+ private var isScheduled = false
+ private let debounce: Duration
+
+ init(debounce: Duration = .milliseconds(250)) {
+ self.debounce = debounce
+ }
+
+ func install(_ action: @escaping Action) {
+ self.action = action
+ }
+
+ func requestUpload() {
+ guard !isScheduled, let action else { return }
+ isScheduled = true
+ Task {
+ try? await Task.sleep(for: debounce)
+ guard !Task.isCancelled else {
+ uploadFinished()
+ return
+ }
+ await action()
+ uploadFinished()
+ }
+ }
+
+ private func uploadFinished() {
+ isScheduled = false
+ }
+}
+
+final class HostAnalyticsBearerBridge: AnalyticsBearerProviding, @unchecked Sendable {
+ static let shared = HostAnalyticsBearerBridge()
+
+ private let lock = NSLock()
+ private var provider: (any AnalyticsBearerProviding)?
+
+ func install(_ provider: any AnalyticsBearerProviding) {
+ lock.lock()
+ self.provider = provider
+ lock.unlock()
+ }
+
+ func bearerToken() async throws -> String? {
+ try await currentProvider()?.bearerToken()
+ }
+
+ func refreshBearerToken(
+ afterUnauthorizedAccessToken failedToken: String?
+ ) async throws -> String? {
+ try await currentProvider()?.refreshBearerToken(
+ afterUnauthorizedAccessToken: failedToken
+ )
+ }
+
+ private func currentProvider() -> (any AnalyticsBearerProviding)? {
+ lock.lock()
+ defer { lock.unlock() }
+ return provider
+ }
+}
+
+struct AccountAnalyticsBearerProvider: AnalyticsBearerProviding {
+ let apiClient: AccountAPIClient
+
+ func bearerToken() async throws -> String? {
+ guard try await apiClient.currentSession() != nil else { return nil }
+ return try await apiClient.accessTokenForAuthorizedRequest()
+ }
+
+ func refreshBearerToken(
+ afterUnauthorizedAccessToken failedToken: String?
+ ) async throws -> String? {
+ guard let failedToken, !failedToken.isEmpty else { return nil }
+ return try await apiClient.refreshAccessToken(
+ afterUnauthorizedAccessToken: failedToken
+ )
+ }
+}
+
+struct HostAnalyticsLogger: AnalyticsLogging {
+ private let logger = Logger(
+ subsystem: Bundle.main.bundleIdentifier ?? "com.osgkeyboard.ios",
+ category: "analytics"
+ )
+
+ func log(_ entry: AnalyticsUploadLogEntry) {
+ let statusCode = entry.statusCode ?? 0
+ let errorCategory = entry.errorCategory?.rawValue ?? "none"
+ logger.info(
+ "outcome=\(entry.outcome.rawValue, privacy: .public) count=\(entry.eventCount, privacy: .public) status=\(statusCode, privacy: .public) attempt=\(entry.attempt, privacy: .public) error=\(errorCategory, privacy: .public)"
+ )
+ }
+}
+
+@MainActor
+final class AnalyticsHostService: ObservableObject {
+ static let shared = AnalyticsHostService()
+ static let backgroundTaskIdentifier = "com.osgkeyboard.ios.analytics-sync"
+
+ @Published private(set) var isEnabled = true
+
+ let client: any AnalyticsClient
+
+ private let runtime: AnalyticsRuntime
+ private let uploadSignal: AnalyticsUploadSignal
+ private let pathMonitor = NWPathMonitor()
+ private let monitorQueue = DispatchQueue(
+ label: "com.osgkeyboard.analytics.network",
+ qos: .utility
+ )
+ private var isMonitoringNetwork = false
+ private var foregroundUploadTask: Task
?
+
+ init(
+ bearerProvider: any AnalyticsBearerProviding = HostAnalyticsBearerBridge.shared,
+ network: any AnalyticsNetworking = URLSessionAnalyticsNetwork()
+ ) {
+ let signal = AnalyticsUploadSignal()
+ uploadSignal = signal
+ let runtime = AnalyticsRuntime.mainApp(
+ environment: Self.environment,
+ uploadConfiguration: AnalyticsUploadConfiguration(endpoint: Self.endpoint),
+ network: network,
+ bearerProvider: bearerProvider,
+ trigger: signal,
+ logger: HostAnalyticsLogger()
+ )
+ self.runtime = runtime
+ client = runtime.client
+
+ Task {
+ await signal.install {
+ await runtime.uploadCoordinator.uploadAvailableEvents(maximumBatches: 4)
+ }
+ }
+ }
+
+ func prepare(firstOpenAcquisitionChannel: AnalyticsAcquisitionChannel) {
+ startNetworkMonitoringIfNeeded()
+ Task {
+ await runtime.prepare(
+ firstOpenAcquisitionChannel: firstOpenAcquisitionChannel
+ )
+ let enabled = await runtime.isEnabled()
+ await MainActor.run {
+ self.isEnabled = enabled
+ }
+ client.recordSessionActivity()
+ await runtime.uploadCoordinator.uploadAvailableEvents(maximumBatches: 8)
+ }
+ }
+
+ func appDidBecomeActive() {
+ client.recordSessionActivity()
+ requestImmediateUpload(maximumBatches: 8)
+ }
+
+ func appDidEnterBackground() {
+ Self.scheduleBackgroundRefresh()
+ let identifier = UIApplication.shared.beginBackgroundTask(
+ withName: "analytics-sync"
+ )
+ guard identifier != .invalid else { return }
+ let task = Task {
+ await runtime.uploadCoordinator.uploadAvailableEvents(maximumBatches: 2)
+ await MainActor.run {
+ UIApplication.shared.endBackgroundTask(identifier)
+ }
+ }
+ foregroundUploadTask = task
+ }
+
+ func observeAuthenticatedAccount(_ accountID: UUID) async {
+ _ = await runtime.observeAccount(stableIdentifier: accountID.uuidString)
+ await runtime.uploadCoordinator.uploadAvailableEvents(maximumBatches: 8)
+ }
+
+ func handleAccountDeletion() async {
+ await runtime.handleAccountDeletion()
+ }
+
+ func setEnabled(_ enabled: Bool) {
+ Task {
+ await runtime.setEnabled(enabled)
+ let current = await runtime.isEnabled()
+ await MainActor.run {
+ self.isEnabled = current
+ }
+ if current {
+ await runtime.uploadCoordinator.uploadAvailableEvents(maximumBatches: 4)
+ }
+ }
+ }
+
+ func refreshEnabledState() {
+ Task {
+ let current = await runtime.isEnabled()
+ await MainActor.run {
+ self.isEnabled = current
+ }
+ }
+ }
+
+ func requestImmediateUpload(maximumBatches: Int = 4) {
+ foregroundUploadTask?.cancel()
+ foregroundUploadTask = Task {
+ await runtime.uploadCoordinator.uploadAvailableEvents(
+ maximumBatches: maximumBatches
+ )
+ }
+ }
+
+ static func registerBackgroundTask() {
+ BGTaskScheduler.shared.register(
+ forTaskWithIdentifier: backgroundTaskIdentifier,
+ using: nil
+ ) { task in
+ guard let refreshTask = task as? BGAppRefreshTask else {
+ task.setTaskCompleted(success: false)
+ return
+ }
+ let operation = Task {
+ await AnalyticsHostService.shared.runtime.uploadCoordinator
+ .uploadAvailableEvents(maximumBatches: 4)
+ refreshTask.setTaskCompleted(success: !Task.isCancelled)
+ scheduleBackgroundRefresh()
+ }
+ refreshTask.expirationHandler = {
+ operation.cancel()
+ }
+ }
+ }
+
+ static func scheduleBackgroundRefresh() {
+ let request = BGAppRefreshTaskRequest(identifier: backgroundTaskIdentifier)
+ request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
+ try? BGTaskScheduler.shared.submit(request)
+ }
+
+ private func startNetworkMonitoringIfNeeded() {
+ guard !isMonitoringNetwork else { return }
+ isMonitoringNetwork = true
+ pathMonitor.pathUpdateHandler = { path in
+ guard path.status == .satisfied else { return }
+ Task { @MainActor in
+ AnalyticsHostService.shared.requestImmediateUpload(maximumBatches: 8)
+ }
+ }
+ pathMonitor.start(queue: monitorQueue)
+ }
+
+ private static let endpoint = URL(
+ string: "https://account.osglab.com/v1/analytics/events"
+ )!
+
+ private static var environment: AnalyticsEnvironment {
+ let appVersion = Bundle.main.object(
+ forInfoDictionaryKey: "CFBundleShortVersionString"
+ ) as? String ?? "unknown"
+ let version = ProcessInfo.processInfo.operatingSystemVersion
+ return AnalyticsEnvironment(
+ appVersion: appVersion,
+ osVersion: "\(version.majorVersion).\(version.minorVersion).\(version.patchVersion)"
+ )
+ }
+}
diff --git a/OSGKeyboard/Services/AppURLHandler.swift b/OSGKeyboard/Services/AppURLHandler.swift
index 6add671..4c2e777 100644
--- a/OSGKeyboard/Services/AppURLHandler.swift
+++ b/OSGKeyboard/Services/AppURLHandler.swift
@@ -43,6 +43,16 @@ final class AppOpenURLRouter {
}
final class AppURLHandler: NSObject, UIApplicationDelegate {
+ func application(
+ _ application: UIApplication,
+ didFinishLaunchingWithOptions launchOptions: [
+ UIApplication.LaunchOptionsKey: Any
+ ]? = nil
+ ) -> Bool {
+ AnalyticsHostService.registerBackgroundTask()
+ return true
+ }
+
/// SwiftUI `@main` apps get no scene delegate by default. Attach ours so
/// scene-based URL delivery — the only iOS 26 path to `sourceApplication` —
/// reaches `AppSceneDelegate`. We deliberately do NOT create a window here;
diff --git a/OSGKeyboard/Services/FlowPictureInPictureController.swift b/OSGKeyboard/Services/FlowPictureInPictureController.swift
index bbac2b8..f837187 100644
--- a/OSGKeyboard/Services/FlowPictureInPictureController.swift
+++ b/OSGKeyboard/Services/FlowPictureInPictureController.swift
@@ -36,14 +36,45 @@ enum FlowPiPStartOutcome: Equatable, Sendable {
case failed(FlowPiPStartFailure)
}
+/// User-facing lifecycle published by `FlowSessionManager`.
+enum FlowPiPLifecycleState: Equatable, Sendable {
+ case inactive
+ case preparing(attempt: Int, total: Int)
+ case recovering(attempt: Int, total: Int)
+ case active
+ case waitingForForeground
+ case failed(FlowPiPStartFailure)
+}
+
@MainActor
-final class FlowPictureInPictureController: NSObject {
- /// User closed the PiP window — host should end the Flow session.
- var onUserDismissed: (() -> Void)?
+protocol FlowPictureInPictureControlling: AnyObject {
+ var onUnexpectedStop: (() -> Void)? { get set }
+ var isPictureInPictureActive: Bool { get }
+ var generation: UInt64 { get }
+
+ func attachHostView(_ view: UIView)
+ func startAndWait(
+ hostTimeout: TimeInterval,
+ activeTimeout: TimeInterval
+ ) async -> FlowPiPStartOutcome
+ func stop()
+ func resetGeneration()
+ func prepareForBackgroundAutoStart() async
+ func reassertKeepAliveAudioSession() async -> Bool
+ func updateWaveformLevels(_ levels: [Float])
+}
+
+@MainActor
+final class FlowPictureInPictureController: NSObject, FlowPictureInPictureControlling {
+ /// PiP disappeared without an in-process teardown. AVKit deliberately does
+ /// not distinguish a user close from a system stop or another app takeover.
+ var onUnexpectedStop: (() -> Void)?
private(set) var isPictureInPictureActive = false
/// True once a host UIView has been attached (may still be awaiting a window).
private(set) var hasHostView = false
+ /// Monotonic identity for the currently configured AVKit controller.
+ private(set) var generation: UInt64 = 0
let displayLayer = AVSampleBufferDisplayLayer()
@@ -115,29 +146,7 @@ final class FlowPictureInPictureController: NSObject {
@discardableResult
func start() async -> Bool {
- lastSystemStartFailure = nil
- guard AVPictureInPictureController.isPictureInPictureSupported() else {
- return false
- }
- guard hasHostView else { return false }
-
- // Required before constructing the controller; without an active
- // session, `isPictureInPicturePossible` stays false forever.
- guard await activateAudioSessionForPiP() else {
- return false
- }
-
- // If a controller was somehow created before audio activation, rebuild.
- if pipController != nil, !didActivateAudioSessionBeforeController {
- pipController = nil
- }
- configureControllerIfNeeded()
- if !usesLowPowerVideoCallPiP {
- warmLogoCacheIfNeeded()
- animationStartedAt = CACurrentMediaTime()
- startFramePump()
- }
- guard pipController != nil else { return false }
+ guard await prepareControllerForStart() else { return false }
if pipController?.isPictureInPictureActive == true {
isPictureInPictureActive = true
@@ -145,6 +154,7 @@ final class FlowPictureInPictureController: NSObject {
return true
}
+ guard pipController?.isPictureInPicturePossible == true else { return false }
if !usesLowPowerVideoCallPiP {
// Prime a few frames before asking the system to start PiP.
enqueueGuideFrame()
@@ -164,17 +174,23 @@ final class FlowPictureInPictureController: NSObject {
) async -> FlowPiPStartOutcome {
if isPictureInPictureActive { return .started }
- guard AVPictureInPictureController.isPictureInPictureSupported() else {
+ let deadline = Date().addingTimeInterval(activeTimeout)
+ let supportsPiP = await waitForPictureInPictureSupport(
+ timeout: min(max(0, deadline.timeIntervalSinceNow), 0.8)
+ )
+ guard supportsPiP else {
return .failed(.unsupported)
}
- let hostReady = await waitForHostInWindow(timeout: hostTimeout)
+ let hostReady = await waitForHostInWindow(
+ timeout: min(hostTimeout, max(0, deadline.timeIntervalSinceNow))
+ )
guard hostReady else {
return .failed(.hostNotReady)
}
lastSystemStartFailure = nil
- guard await start() else {
+ guard await prepareControllerForStart() else {
stopFramePump()
if lastSystemStartFailure != nil {
return .failed(.systemRejected)
@@ -182,17 +198,49 @@ final class FlowPictureInPictureController: NSObject {
return .failed(hasHostView ? .notPossible : .hostNotReady)
}
- let deadline = Date().addingTimeInterval(activeTimeout)
while Date() < deadline {
if isPictureInPictureActive { return .started }
if pipController?.isPictureInPictureActive == true {
isPictureInPictureActive = true
return .started
}
- if let pipController, pipController.isPictureInPicturePossible {
- pipController.startPictureInPicture()
- } else {
+ if pipController?.isPictureInPicturePossible == true {
+ break
+ }
+ try? await Task.sleep(nanoseconds: 50_000_000)
+ }
+
+ guard pipController?.isPictureInPicturePossible == true else {
+ FlowDiagnostics.log(
+ "PiP generation \(generation) never became possible"
+ )
+ return .failed(.notPossible)
+ }
+
+ if !usesLowPowerVideoCallPiP {
+ // Prime a few frames before asking the system to start PiP.
+ enqueueGuideFrame()
+ enqueueGuideFrame()
+ pipController?.invalidatePlaybackState()
+ }
+ // Issue immediately when possible. iOS 27 beta can silently ignore a
+ // request without sending either delegate callback, so retry at a
+ // conservative cadence while keeping this controller generation alive.
+ pipController?.startPictureInPicture()
+ var lastStartRequestAt = Date()
+ var startRequestCount = 1
+
+ while Date() < deadline {
+ if isPictureInPictureActive { return .started }
+ if pipController?.isPictureInPictureActive == true {
+ isPictureInPictureActive = true
+ return .started
+ }
+ if pipController?.isPictureInPicturePossible == true,
+ Date().timeIntervalSince(lastStartRequestAt) >= 0.25 {
pipController?.startPictureInPicture()
+ lastStartRequestAt = Date()
+ startRequestCount += 1
}
try? await Task.sleep(nanoseconds: 50_000_000)
}
@@ -213,16 +261,24 @@ final class FlowPictureInPictureController: NSObject {
failure = .timedOut
}
FlowDiagnostics.log(
- "PiP startAndWait failed: \(failure) possible=\(pipController?.isPictureInPicturePossible == true)"
+ "PiP startAndWait failed: \(failure) possible=\(pipController?.isPictureInPicturePossible == true) "
+ + "requests=\(startRequestCount)"
)
- stop()
return .failed(failure)
}
func stop() {
+ resetGeneration()
+ }
+
+ /// Fully releases the AVKit content source so the next attempt cannot
+ /// inherit a controller that the system has already rejected.
+ func resetGeneration() {
isStoppingProgrammatically = true
stopFramePump()
- pipController?.stopPictureInPicture()
+ let controller = pipController
+ controller?.delegate = nil
+ controller?.stopPictureInPicture()
if !usesLowPowerVideoCallPiP {
displayLayer.sampleBufferRenderer.flush(
removingDisplayedImage: true,
@@ -232,6 +288,10 @@ final class FlowPictureInPictureController: NSObject {
isPictureInPictureActive = false
animationStartedAt = nil
lastSystemStartFailure = nil
+ pipController = nil
+ videoCallContentController = nil
+ transparentContentView = nil
+ didActivateAudioSessionBeforeController = false
isStoppingProgrammatically = false
}
@@ -277,6 +337,32 @@ final class FlowPictureInPictureController: NSObject {
/// Set once we successfully activate audio before building the controller.
private var didActivateAudioSessionBeforeController = false
+ private func prepareControllerForStart() async -> Bool {
+ lastSystemStartFailure = nil
+ guard AVPictureInPictureController.isPictureInPictureSupported() else {
+ return false
+ }
+ guard hasHostView else { return false }
+
+ // Required before constructing the controller; without an active
+ // session, `isPictureInPicturePossible` stays false forever.
+ guard await activateAudioSessionForPiP() else {
+ return false
+ }
+
+ // If a controller was somehow created before audio activation, rebuild.
+ if pipController != nil, !didActivateAudioSessionBeforeController {
+ resetGeneration()
+ }
+ configureControllerIfNeeded()
+ if !usesLowPowerVideoCallPiP {
+ warmLogoCacheIfNeeded()
+ animationStartedAt = CACurrentMediaTime()
+ startFramePump()
+ }
+ return pipController != nil
+ }
+
@discardableResult
private func activateAudioSessionForPiP() async -> Bool {
// The first PiP start uses playback. After capture establishes a
@@ -289,6 +375,24 @@ final class FlowPictureInPictureController: NSObject {
return false
}
+ private func waitForPictureInPictureSupport(timeout: TimeInterval) async -> Bool {
+ if AVPictureInPictureController.isPictureInPictureSupported() {
+ return true
+ }
+#if targetEnvironment(simulator)
+ return false
+#else
+ let deadline = Date().addingTimeInterval(timeout)
+ while Date() < deadline {
+ try? await Task.sleep(nanoseconds: 200_000_000)
+ if AVPictureInPictureController.isPictureInPictureSupported() {
+ return true
+ }
+ }
+ return AVPictureInPictureController.isPictureInPictureSupported()
+#endif
+ }
+
private func waitForHostInWindow(timeout: TimeInterval) async -> Bool {
if isHostInWindowHierarchy { return true }
let deadline = Date().addingTimeInterval(timeout)
@@ -341,7 +445,9 @@ final class FlowPictureInPictureController: NSObject {
controller.canStartPictureInPictureAutomaticallyFromInline = true
controller.requiresLinearPlayback = true
pipController = controller
+ generation &+= 1
didActivateAudioSessionBeforeController = true
+ FlowDiagnostics.log("PiP controller generation \(generation) configured")
}
private func releaseAudioSessionForLowPowerPiP() {
@@ -642,6 +748,7 @@ extension FlowPictureInPictureController: @preconcurrency AVPictureInPictureCont
func pictureInPictureControllerDidStartPictureInPicture(
_ pictureInPictureController: AVPictureInPictureController
) {
+ guard pictureInPictureController === pipController else { return }
isPictureInPictureActive = true
lastSystemStartFailure = nil
releaseAudioSessionForLowPowerPiP()
@@ -650,16 +757,18 @@ extension FlowPictureInPictureController: @preconcurrency AVPictureInPictureCont
func pictureInPictureControllerDidStopPictureInPicture(
_ pictureInPictureController: AVPictureInPictureController
) {
+ guard pictureInPictureController === pipController else { return }
isPictureInPictureActive = false
stopFramePump()
guard !isStoppingProgrammatically else { return }
- onUserDismissed?()
+ onUnexpectedStop?()
}
func pictureInPictureController(
_ pictureInPictureController: AVPictureInPictureController,
failedToStartPictureInPictureWithError error: Error
) {
+ guard pictureInPictureController === pipController else { return }
// Sample-buffer fallback may need warm-up retries. VideoCall PiP uses
// the automatic-inline path plus the bounded startAndWait fallback.
lastSystemStartFailure = error
diff --git a/OSGKeyboard/Services/FlowSessionManager.swift b/OSGKeyboard/Services/FlowSessionManager.swift
index 2512c55..c708827 100644
--- a/OSGKeyboard/Services/FlowSessionManager.swift
+++ b/OSGKeyboard/Services/FlowSessionManager.swift
@@ -31,6 +31,67 @@ enum FlowUtteranceLifecyclePolicy {
}
}
+enum FlowPiPActivationTrigger: String, Sendable {
+ case coldStart
+ case foreground
+ case existingSession
+ case startupRecovery
+ case unexpectedStop
+ case healthCheck
+ case manualRetry
+}
+
+enum FlowPiPReconciliationDecision: Equatable, Sendable {
+ case noSessionIntent
+ case alreadyActive
+ case waitForForeground
+ case startRecovery
+}
+
+enum FlowPiPRecoveryPolicy {
+ static let maxAttempts = 3
+ static let totalBudget: TimeInterval = 5
+
+ static func reconciliationDecision(
+ wantsActiveSession: Bool,
+ isAppForeground: Bool,
+ isPictureInPictureActive: Bool
+ ) -> FlowPiPReconciliationDecision {
+ guard wantsActiveSession else { return .noSessionIntent }
+ if isPictureInPictureActive { return .alreadyActive }
+ return isAppForeground ? .startRecovery : .waitForForeground
+ }
+
+ static func canContinue(
+ operation: UInt64,
+ currentOperation: UInt64,
+ wantsActiveSession: Bool,
+ isAppForeground: Bool,
+ taskIsCancelled: Bool
+ ) -> Bool {
+ operation == currentOperation
+ && wantsActiveSession
+ && isAppForeground
+ && !taskIsCancelled
+ }
+
+ static func retryDelay(beforeAttempt attempt: Int) -> TimeInterval {
+ switch attempt {
+ case 1: return 0
+ case 2: return 0.25
+ default: return 0.6
+ }
+ }
+
+ static func hostTimeout(attempt: Int, remainingBudget: TimeInterval) -> TimeInterval {
+ min(attempt == 1 ? 1.5 : 0.25, max(0, remainingBudget))
+ }
+
+ static func activeTimeout(remainingBudget: TimeInterval) -> TimeInterval {
+ min(1.4, max(0, remainingBudget))
+ }
+}
+
@MainActor
final class FlowSessionManager: ObservableObject {
private struct PrefilledAIRequest {
@@ -45,12 +106,14 @@ final class FlowSessionManager: ObservableObject {
@Published private(set) var sessionExpiresAt: Date?
/// Non-nil when continuous capture failed or permissions are missing.
@Published private(set) var sessionWarning: String?
+ @Published private(set) var pipLifecycleState: FlowPiPLifecycleState = .inactive
private let capture = FlowContinuousCapture()
- private let pipController = FlowPictureInPictureController()
+ private let pipController: any FlowPictureInPictureControlling
private let store = AppGroupStore()
+ private let analyticsClient: any AnalyticsClient
/// Cloud / local polish via the user-configured LLM provider.
- private let polisher = PolishingService()
+ private let polisher: PolishingService
/// AI-mode turns are intentionally process-local and never persisted.
private let aiConversations = AIConversationStore()
/// Cached ASR instance. The only on-device backend is iOS
@@ -98,6 +161,7 @@ final class FlowSessionManager: ObservableObject {
private var pendingSourceHistoryEntryID: UUID?
private var pendingSourceHistoryEntryRevision: Int64?
private var pendingAIConversationID: UUID?
+ private var pendingManagedRequestPurpose: ManagedGatewayRequestPurpose?
private var pendingProcessingDeadlineAt: TimeInterval?
private var pendingStopUtteranceId: UUID?
private var currentCommandSeq: Int64 = 0
@@ -110,6 +174,7 @@ final class FlowSessionManager: ObservableObject {
@Published private(set) var isUtteranceProcessing = false
private var finalizeTask: Task?
private var asrTask: Task?
+ private var transcriptionAnalyticsOperation: (any AnalyticsAIOperation)?
private var utteranceSafetyTask: Task?
private var chunkedPipeline: ChunkedUtterancePipeline?
private var currentPartial = ""
@@ -131,7 +196,10 @@ final class FlowSessionManager: ObservableObject {
private var isAppForeground = false
/// True while handling a keyboard-initiated `startflow` cold start.
private var isColdStartHandoff = false
- private var coldStartRecoveryTask: Task?
+ /// User intent outlives a transient PiP loss; only explicit teardown clears it.
+ private var wantsActiveSession = false
+ /// Invalidates late async completions after retry, stop, or process teardown.
+ private var pipRecoveryOperation: UInt64 = 0
var shouldDeferHostHeavyWork: Bool {
isStarting
|| startingUtteranceId != nil
@@ -148,7 +216,13 @@ final class FlowSessionManager: ObservableObject {
/// recreate the `@StateObject`-owned manager within the same process).
private static var didRunLaunchReconciliation = false
- init() {
+ init(
+ analyticsClient: any AnalyticsClient = NoopAnalyticsClient(),
+ pipController: any FlowPictureInPictureControlling = FlowPictureInPictureController()
+ ) {
+ self.analyticsClient = analyticsClient
+ self.polisher = PolishingService(analyticsClient: analyticsClient)
+ self.pipController = pipController
// Sessions are (re)started explicitly on app foreground via
// `activateOnForeground()`. We deliberately do NOT silently reattach a
// stored session here — after a force-quit that would resurrect capture
@@ -194,10 +268,9 @@ final class FlowSessionManager: ObservableObject {
kind: .recognitionInterrupted
)
}
- pipController.onUserDismissed = { [weak self] in
- guard let self, self.isActive else { return }
- self.debug("PiP dismissed by user — ending Flow session")
- self.endSession()
+ pipController.onUnexpectedStop = { [weak self] in
+ guard let self, self.wantsActiveSession else { return }
+ self.handleUnexpectedPiPStop()
}
FlowTerminationCoordinator.register(self)
}
@@ -257,25 +330,25 @@ final class FlowSessionManager: ObservableObject {
}
if isActive {
+ wantsActiveSession = true
extendSession(duration: duration)
- refreshHostReady()
+ if pipController.isPictureInPictureActive {
+ pipLifecycleState = .active
+ refreshHostReady()
+ } else {
+ ensurePiPActive(
+ trigger: coldStart ? .coldStart : .existingSession,
+ duration: duration
+ )
+ }
return
}
- guard !isStarting else {
- traceState("startSession.ignored", extra: "reason=alreadyStarting")
- return
- }
- // Claim the flag synchronously: on a cold start the URL router and
- // `activateOnForeground()` both fire in the same runloop turn, and
- // setting it inside the async body let two start bodies interleave.
- isStarting = true
-
- startTask?.cancel()
- startTask = Task { @MainActor [weak self] in
- await self?.startSessionAsync(duration: duration)
- self?.handleColdStartAfterSessionReady()
- }
+ wantsActiveSession = true
+ ensurePiPActive(
+ trigger: coldStart ? .coldStart : .foreground,
+ duration: duration
+ )
}
/// Clears App Group Flow state left behind when the host process was killed
@@ -339,9 +412,19 @@ final class FlowSessionManager: ObservableObject {
)
}
+ /// User-requested recovery always discards the rejected AVKit generation.
+ func retryPiPRecovery() {
+ guard AppGroup.isAvailable else { return }
+ guard AppPermissions.flowRequirementsMet else {
+ sessionWarning = permissionWarningMessage()
+ FlowSessionBridge.setHostReady(false)
+ return
+ }
+ wantsActiveSession = true
+ ensurePiPActive(trigger: .manualRetry, duration: nil, forceReset: true)
+ }
+
private func completeColdStartHandoff() {
- coldStartRecoveryTask?.cancel()
- coldStartRecoveryTask = nil
isColdStartHandoff = false
if isActive {
refreshHostReady()
@@ -360,9 +443,10 @@ final class FlowSessionManager: ObservableObject {
)
}
+ wantsActiveSession = false
+ pipRecoveryOperation &+= 1
+ pipLifecycleState = .inactive
isColdStartHandoff = false
- coldStartRecoveryTask?.cancel()
- coldStartRecoveryTask = nil
startTask?.cancel()
startTask = nil
startupAudioHealthTask?.cancel()
@@ -433,7 +517,7 @@ final class FlowSessionManager: ObservableObject {
}
func endSession() {
- guard isActive else { return }
+ guard isActive || isStarting || wantsActiveSession else { return }
debug("Flow session ended")
if isUtteranceRecording || isUtteranceProcessing,
claimTerminal(utteranceId: currentUtteranceId) {
@@ -444,9 +528,10 @@ final class FlowSessionManager: ObservableObject {
)
}
+ wantsActiveSession = false
+ pipRecoveryOperation &+= 1
+ pipLifecycleState = .inactive
isColdStartHandoff = false
- coldStartRecoveryTask?.cancel()
- coldStartRecoveryTask = nil
startTask?.cancel()
startTask = nil
startupAudioHealthTask?.cancel()
@@ -493,6 +578,7 @@ final class FlowSessionManager: ObservableObject {
FlowSessionBridge.markSessionInactive()
FlowSessionDarwin.postSessionChanged()
isActive = false
+ isStarting = false
sessionExpiresAt = nil
sessionWarning = nil
currentPartial = ""
@@ -516,19 +602,27 @@ final class FlowSessionManager: ObservableObject {
case .active:
setAppForeground(true)
resumeAfterForeground()
+ if wantsActiveSession, !pipController.isPictureInPictureActive {
+ ensurePiPActive(trigger: .foreground, duration: nil)
+ }
case .inactive:
+ setAppForeground(false)
writeHeartbeatIfActive()
- if isActive {
+ if isActive, pipController.isPictureInPictureActive {
Task { @MainActor [weak self] in
await self?.pipController.prepareForBackgroundAutoStart()
}
+ } else if wantsActiveSession {
+ pausePiPRecoveryUntilForeground()
}
case .background:
setAppForeground(false)
- if isActive {
+ if isActive, pipController.isPictureInPictureActive {
Task { @MainActor [weak self] in
await self?.pipController.prepareForBackgroundAutoStart()
}
+ } else if wantsActiveSession {
+ pausePiPRecoveryUntilForeground()
}
if isColdStartHandoff {
completeColdStartHandoff()
@@ -549,6 +643,33 @@ final class FlowSessionManager: ObservableObject {
FlowSessionBridge.writeHeartbeat()
}
+ private func handleUnexpectedPiPStop() {
+ guard wantsActiveSession else { return }
+ traceState("pip.unexpectedStop")
+ pipLifecycleState = .waitingForForeground
+ sessionWarning = nil
+ if isUtteranceRecording {
+ failUtterance(
+ message: AppL10n.string("flow.error.recognitionInterrupted"),
+ kind: .recognitionInterrupted
+ )
+ }
+ FlowSessionBridge.setHostReady(false)
+ refreshHostReady()
+ // Do not immediately fight another app for the system-owned PiP slot.
+ // The scene-active path or the existing heartbeat performs reconciliation.
+ }
+
+ private func pausePiPRecoveryUntilForeground() {
+ startTask?.cancel()
+ startTask = nil
+ pipRecoveryOperation &+= 1
+ pipController.resetGeneration()
+ isStarting = false
+ pipLifecycleState = .waitingForForeground
+ refreshHostReady()
+ }
+
private func resumeAfterForeground() {
guard isActive else {
return
@@ -723,36 +844,192 @@ final class FlowSessionManager: ObservableObject {
// MARK: - Session start
- private func startSessionAsync(duration: TimeInterval?) async {
- // `isStarting` was claimed synchronously in `startSession()`.
- defer { isStarting = false }
+ private func ensurePiPActive(
+ trigger: FlowPiPActivationTrigger,
+ duration: TimeInterval?,
+ forceReset: Bool = false
+ ) {
+ switch FlowPiPRecoveryPolicy.reconciliationDecision(
+ wantsActiveSession: wantsActiveSession,
+ isAppForeground: isAppForeground,
+ isPictureInPictureActive: pipController.isPictureInPictureActive
+ ) {
+ case .noSessionIntent:
+ return
+ case .alreadyActive:
+ pipLifecycleState = .active
+ sessionWarning = nil
+ if isActive {
+ refreshHostReady()
+ } else {
+ activateFlowSessionAfterPiPProof(duration: duration)
+ }
+ handleColdStartAfterSessionReady()
+ return
+ case .waitForForeground:
+ pipLifecycleState = .waitingForForeground
+ FlowSessionBridge.setHostReady(false)
+ refreshHostReady()
+ return
+ case .startRecovery:
+ break
+ }
+
+ guard startTask == nil else {
+ traceState(
+ "pipRecovery.coalesced",
+ extra: "trigger=\(trigger.rawValue)"
+ )
+ return
+ }
+
+ // Claim the flag synchronously: on a cold start the URL router and
+ // `activateOnForeground()` both fire in the same runloop turn, and
+ // setting it inside the async body let two start bodies interleave.
+ isStarting = true
+ pipRecoveryOperation &+= 1
+ let operation = pipRecoveryOperation
+ let recoveringExistingSession = isActive
+ let resetFirstGeneration = forceReset
+ || recoveringExistingSession
+ || pipController.generation > 0
+ pipLifecycleState = recoveringExistingSession
+ ? .recovering(attempt: 1, total: FlowPiPRecoveryPolicy.maxAttempts)
+ : .preparing(attempt: 1, total: FlowPiPRecoveryPolicy.maxAttempts)
+
+ startTask = Task { @MainActor [weak self] in
+ await self?.startSessionAsync(
+ duration: duration,
+ trigger: trigger,
+ operation: operation,
+ resetFirstGeneration: resetFirstGeneration
+ )
+ }
+ }
+
+ private func startSessionAsync(
+ duration: TimeInterval?,
+ trigger: FlowPiPActivationTrigger,
+ operation: UInt64,
+ resetFirstGeneration: Bool
+ ) async {
+ // `isStarting` was claimed synchronously in `ensurePiPActive()`.
+ defer {
+ if operation == pipRecoveryOperation {
+ isStarting = false
+ startTask = nil
+ }
+ }
guard !Task.isCancelled else { return }
- traceState("startSessionAsync.begin")
+ traceState("startSessionAsync.begin", extra: "trigger=\(trigger.rawValue)")
sessionWarning = nil
guard AppPermissions.flowRequirementsMet else {
sessionWarning = permissionWarningMessage()
+ pipLifecycleState = .failed(.notPossible)
traceState("startSessionAsync.blocked", extra: "reason=permissions")
FlowSessionBridge.setHostReady(false)
isColdStartHandoff = false
return
}
- switch await pipController.startAndWait() {
- case .started:
- activateFlowSessionAfterPiPProof(duration: duration)
- traceState("startSessionAsync.ready")
- debug("Flow session started (PiP keep-alive), mic released between utterances")
- case .failed(let failure):
- let message = AppL10n.string(failure.localizationKey)
- sessionWarning = message
- traceState("startSessionAsync.failed", extra: "reason=pipUnavailable failure=\(failure)")
- FlowSessionBridge.setHostReady(false)
- if isColdStartHandoff {
- scheduleColdStartRecovery(duration: duration)
+ let deadline = Date().addingTimeInterval(FlowPiPRecoveryPolicy.totalBudget)
+ var lastFailure: FlowPiPStartFailure = .timedOut
+
+ for attempt in 1...FlowPiPRecoveryPolicy.maxAttempts {
+ guard FlowPiPRecoveryPolicy.canContinue(
+ operation: operation,
+ currentOperation: pipRecoveryOperation,
+ wantsActiveSession: wantsActiveSession,
+ isAppForeground: isAppForeground,
+ taskIsCancelled: Task.isCancelled
+ ) else {
+ if operation == pipRecoveryOperation,
+ wantsActiveSession,
+ !Task.isCancelled,
+ !isAppForeground {
+ pipLifecycleState = .waitingForForeground
+ FlowSessionBridge.setHostReady(false)
+ }
+ return
+ }
+
+ let delay = FlowPiPRecoveryPolicy.retryDelay(beforeAttempt: attempt)
+ if delay > 0 {
+ try? await Task.sleep(
+ nanoseconds: UInt64(delay * 1_000_000_000)
+ )
+ }
+ guard FlowPiPRecoveryPolicy.canContinue(
+ operation: operation,
+ currentOperation: pipRecoveryOperation,
+ wantsActiveSession: wantsActiveSession,
+ isAppForeground: isAppForeground,
+ taskIsCancelled: Task.isCancelled
+ ) else { return }
+
+ if resetFirstGeneration || attempt > 1 {
+ pipController.resetGeneration()
+ }
+
+ let remaining = deadline.timeIntervalSinceNow
+ guard remaining > 0 else { break }
+ pipLifecycleState = isActive
+ ? .recovering(attempt: attempt, total: FlowPiPRecoveryPolicy.maxAttempts)
+ : .preparing(attempt: attempt, total: FlowPiPRecoveryPolicy.maxAttempts)
+ traceState(
+ "pipRecovery.attempt",
+ extra: "trigger=\(trigger.rawValue) attempt=\(attempt) generation=\(pipController.generation)"
+ )
+
+ let outcome = await pipController.startAndWait(
+ hostTimeout: FlowPiPRecoveryPolicy.hostTimeout(
+ attempt: attempt,
+ remainingBudget: remaining
+ ),
+ activeTimeout: FlowPiPRecoveryPolicy.activeTimeout(
+ remainingBudget: deadline.timeIntervalSinceNow
+ )
+ )
+ guard FlowPiPRecoveryPolicy.canContinue(
+ operation: operation,
+ currentOperation: pipRecoveryOperation,
+ wantsActiveSession: wantsActiveSession,
+ isAppForeground: isAppForeground,
+ taskIsCancelled: Task.isCancelled
+ ) else { return }
+
+ switch outcome {
+ case .started:
+ sessionWarning = nil
+ pipLifecycleState = .active
+ if isActive {
+ refreshHostReady()
+ } else {
+ activateFlowSessionAfterPiPProof(duration: duration)
+ }
+ traceState(
+ "startSessionAsync.ready",
+ extra: "trigger=\(trigger.rawValue) attempt=\(attempt) generation=\(pipController.generation)"
+ )
+ handleColdStartAfterSessionReady()
+ debug("Flow session started (PiP keep-alive), mic released between utterances")
+ return
+ case .failed(let failure):
+ lastFailure = failure
+ traceState(
+ "startSessionAsync.failed",
+ extra: "reason=pipUnavailable trigger=\(trigger.rawValue) attempt=\(attempt) failure=\(failure)"
+ )
}
- debug("PiP keep-alive failed to start: \(failure)")
}
+
+ pipController.resetGeneration()
+ pipLifecycleState = .failed(lastFailure)
+ sessionWarning = AppL10n.string(lastFailure.localizationKey)
+ FlowSessionBridge.setHostReady(false)
+ refreshHostReady()
+ debug("PiP keep-alive failed after bounded recovery: \(lastFailure)")
}
private func activateFlowSessionAfterPiPProof(duration: TimeInterval?) {
@@ -762,6 +1039,8 @@ final class FlowSessionManager: ObservableObject {
FlowSessionBridge.markSessionActivePersistent(sessionId: sessionId)
FlowSessionDarwin.postSessionChanged()
isActive = true
+ wantsActiveSession = true
+ pipLifecycleState = .active
// Low-profile PiP is a system-owned keep-alive surface. Keeping the
// display awake wastes far more power than the static PiP itself.
ScreenWakeLock.release()
@@ -862,18 +1141,10 @@ final class FlowSessionManager: ObservableObject {
guard isColdStartHandoff, isActive else { return }
sessionWarning = nil
if !pipController.isPictureInPictureActive {
- switch await pipController.startAndWait() {
- case .started:
- break
- case .failed(let failure):
- let message = AppL10n.string(failure.localizationKey)
- sessionWarning = message
- FlowSessionBridge.setHostReady(false)
- scheduleColdStartRecovery(duration: nil)
- debug("existing PiP session failed cold-start restart: \(failure)")
- return
- }
+ ensurePiPActive(trigger: .existingSession, duration: nil)
+ return
}
+ pipLifecycleState = .active
refreshHostReady()
handleColdStartAfterSessionReady()
}
@@ -895,7 +1166,9 @@ final class FlowSessionManager: ObservableObject {
let message = AppL10n.string("flow.session.error.notPossible")
sessionWarning = message
FlowSessionBridge.setHostReady(false)
- scheduleColdStartRecovery(duration: nil)
+ if !pipController.isPictureInPictureActive {
+ scheduleColdStartRecovery(duration: nil)
+ }
debug("cold-start blocked: host ready contract not published")
return
}
@@ -927,31 +1200,14 @@ final class FlowSessionManager: ObservableObject {
/// bounce the audio session and rebuild. Force-quit relaunches routinely
/// inherit stale mediaserverd state that only a rebuild clears.
private func scheduleColdStartRecovery(duration: TimeInterval?) {
- coldStartRecoveryTask?.cancel()
- coldStartRecoveryTask = Task { @MainActor [weak self] in
- guard let self else { return }
- // The failed controller has been fully torn down. Give the app
- // scene and Pegasus service a short settling interval before the
- // one bounded cold-start retry creates a new controller generation.
- try? await Task.sleep(nanoseconds: 400_000_000)
- guard !Task.isCancelled, self.isColdStartHandoff else { return }
- let outcome = await self.pipController.startAndWait()
- self.traceState("coldStartRecovery.pip", extra: "outcome=\(outcome)")
- guard !Task.isCancelled, self.isColdStartHandoff else { return }
- switch outcome {
- case .started:
- if self.isActive {
- self.sessionWarning = nil
- self.refreshHostReady()
- self.handleColdStartAfterSessionReady()
- } else {
- self.activateFlowSessionAfterPiPProof(duration: duration)
- self.handleColdStartAfterSessionReady()
- }
- case .failed(let failure):
- self.sessionWarning = AppL10n.string(failure.localizationKey)
- }
- }
+ // The failed controller has been fully torn down. Give the app
+ // scene and Pegasus service a short settling interval before the
+ // one bounded cold-start retry creates a new controller generation.
+ ensurePiPActive(
+ trigger: .startupRecovery,
+ duration: duration,
+ forceReset: true
+ )
}
private func bindSessionASRIfNeeded(force: Bool = false) {
@@ -1245,6 +1501,7 @@ final class FlowSessionManager: ObservableObject {
)
)
currentUtteranceMode = command.resolvedUtteranceMode
+ pendingManagedRequestPurpose = command.managedRequestPurpose
pendingAIConversationID = currentUtteranceMode == .aiQuestion
? command.aiConversationID
: nil
@@ -1357,6 +1614,7 @@ final class FlowSessionManager: ObservableObject {
commandSeq: command.commandSeq
) else { return }
currentUtteranceMode = .aiQuestion
+ pendingManagedRequestPurpose = command.managedRequestPurpose
pendingAIConversationID = command.aiConversationID
pendingEditSourceText = nil
pendingSourceHistoryEntryID = nil
@@ -1435,7 +1693,9 @@ final class FlowSessionManager: ObservableObject {
store: pipelineStore,
conversations: aiConversations,
taskKind: request.taskKind,
- thinkingEnabled: request.thinkingEnabled
+ thinkingEnabled: request.thinkingEnabled,
+ analyticsClient: analyticsClient,
+ analyticsFeature: Self.analyticsFeature(for: request.taskKind)
)
aiAnswerStreamThrottle = AIAnswerStreamThrottle()
let answer = try await service.answer(
@@ -1610,6 +1870,13 @@ final class FlowSessionManager: ObservableObject {
kind: FlowSessionKeys.TranscriptionErrorKind = .generic,
status: FlowResult.Status = .error
) {
+ finishTranscriptionAnalytics(
+ success: false,
+ failureCategory: Self.transcriptionFailureCategory(
+ kind: kind,
+ status: status
+ )
+ )
guard let activeSessionId, let currentUtteranceId else { return }
FlowSessionBridge.writeResult(
FlowResult(
@@ -1901,6 +2168,11 @@ final class FlowSessionManager: ObservableObject {
)
let cloudASRForStreaming = useStreaming ? cloudService : nil
+ transcriptionAnalyticsOperation?.cancel()
+ transcriptionAnalyticsOperation = analyticsClient.startAIFeature(
+ .transcription,
+ executionMode: analyticsExecutionMode
+ )
asrTask = Task.detached(priority: .userInitiated) { [weak manager = self] in
let outcome: ChunkedUtterancePipelineOutcome
@@ -2220,6 +2492,7 @@ final class FlowSessionManager: ObservableObject {
pendingSourceHistoryEntryID = nil
pendingSourceHistoryEntryRevision = nil
pendingAIConversationID = nil
+ pendingManagedRequestPurpose = nil
pendingProcessingDeadlineAt = nil
currentUtteranceMode = .dictation
}
@@ -2237,6 +2510,7 @@ final class FlowSessionManager: ObservableObject {
let sourceHistoryEntryID = pendingSourceHistoryEntryID
let sourceHistoryEntryRevision = pendingSourceHistoryEntryRevision
let aiConversationID = pendingAIConversationID
+ let managedRequestPurpose = pendingManagedRequestPurpose
let processingDeadlineAt = pendingProcessingDeadlineAt
let asrEngineMode = sessionASREngineMode ?? store.engineMode
// ALWAYS clear the processing gate for this utterance. The previous
@@ -2250,6 +2524,7 @@ final class FlowSessionManager: ObservableObject {
pendingSourceHistoryEntryID = nil
pendingSourceHistoryEntryRevision = nil
pendingAIConversationID = nil
+ pendingManagedRequestPurpose = nil
pendingProcessingDeadlineAt = nil
if currentUtteranceMode == utteranceMode {
currentUtteranceMode = .dictation
@@ -2366,6 +2641,7 @@ final class FlowSessionManager: ObservableObject {
)
return
}
+ finishTranscriptionAnalytics(success: true)
// Re-read App Group at finalize so dictionary and translation changes
// from the keyboard extension are visible before local correction,
@@ -2427,7 +2703,9 @@ final class FlowSessionManager: ObservableObject {
let service = try AIQuestionService.configured(
store: pipelineStore,
conversations: aiConversations,
- taskKind: .aiQuestion
+ taskKind: .aiQuestion,
+ analyticsClient: analyticsClient,
+ analyticsFeature: .aiAssistant
)
aiAnswerStreamThrottle = AIAnswerStreamThrottle()
let publishUtteranceId = finalizeUtteranceId
@@ -2564,6 +2842,7 @@ final class FlowSessionManager: ObservableObject {
systemPrompt: instructionPrompt?.system,
providerIdOverride: pipelineStore.polishProviderIdOverride,
taskKind: isEditLastInput ? .editLastInput : nil,
+ requestPurpose: managedRequestPurpose,
context: isInstructionMode ? nil : polishContext,
timeoutLimit: processingDeadlineAt.map {
max(0.1, $0 - Date().timeIntervalSince1970)
@@ -2868,6 +3147,13 @@ final class FlowSessionManager: ObservableObject {
status: FlowResult.Status = .error,
aiConversationID: UUID? = nil
) {
+ finishTranscriptionAnalytics(
+ success: false,
+ failureCategory: Self.transcriptionFailureCategory(
+ kind: kind,
+ status: status
+ )
+ )
guard let sessionId, let utteranceId else { return }
FlowTrace.warn(
"host.deliveredError",
@@ -2892,6 +3178,59 @@ final class FlowSessionManager: ObservableObject {
)
}
+ private static func analyticsFeature(
+ for taskKind: ManagedGatewayTaskKind
+ ) -> AnalyticsFeature {
+ switch taskKind {
+ case .aiQuestion:
+ return .hotword
+ case .clipboardTransform, .customSkill, .agentPlanning:
+ return .agent
+ case .dictationPolish, .translation, .editLastInput:
+ return .other
+ }
+ }
+
+ private var analyticsExecutionMode: AnalyticsExecutionMode {
+ if store.engineMode == "local" {
+ return .local
+ }
+ return store.credentialSource == .managed ? .managed : .byok
+ }
+
+ private func finishTranscriptionAnalytics(
+ success: Bool,
+ failureCategory: AnalyticsFailureCategory = .unknown
+ ) {
+ guard let operation = transcriptionAnalyticsOperation else { return }
+ transcriptionAnalyticsOperation = nil
+ if success {
+ operation.succeed()
+ } else {
+ operation.fail(category: failureCategory)
+ }
+ }
+
+ private static func transcriptionFailureCategory(
+ kind: FlowSessionKeys.TranscriptionErrorKind,
+ status: FlowResult.Status
+ ) -> AnalyticsFailureCategory {
+ if status == .aborted {
+ return .cancelled
+ }
+ if status == .timeout {
+ return .timeout
+ }
+ switch kind {
+ case .noSpeech, .discardedEmpty:
+ return .validation
+ case .recognitionInterrupted:
+ return .cancelled
+ case .asrFailed, .audioUnavailable, .generic:
+ return .provider
+ }
+ }
+
private static var lastResultRevision: Int64 = 0
private static func resultRevision() -> Int64 {
@@ -3030,6 +3369,7 @@ final class FlowSessionManager: ObservableObject {
systemPrompt: String? = nil,
providerIdOverride: String?,
taskKind: ManagedGatewayTaskKind? = nil,
+ requestPurpose: ManagedGatewayRequestPurpose? = nil,
context: PolishContext?,
timeoutLimit: TimeInterval? = nil
) async throws -> PolishingService.PolishOutcome {
@@ -3042,6 +3382,7 @@ final class FlowSessionManager: ObservableObject {
systemPrompt: systemPrompt,
providerIdOverride: providerIdOverride,
taskKind: taskKind,
+ requestPurpose: requestPurpose,
context: context
)
}
@@ -3081,6 +3422,14 @@ final class FlowSessionManager: ObservableObject {
self.isUtteranceRecording || self.isUtteranceProcessing {
await self.reactivateCaptureIfNeeded()
}
+ if self.wantsActiveSession,
+ !self.pipController.isPictureInPictureActive {
+ if self.isAppForeground {
+ self.ensurePiPActive(trigger: .healthCheck, duration: nil)
+ } else {
+ self.pipLifecycleState = .waitingForForeground
+ }
+ }
FlowSessionBridge.writeHeartbeat()
self.refreshHostReady()
try? await Task.sleep(nanoseconds: 1_000_000_000)
@@ -3123,6 +3472,9 @@ final class FlowSessionManager: ObservableObject {
"event=\(event)",
"active=\(isActive)",
"starting=\(isStarting)",
+ "wantsActive=\(wantsActiveSession)",
+ "pipState=\(String(describing: pipLifecycleState))",
+ "pipGeneration=\(pipController.generation)",
"coldStart=\(isColdStartHandoff)",
"sessionId=\(sessionId)",
"utteranceId=\(utteranceId)",
diff --git a/OSGKeyboard/Views/Account/AccountCenterView.swift b/OSGKeyboard/Views/Account/AccountCenterView.swift
index 96c2e7c..b5ec61d 100644
--- a/OSGKeyboard/Views/Account/AccountCenterView.swift
+++ b/OSGKeyboard/Views/Account/AccountCenterView.swift
@@ -505,6 +505,7 @@ private struct AccountCreditsSection: View {
private struct AccountCreditPurchaseSection: View {
@Environment(\.themePalette) private var palette
@ObservedObject var manager: AccountCreditPurchaseManager
+ @State private var didRecordPurchaseView = false
let accountID: UUID
let onGranted: () -> Void
@@ -540,6 +541,11 @@ private struct AccountCreditPurchaseSection: View {
guard current != nil, current != previous else { return }
onGranted()
}
+ .onAppear {
+ guard !didRecordPurchaseView else { return }
+ didRecordPurchaseView = true
+ manager.recordPurchaseViewed()
+ }
}
private func purchaseOption(_ option: AccountCreditPurchaseOption) -> some View {
@@ -777,10 +783,17 @@ private struct AccountInvitationActivityView: UIViewControllerRepresentable {
let invitationURL: URL
func makeUIViewController(context: Context) -> UIActivityViewController {
- UIActivityViewController(
+ let controller = UIActivityViewController(
activityItems: [invitationURL],
applicationActivities: nil
)
+ controller.completionWithItemsHandler = { _, completed, _, _ in
+ guard completed else { return }
+ Task { @MainActor in
+ AnalyticsHostService.shared.client.recordReferralShared()
+ }
+ }
+ return controller
}
func updateUIViewController(
diff --git a/OSGKeyboard/Views/Account/AccountCreditPurchaseManager.swift b/OSGKeyboard/Views/Account/AccountCreditPurchaseManager.swift
index 7288e30..1d878c9 100644
--- a/OSGKeyboard/Views/Account/AccountCreditPurchaseManager.swift
+++ b/OSGKeyboard/Views/Account/AccountCreditPurchaseManager.swift
@@ -7,6 +7,7 @@
import Combine
import Foundation
import OSGKeyboardHostSupport
+import OSGKeyboardShared
struct AccountCreditPurchaseOption: Identifiable, Equatable {
var id: String { productID }
@@ -43,6 +44,7 @@ final class AccountCreditPurchaseManager: ObservableObject {
private let service: any AccountCenterServicing
private let store: any AccountCreditStore
+ private let analyticsClient: any AnalyticsClient
private var updatesTask: Task?
private var activeAccountID: UUID?
private var configuredProductIDs: Set = []
@@ -50,10 +52,12 @@ final class AccountCreditPurchaseManager: ObservableObject {
init(
service: any AccountCenterServicing,
- store: any AccountCreditStore = LiveAccountCreditStore()
+ store: any AccountCreditStore = LiveAccountCreditStore(),
+ analyticsClient: any AnalyticsClient = NoopAnalyticsClient()
) {
self.service = service
self.store = store
+ self.analyticsClient = analyticsClient
}
deinit {
@@ -100,6 +104,7 @@ final class AccountCreditPurchaseManager: ObservableObject {
return false
}
state = .purchasing(productID: productID)
+ analyticsClient.recordPurchaseStarted()
do {
switch try await store.purchase(productID: productID, accountID: accountID) {
case .success(let verification):
@@ -109,6 +114,7 @@ final class AccountCreditPurchaseManager: ObservableObject {
state = .pending
case .userCancelled:
state = .idle
+ analyticsClient.recordPurchaseCancelled()
@unknown default:
state = .failed(messageKey: "account.storekit.error.unknown")
}
@@ -118,6 +124,10 @@ final class AccountCreditPurchaseManager: ObservableObject {
return false
}
+ func recordPurchaseViewed() {
+ analyticsClient.recordPurchaseViewed()
+ }
+
func clearTransientState() {
switch state {
case .succeeded, .failed, .pending:
diff --git a/OSGKeyboard/Views/Account/AccountSessionCoordinator.swift b/OSGKeyboard/Views/Account/AccountSessionCoordinator.swift
index efb4122..748e696 100644
--- a/OSGKeyboard/Views/Account/AccountSessionCoordinator.swift
+++ b/OSGKeyboard/Views/Account/AccountSessionCoordinator.swift
@@ -6,6 +6,7 @@
import Combine
import Foundation
+import OSGKeyboardShared
@MainActor
final class AccountSessionCoordinator: ObservableObject {
@@ -46,6 +47,9 @@ final class AccountSessionCoordinator: ObservableObject {
private let sessionService: any AccountSessionServicing
private let centerService: any AccountCenterServicing
private let pendingReferralStore: any PendingReferralCodeStoring
+ private let analyticsClient: any AnalyticsClient
+ private let onAccountAuthenticated: (UUID) async -> Void
+ private let onAccountDeleted: () async -> Void
private let accountRefreshInterval: TimeInterval
private let now: () -> Date
private var didAttemptRestore = false
@@ -57,15 +61,22 @@ final class AccountSessionCoordinator: ObservableObject {
pendingReferralStore: any PendingReferralCodeStoring =
UserDefaultsPendingReferralCodeStore(),
accountRefreshInterval: TimeInterval = 10 * 60,
- now: @escaping () -> Date = Date.init
+ now: @escaping () -> Date = Date.init,
+ analyticsClient: any AnalyticsClient = NoopAnalyticsClient(),
+ onAccountAuthenticated: @escaping (UUID) async -> Void = { _ in },
+ onAccountDeleted: @escaping () async -> Void = {}
) {
sessionService = dependencies.sessionService
centerService = dependencies.centerService
creditPurchases = AccountCreditPurchaseManager(
service: dependencies.centerService,
- store: creditStore
+ store: creditStore,
+ analyticsClient: analyticsClient
)
self.pendingReferralStore = pendingReferralStore
+ self.analyticsClient = analyticsClient
+ self.onAccountAuthenticated = onAccountAuthenticated
+ self.onAccountDeleted = onAccountDeleted
self.accountRefreshInterval = accountRefreshInterval
self.now = now
pendingReferralCode = pendingReferralStore.code
@@ -94,6 +105,7 @@ final class AccountSessionCoordinator: ObservableObject {
sessionPhase = .signedOut
return
}
+ await onAccountAuthenticated(session.accountID)
sessionPhase = .signedIn(session)
await redeemPendingReferralIfNeeded()
await refreshAccountData(force: true)
@@ -114,6 +126,7 @@ final class AccountSessionCoordinator: ObservableObject {
pendingReferralCode = code
shouldPresentAccountCenter = true
operationErrorKey = nil
+ analyticsClient.recordInviteOpened()
if isSignedIn {
Task {
@@ -138,6 +151,7 @@ final class AccountSessionCoordinator: ObservableObject {
do {
let session = try await sessionService.signIn(with: payload)
+ await onAccountAuthenticated(session.accountID)
sessionPhase = .signedIn(session)
await redeemPendingReferralIfNeeded()
await refreshAccountData(force: true)
@@ -260,6 +274,7 @@ final class AccountSessionCoordinator: ObservableObject {
do {
try await sessionService.deleteAccount(with: payload)
+ await onAccountDeleted()
creditPurchases.reset()
clearAccountRefreshState()
sessionPhase = .signedOut
diff --git a/OSGKeyboard/Views/Account/LiveAccountServices.swift b/OSGKeyboard/Views/Account/LiveAccountServices.swift
index 588b67f..91fe84b 100644
--- a/OSGKeyboard/Views/Account/LiveAccountServices.swift
+++ b/OSGKeyboard/Views/Account/LiveAccountServices.swift
@@ -22,6 +22,9 @@ enum LiveAccountDependencyFactory {
let sessionVault = HostPrivateAccountKeychain(descriptor: descriptor)
let apiClient = AccountAPIClient(sessionVault: sessionVault)
+ HostAnalyticsBearerBridge.shared.install(
+ AccountAnalyticsBearerProvider(apiClient: apiClient)
+ )
let integrity = DeviceIntegrityCoordinator(
apiClient: apiClient,
keyStateStore: sessionVault
diff --git a/OSGKeyboard/Views/HomeView.swift b/OSGKeyboard/Views/HomeView.swift
index e80fb29..1b69bdd 100644
--- a/OSGKeyboard/Views/HomeView.swift
+++ b/OSGKeyboard/Views/HomeView.swift
@@ -14,6 +14,68 @@ private enum HomeRoute: Hashable {
case dictionary
}
+enum FlowHomePiPStatusDescriptor: Equatable {
+ case text(localizationKey: String)
+ case progress(localizationKey: String, attempt: Int, total: Int)
+}
+
+enum FlowHomePiPStatusPolicy {
+ static func descriptor(
+ lifecycle: FlowPiPLifecycleState,
+ isStarting: Bool,
+ isRecording: Bool,
+ isProcessing: Bool,
+ isActive: Bool,
+ isHostReady: Bool
+ ) -> FlowHomePiPStatusDescriptor {
+ switch lifecycle {
+ case .preparing(let attempt, let total):
+ return .progress(
+ localizationKey: "home.flow.preparingProgress",
+ attempt: attempt,
+ total: total
+ )
+ case .recovering(let attempt, let total):
+ return .progress(
+ localizationKey: "home.flow.recoveringProgress",
+ attempt: attempt,
+ total: total
+ )
+ case .waitingForForeground:
+ return .text(localizationKey: "home.flow.waitingForForeground")
+ case .failed:
+ return .text(localizationKey: "home.flow.recoveryFailed")
+ case .inactive, .active:
+ break
+ }
+ if isStarting {
+ return .text(localizationKey: "home.flow.starting")
+ }
+ if isRecording {
+ return .text(localizationKey: "home.flow.recording")
+ }
+ if isProcessing {
+ return .text(localizationKey: "home.flow.processing")
+ }
+ if isActive, isHostReady {
+ return .text(localizationKey: "home.flow.label")
+ }
+ if isActive {
+ // Session flag is up but the ready contract is not — do not lie.
+ return .text(localizationKey: "home.flow.notReady")
+ }
+ return .text(localizationKey: "home.flow.inactive")
+ }
+
+ static func canRetry(
+ lifecycle: FlowPiPLifecycleState,
+ needsPermissionSetup: Bool
+ ) -> Bool {
+ guard case .failed = lifecycle else { return false }
+ return !needsPermissionSetup
+ }
+}
+
struct HomeView: View {
@Environment(\.themePalette) private var palette: ThemePalette
@Environment(\.scenePhase) private var scenePhase
@@ -55,6 +117,23 @@ struct HomeView: View {
!sessionIsLive && !needsPermissionSetup
}
+ private var canRetryPiP: Bool {
+ FlowHomePiPStatusPolicy.canRetry(
+ lifecycle: flowManager.pipLifecycleState,
+ needsPermissionSetup: needsPermissionSetup
+ )
+ }
+
+ private var canEndFlowSession: Bool {
+ if flowManager.isActive || flowManager.isStarting { return true }
+ switch flowManager.pipLifecycleState {
+ case .waitingForForeground, .failed:
+ return true
+ case .inactive, .preparing, .recovering, .active:
+ return false
+ }
+ }
+
private var shouldShowKeyboardHint: Bool {
!keyboardHintDismissed
&& !KeyboardSetupBridge.isReadyForOnboardingSkip
@@ -125,11 +204,11 @@ struct HomeView: View {
.padding(.top, logoTopPadding)
.padding(.bottom, logoBottomPadding)
- if showsFlowSessionExtras {
- flowSessionExtras
- .padding(.horizontal, Spacing.lg)
- .padding(.bottom, extrasBottomPadding)
- }
+ // Engine + Flow status now stays directly below the
+ // logo so startup and recovery are always visible.
+ scrollStatusFooter
+ .padding(.horizontal, Spacing.lg)
+ .padding(.bottom, extrasBottomPadding)
HomeUsageStatsSection(layout: .stacked, compact: isCompact)
.padding(.horizontal, Spacing.lg)
@@ -138,11 +217,6 @@ struct HomeView: View {
homeLibrarySection
.padding(.horizontal, Spacing.lg)
.padding(.bottom, Spacing.xl)
-
- // Scrolls with the page (not pinned); clearance comes from
- // `tabBarScrollBottomPadding` so the dock never covers it.
- scrollStatusFooter
- .padding(.horizontal, Spacing.lg)
}
.frame(maxWidth: .infinity)
.tabBarScrollBottomPadding()
@@ -152,14 +226,14 @@ struct HomeView: View {
}
}
- /// Engine + Flow status — last content in the scroll stack.
+ /// Engine + Flow status — visible near the logo instead of at scroll bottom.
private var scrollStatusFooter: some View {
- VStack(spacing: Spacing.xs) {
+ setupGuidanceCard {
engineStatusLine
flowStatusFooter
+ Divider()
+ flowSessionExtras
}
- .frame(maxWidth: .infinity, alignment: .center)
- .multilineTextAlignment(.center)
}
// MARK: - Wide layout (iPad / regular width)
@@ -169,16 +243,11 @@ struct HomeView: View {
VStack(alignment: .leading, spacing: Spacing.lg) {
wideHeroHeader
- if showsFlowSessionExtras {
- flowSessionExtras
- }
+ scrollStatusFooter
HomeUsageStatsSection(layout: .split)
homeLibrarySection
-
- scrollStatusFooter
- .frame(maxWidth: .infinity)
}
.padding(.horizontal, WideLayoutMetrics.pageHorizontalInset)
.padding(.top, Spacing.sm)
@@ -466,7 +535,26 @@ struct HomeView: View {
if needsAPIKeySetup {
// 无按钮：引导卡片已提示去设置填 API Key。
EmptyView()
- } else if flowManager.isActive {
+ } else if canRetryPiP {
+ Button {
+ flowManager.retryPiPRecovery()
+ } label: {
+ Text("home.flow.retry")
+ .font(TypeStyle.caption2)
+ .foregroundStyle(palette.accent)
+ }
+ .buttonStyle(.plain)
+ .padding(.leading, Spacing.xs)
+ Button {
+ flowManager.endSession()
+ } label: {
+ Text("home.flow.endShort")
+ .font(TypeStyle.caption2)
+ .foregroundStyle(palette.textSecondary)
+ }
+ .buttonStyle(.plain)
+ .padding(.leading, Spacing.xs)
+ } else if canEndFlowSession {
Button {
flowManager.endSession()
} label: {
@@ -477,8 +565,8 @@ struct HomeView: View {
.buttonStyle(.plain)
.padding(.leading, Spacing.xs)
} else if canManuallyStartSession {
- // Sessions no longer auto-start on foreground (keyboard survival).
- // After a manual stop / expiry, Start is the explicit re-entry.
+ // Foreground activation is automatic. After an explicit stop
+ // while staying on this screen, Start is the explicit re-entry.
Button {
flowManager.activateOnForeground(
reason: "HomeView.startButton",
@@ -498,18 +586,10 @@ struct HomeView: View {
// MARK: - Flow extras (warnings / hints)
- private var showsFlowSessionExtras: Bool {
- needsPermissionSetup
- || flowManager.sessionWarning != nil
- || needsAPIKeySetup
- || shouldShowKeyboardHint
- || !flowManager.isActive
- }
-
@ViewBuilder
private var flowSessionExtras: some View {
if needsPermissionSetup {
- setupGuidanceCard {
+ VStack(alignment: .leading, spacing: Spacing.sm) {
Text(AppPermissions.homePermissionGuidanceMessage)
.font(TypeStyle.caption2)
.foregroundStyle(palette.warning)
@@ -526,14 +606,14 @@ struct HomeView: View {
.buttonStyle(.plain)
}
} else if let warning = flowManager.sessionWarning {
- setupGuidanceCard {
+ VStack(alignment: .leading, spacing: Spacing.sm) {
Text(warning)
.font(TypeStyle.caption2)
.foregroundStyle(palette.warning)
.fixedSize(horizontal: false, vertical: true)
}
} else if needsAPIKeySetup {
- setupGuidanceCard {
+ VStack(alignment: .leading, spacing: Spacing.sm) {
Text(config.isLocalEngine
? "home.setup.polishKeyMissing"
: "home.setup.cloudIncomplete")
@@ -542,7 +622,7 @@ struct HomeView: View {
.fixedSize(horizontal: false, vertical: true)
}
} else if shouldShowKeyboardHint {
- setupGuidanceCard {
+ VStack(alignment: .leading, spacing: Spacing.sm) {
Text("home.setup.keyboardHint")
.font(TypeStyle.caption2)
.foregroundStyle(palette.textSecondary)
@@ -584,6 +664,8 @@ struct HomeView: View {
if needsAPIKeySetup { return palette.warning }
if flowManager.isUtteranceRecording { return palette.accent }
if flowManager.isUtteranceProcessing { return palette.accent }
+ if case .failed = flowManager.pipLifecycleState { return palette.warning }
+ if case .waitingForForeground = flowManager.pipLifecycleState { return palette.warning }
if flowManager.isActive, FlowSessionBridge.isHostReady() { return palette.accent }
if flowManager.isStarting { return palette.accent }
if needsPermissionSetup { return palette.warning }
@@ -598,23 +680,20 @@ struct HomeView: View {
/// with the OS), so the previous downloading / warming / failed
/// states collapse into the cloud-engine branch.
private var flowCapsuleStatusMessage: String {
- if flowManager.isStarting {
- return AppL10n.string("home.flow.starting")
+ let descriptor = FlowHomePiPStatusPolicy.descriptor(
+ lifecycle: flowManager.pipLifecycleState,
+ isStarting: flowManager.isStarting,
+ isRecording: flowManager.isUtteranceRecording,
+ isProcessing: flowManager.isUtteranceProcessing,
+ isActive: flowManager.isActive,
+ isHostReady: FlowSessionBridge.isHostReady()
+ )
+ switch descriptor {
+ case .text(let localizationKey):
+ return AppL10n.string(localizationKey)
+ case .progress(let localizationKey, let attempt, let total):
+ return AppL10n.format(localizationKey, attempt, total)
}
- if flowManager.isUtteranceRecording {
- return AppL10n.string("home.flow.recording")
- }
- if flowManager.isUtteranceProcessing {
- return AppL10n.string("home.flow.processing")
- }
- if flowManager.isActive, FlowSessionBridge.isHostReady() {
- return AppL10n.string("home.flow.label")
- }
- if flowManager.isActive {
- // Session flag is up but the ready contract is not — do not lie.
- return AppL10n.string("home.flow.notReady")
- }
- return AppL10n.string("home.flow.inactive")
}
private var engineStatusLine: some View {
diff --git a/OSGKeyboard/Views/MainAppRoot.swift b/OSGKeyboard/Views/MainAppRoot.swift
index 45d2a00..e87984d 100644
--- a/OSGKeyboard/Views/MainAppRoot.swift
+++ b/OSGKeyboard/Views/MainAppRoot.swift
@@ -16,15 +16,30 @@ struct MainAppRoot: View {
// `@ObservedObject` keeps subscriptions correct across Settings replay.
@ObservedObject private var config = ProviderConfig.shared
@ObservedObject private var releaseNotes = ReleaseNotesController.shared
- @StateObject private var flowManager = FlowSessionManager()
+ @ObservedObject private var analytics = AnalyticsHostService.shared
+ @StateObject private var flowManager: FlowSessionManager
@StateObject private var accountSession: AccountSessionCoordinator
@State private var clmWarmupTask: Task?
@State private var rimeStartupTask: Task?
+ @State private var firstOpenAcquisitionChannel: AnalyticsAcquisitionChannel = .unknown
init(accountDependencies: AccountDependencies? = nil) {
let resolvedDependencies = accountDependencies ?? LiveAccountDependencyFactory.make()
+ let analytics = AnalyticsHostService.shared
+ _flowManager = StateObject(
+ wrappedValue: FlowSessionManager(analyticsClient: analytics.client)
+ )
_accountSession = StateObject(
- wrappedValue: AccountSessionCoordinator(dependencies: resolvedDependencies)
+ wrappedValue: AccountSessionCoordinator(
+ dependencies: resolvedDependencies,
+ analyticsClient: analytics.client,
+ onAccountAuthenticated: { accountID in
+ await analytics.observeAuthenticatedAccount(accountID)
+ },
+ onAccountDeleted: {
+ await analytics.handleAccountDeletion()
+ }
+ )
)
}
@@ -35,6 +50,7 @@ struct MainAppRoot: View {
.environment(\.locale, config.uiLanguage.swiftUILocale)
.environmentObject(flowManager)
.environmentObject(accountSession)
+ .environmentObject(analytics)
.background {
FlowPiPHostView { view in
flowManager.attachPiPHostView(view)
@@ -65,6 +81,9 @@ struct MainAppRoot: View {
AppOpenURLRouter.shared.register { url in
handleIncomingURL(url)
}
+ analytics.prepare(
+ firstOpenAcquisitionChannel: firstOpenAcquisitionChannel
+ )
OSGDiag.log(
"MainAppRoot.onAppear scene=\(String(describing: scenePhase)) "
+ "onboarding=\(config.hasCompletedOnboarding) \(OSGDiag.memoryTag())",
@@ -131,6 +150,11 @@ struct MainAppRoot: View {
}
.onChange(of: scenePhase) { _, phase in
flowManager.handleScenePhase(phase)
+ if phase == .active {
+ analytics.appDidBecomeActive()
+ } else if phase == .background {
+ analytics.appDidEnterBackground()
+ }
guard phase == .active else {
clmWarmupTask?.cancel()
clmWarmupTask = nil
@@ -200,7 +224,7 @@ struct MainAppRoot: View {
MainTabView()
.id("main")
} else {
- OnboardingView(config: config)
+ OnboardingExperienceView(config: config)
.id("onboarding")
}
}
@@ -246,6 +270,7 @@ struct MainAppRoot: View {
private func handleIncomingURL(_ url: URL) {
if accountSession.handleIncomingURL(url) {
+ firstOpenAcquisitionChannel = .referral
NotificationCenter.default.post(name: .osgOpenAccountDeepLink, object: nil)
return
}
diff --git a/OSGKeyboard/Views/OnboardingExperienceView.swift b/OSGKeyboard/Views/OnboardingExperienceView.swift
new file mode 100644
index 0000000..29db1b7
--- /dev/null
+++ b/OSGKeyboard/Views/OnboardingExperienceView.swift
@@ -0,0 +1,1063 @@
+// OnboardingExperienceView.swift
+// OSGKeyboard · Main App
+//
+// A short, outcome-led first run:
+// 1) Explain the product and its data boundaries.
+// 2) Request the two permissions needed by Flow.
+// 3) Guide keyboard installation with a visual system-settings preview.
+// 4) Teach on the real keyboard inside a real host text field.
+// 5) Celebrate the first verified voice insertion.
+
+import OSGKeyboardShared
+import SwiftUI
+import UIKit
+
+private enum OnboardingExperienceStep: Int, CaseIterable {
+ case introduction
+ case permissions
+ case keyboard
+ case practice
+ case complete
+}
+
+struct OnboardingExperienceView: View {
+ @Environment(\.scenePhase) private var scenePhase
+ @Environment(\.themePalette) private var palette
+ @EnvironmentObject private var flowManager: FlowSessionManager
+ @EnvironmentObject private var accountSession: AccountSessionCoordinator
+
+ @ObservedObject var config: ProviderConfig
+ @ObservedObject private var deployment = RimeDeploymentController.shared
+
+ @State private var micStatus = AppPermissions.micStatus
+ @State private var speechStatus = AppPermissions.speechStatus
+ @State private var keyboardAppeared = KeyboardSetupBridge.hasAppeared
+ @State private var keyboardReady = KeyboardSetupBridge.isReadyForOnboardingSkip
+ @State private var hasOpenedKeyboardSettings = false
+ @State private var isRequestingPermissions = false
+ @State private var practiceText = ""
+ @State private var practiceStartedAt: Date?
+ @State private var didVerifyVoiceInsertion = false
+ @State private var isPreparingManagedPractice = false
+ @State private var managedPracticeReady = false
+ @State private var managedPracticeFailed = false
+ @FocusState private var practiceFieldFocused: Bool
+
+ private static let migrationKey = "onboarding.experience.v2.migrated"
+
+ private var currentStep: OnboardingExperienceStep {
+ OnboardingExperienceStep(rawValue: config.onboardingPage) ?? .introduction
+ }
+
+ var body: some View {
+ ZStack {
+ palette.background.ignoresSafeArea()
+ ambientBackground
+
+ VStack(spacing: 0) {
+ page
+ .frame(maxWidth: .infinity, maxHeight: .infinity)
+ .id(currentStep)
+ .transition(.opacity.combined(with: .move(edge: .trailing)))
+
+ if currentStep != .practice {
+ bottomAction
+ .padding(.horizontal, Spacing.lg)
+ .padding(.bottom, Spacing.lg)
+ }
+ }
+ }
+ .onAppear {
+ migrateLegacyProgressIfNeeded()
+ applyPrivacySafeDefaultsIfNeeded()
+ refreshState()
+ if currentStep == .practice {
+ beginPractice()
+ }
+ }
+ .onDisappear {
+ endPractice()
+ }
+ .onChange(of: scenePhase) { _, phase in
+ guard phase == .active else { return }
+ refreshState()
+ if currentStep == .practice {
+ beginPracticeIfNeeded()
+ }
+ }
+ .onChange(of: currentStep) { previous, current in
+ if previous == .practice {
+ endPractice()
+ }
+ if current == .practice {
+ beginPractice()
+ }
+ }
+ .onChange(of: accountSession.isSignedIn) { _, isSignedIn in
+ guard isSignedIn, currentStep == .practice,
+ config.hasAcknowledgedCloudSharing else { return }
+ prepareManagedPractice()
+ }
+ .onChange(of: config.hasAcknowledgedCloudSharing) { _, acknowledged in
+ guard acknowledged, currentStep == .practice,
+ accountSession.isSignedIn else { return }
+ prepareManagedPractice()
+ }
+ .task(id: currentStep) {
+ guard currentStep == .practice else { return }
+ await monitorPractice()
+ }
+ }
+
+ @ViewBuilder
+ private var page: some View {
+ switch currentStep {
+ case .introduction:
+ introductionPage
+ case .permissions:
+ permissionsPage
+ case .keyboard:
+ keyboardPage
+ case .practice:
+ practicePage
+ case .complete:
+ completePage
+ }
+ }
+
+ private var ambientBackground: some View {
+ GeometryReader { geometry in
+ LinearGradient(
+ colors: [
+ palette.accent.opacity(0.10),
+ palette.accent.opacity(0.025),
+ palette.background.opacity(0)
+ ],
+ startPoint: .top,
+ endPoint: .bottom
+ )
+ .frame(height: geometry.size.height * 0.46)
+ .allowsHitTesting(false)
+ }
+ .ignoresSafeArea(edges: .top)
+ }
+
+ // MARK: - Introduction
+
+ private var introductionPage: some View {
+ ScrollView {
+ VStack(alignment: .leading, spacing: 0) {
+ Spacer(minLength: Spacing.xxl)
+
+ Image("osglogo")
+ .resizable()
+ .scaledToFit()
+ .frame(maxWidth: 174, maxHeight: 50)
+ .accessibilityHidden(true)
+
+ Text("onboarding.experience.intro.eyebrow")
+ .font(TypeStyle.caption)
+ .tracking(1.2)
+ .foregroundStyle(palette.accent)
+ .padding(.horizontal, Spacing.sm)
+ .frame(height: 28)
+ .background(palette.accentMuted, in: Capsule())
+ .padding(.top, Spacing.hero)
+
+ Text("onboarding.experience.intro.title")
+ .font(TypeStyle.largeTitle)
+ .foregroundStyle(palette.textPrimary)
+ .padding(.top, Spacing.md)
+
+ Text("onboarding.experience.intro.subtitle")
+ .font(TypeStyle.body)
+ .foregroundStyle(palette.textSecondary)
+ .fixedSize(horizontal: false, vertical: true)
+ .padding(.top, Spacing.sm)
+
+ VStack(spacing: Spacing.sm) {
+ promiseRow(
+ icon: "waveform",
+ title: "onboarding.experience.privacy.local.title",
+ detail: "onboarding.experience.privacy.local.body"
+ )
+ promiseRow(
+ icon: "network",
+ title: "onboarding.experience.privacy.cloud.title",
+ detail: "onboarding.experience.privacy.cloud.body"
+ )
+ promiseRow(
+ icon: "keyboard",
+ title: "onboarding.experience.privacy.anywhere.title",
+ detail: "onboarding.experience.privacy.anywhere.body"
+ )
+ }
+ .padding(.top, Spacing.xxl)
+
+ if let privacyURL = LegalLinks.privacyPolicyURL {
+ Link(destination: privacyURL) {
+ Text("legal.privacyPolicy")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ .underline()
+ }
+ .padding(.top, Spacing.lg)
+ }
+ }
+ .padding(.horizontal, Spacing.xl)
+ .padding(.bottom, Spacing.xl)
+ .frame(maxWidth: 560, alignment: .leading)
+ .frame(maxWidth: .infinity)
+ }
+ }
+
+ private func promiseRow(
+ icon: String,
+ title: LocalizedStringKey,
+ detail: LocalizedStringKey
+ ) -> some View {
+ HStack(alignment: .top, spacing: Spacing.md) {
+ Image(systemName: icon)
+ .font(.system(size: 19, weight: .semibold))
+ .foregroundStyle(palette.accent)
+ .frame(width: 42, height: 42)
+ .background(palette.accentMuted, in: RoundedRectangle(cornerRadius: Radius.medium))
+
+ VStack(alignment: .leading, spacing: 3) {
+ Text(title)
+ .font(TypeStyle.bodyEmph)
+ .foregroundStyle(palette.textPrimary)
+ Text(detail)
+ .font(TypeStyle.footnote)
+ .foregroundStyle(palette.textSecondary)
+ .fixedSize(horizontal: false, vertical: true)
+ }
+
+ Spacer(minLength: 0)
+ }
+ .padding(Spacing.md)
+ .background(palette.surface, in: RoundedRectangle(cornerRadius: Radius.large, style: .continuous))
+ .overlay(
+ RoundedRectangle(cornerRadius: Radius.large, style: .continuous)
+ .stroke(palette.divider, lineWidth: 0.5)
+ )
+ }
+
+ // MARK: - Permissions
+
+ private var permissionsPage: some View {
+ OnboardingExperienceShell(
+ title: "onboarding.experience.permissions.title",
+ subtitle: "onboarding.experience.permissions.subtitle",
+ onBack: goBack
+ ) {
+ VStack(spacing: Spacing.sm) {
+ permissionRow(
+ icon: "mic.fill",
+ title: "onboarding.permission.mic.title",
+ detail: "onboarding.permission.mic.body",
+ granted: micStatus == .granted,
+ denied: micStatus == .denied
+ )
+ permissionRow(
+ icon: "waveform.badge.mic",
+ title: "onboarding.permission.speech.title",
+ detail: "onboarding.permission.speech.body",
+ granted: speechStatus == .granted,
+ denied: speechPermissionDenied
+ )
+ }
+ .padding(.top, Spacing.xxl)
+
+ Text("onboarding.experience.permissions.systemHint")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textTertiary)
+ .multilineTextAlignment(.center)
+ .padding(.horizontal, Spacing.lg)
+ .padding(.top, Spacing.lg)
+
+ if !permissionsReady {
+ Button("onboarding.experience.permissions.later") {
+ goForward()
+ }
+ .font(TypeStyle.footnote)
+ .foregroundStyle(palette.textSecondary)
+ .padding(.top, Spacing.xl)
+ }
+ }
+ }
+
+ private func permissionRow(
+ icon: String,
+ title: LocalizedStringKey,
+ detail: LocalizedStringKey,
+ granted: Bool,
+ denied: Bool
+ ) -> some View {
+ HStack(spacing: Spacing.md) {
+ Image(systemName: icon)
+ .font(.system(size: 20, weight: .semibold))
+ .foregroundStyle(palette.accent)
+ .frame(width: 42, height: 42)
+ .background(palette.accentMuted, in: RoundedRectangle(cornerRadius: Radius.medium))
+
+ VStack(alignment: .leading, spacing: 2) {
+ Text(title)
+ .font(TypeStyle.bodyEmph)
+ .foregroundStyle(palette.textPrimary)
+ Text(detail)
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ }
+
+ Spacer(minLength: Spacing.sm)
+
+ Image(systemName: granted ? "checkmark.circle.fill" : (denied ? "exclamationmark.circle.fill" : "circle"))
+ .font(.system(size: 20, weight: .semibold))
+ .foregroundStyle(granted ? palette.accent : (denied ? palette.warning : palette.textTertiary))
+ .accessibilityHidden(true)
+ }
+ .padding(Spacing.md)
+ .background(palette.surface, in: RoundedRectangle(cornerRadius: Radius.large, style: .continuous))
+ .overlay(
+ RoundedRectangle(cornerRadius: Radius.large, style: .continuous)
+ .stroke(palette.divider, lineWidth: 0.5)
+ )
+ }
+
+ // MARK: - Keyboard setup
+
+ private var keyboardPage: some View {
+ OnboardingExperienceShell(
+ title: "onboarding.experience.keyboard.title",
+ subtitle: "onboarding.experience.keyboard.subtitle",
+ onBack: goBack
+ ) {
+ KeyboardSettingsPreview(isReady: keyboardReady || hasOpenedKeyboardSettings)
+ .padding(.top, Spacing.xxl)
+
+ HStack(spacing: Spacing.xs) {
+ Image(systemName: keyboardReady ? "checkmark.circle.fill" : "info.circle")
+ .foregroundStyle(keyboardReady ? palette.accent : palette.textSecondary)
+ Text(
+ keyboardReady
+ ? "onboarding.experience.keyboard.ready"
+ : "onboarding.experience.keyboard.fullAccess"
+ )
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ }
+ .padding(.top, Spacing.lg)
+
+ if hasOpenedKeyboardSettings, !keyboardReady {
+ Button("onboarding.experience.keyboard.openAgain") {
+ openKeyboardSettings()
+ }
+ .font(TypeStyle.footnote)
+ .foregroundStyle(palette.textSecondary)
+ .padding(.top, Spacing.lg)
+ }
+
+ resourceStatus
+ .padding(.top, Spacing.md)
+ }
+ .onAppear {
+ deployment.deployNow(reason: "onboarding.experience.keyboard")
+ }
+ }
+
+ @ViewBuilder
+ private var resourceStatus: some View {
+ switch deployment.status {
+ case .deploying:
+ Label("onboarding.enable.resources.preparing", systemImage: "hourglass")
+ .font(TypeStyle.caption2)
+ .foregroundStyle(palette.textTertiary)
+ case .ready:
+ EmptyView()
+ case .failed:
+ Button {
+ deployment.deployNow(force: true, reason: "onboarding.experience.retry")
+ } label: {
+ Label("onboarding.enable.resources.retry", systemImage: "arrow.clockwise")
+ .font(TypeStyle.caption)
+ }
+ .foregroundStyle(palette.warning)
+ case .idle:
+ EmptyView()
+ }
+ }
+
+ // MARK: - Real keyboard practice
+
+ private var practicePage: some View {
+ VStack(spacing: 0) {
+ HStack {
+ Button(action: goBack) {
+ Image(systemName: "chevron.left")
+ .font(.system(size: 17, weight: .semibold))
+ .foregroundStyle(palette.textPrimary)
+ .frame(width: 44, height: 44)
+ .contentShape(Rectangle())
+ }
+ .buttonStyle(.plain)
+ .accessibilityLabel(Text("common.back"))
+
+ Spacer()
+
+ Button("onboarding.experience.practice.skip") {
+ goToComplete()
+ }
+ .font(TypeStyle.footnote)
+ .foregroundStyle(palette.textSecondary)
+ }
+ .padding(.horizontal, Spacing.sm)
+
+ VStack(alignment: .leading, spacing: Spacing.sm) {
+ Text(practiceTitle)
+ .font(TypeStyle.title)
+ .foregroundStyle(palette.textPrimary)
+ .fixedSize(horizontal: false, vertical: true)
+
+ Text(practiceSubtitle)
+ .font(TypeStyle.body)
+ .foregroundStyle(palette.textSecondary)
+ .fixedSize(horizontal: false, vertical: true)
+
+ if managedPracticeReady, keyboardReady {
+ Text("onboarding.experience.practice.sample")
+ .font(.system(size: 20, weight: .medium, design: .rounded))
+ .foregroundStyle(palette.textPrimary)
+ .italic()
+ .padding(.top, Spacing.sm)
+ }
+ }
+ .frame(maxWidth: .infinity, alignment: .leading)
+ .padding(.horizontal, Spacing.xl)
+ .padding(.top, Spacing.sm)
+
+ practiceContent
+ .padding(.horizontal, Spacing.lg)
+ .padding(.top, Spacing.lg)
+ .padding(.bottom, Spacing.sm)
+
+ if managedPracticeReady, keyboardAppeared, !keyboardReady {
+ Button {
+ openKeyboardSettings()
+ } label: {
+ Label(
+ "onboarding.experience.practice.fullAccessAction",
+ systemImage: "arrow.up.right.square"
+ )
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.warning)
+ }
+ .buttonStyle(.plain)
+ .padding(.bottom, Spacing.sm)
+ }
+ }
+ }
+
+ @ViewBuilder
+ private var practiceContent: some View {
+ if !accountSession.isSignedIn {
+ VStack(spacing: Spacing.md) {
+ Image(systemName: "person.crop.circle.badge.checkmark")
+ .font(.system(size: 34, weight: .semibold))
+ .foregroundStyle(palette.accent)
+
+ Text("onboarding.experience.practice.signInBody")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ .multilineTextAlignment(.center)
+
+ AccountAppleAuthorizationButton(purpose: .signIn)
+ .disabled(accountSession.operation != nil)
+
+ accountOperationError
+ }
+ .practiceSetupCard(palette: palette)
+ } else if !config.hasAcknowledgedCloudSharing {
+ VStack(spacing: Spacing.md) {
+ Image(systemName: "sparkles")
+ .font(.system(size: 34, weight: .semibold))
+ .foregroundStyle(palette.accent)
+
+ Text("onboarding.experience.practice.cloudBody")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ .multilineTextAlignment(.center)
+
+ Button {
+ config.hasAcknowledgedCloudSharing = true
+ } label: {
+ Text("onboarding.experience.practice.cloudAction")
+ .primaryButton()
+ }
+ .buttonStyle(.plain)
+ }
+ .practiceSetupCard(palette: palette)
+ } else if isPreparingManagedPractice {
+ VStack(spacing: Spacing.md) {
+ ProgressView()
+ .tint(palette.accent)
+ Text("onboarding.experience.practice.preparingCredits")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ }
+ .practiceSetupCard(palette: palette)
+ } else if managedPracticeFailed {
+ VStack(spacing: Spacing.md) {
+ Image(systemName: "arrow.clockwise.circle")
+ .font(.system(size: 34, weight: .semibold))
+ .foregroundStyle(palette.warning)
+ Text("onboarding.experience.practice.creditsFailed")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ .multilineTextAlignment(.center)
+ Button("onboarding.enable.resources.retry") {
+ prepareManagedPractice()
+ }
+ .font(TypeStyle.bodyEmph)
+ .foregroundStyle(palette.accent)
+ accountOperationError
+ }
+ .practiceSetupCard(palette: palette)
+ } else {
+ practiceEditor
+ }
+ }
+
+ @ViewBuilder
+ private var accountOperationError: some View {
+ if let key = accountSession.operationErrorKey {
+ Text(LocalizedStringKey(key))
+ .font(TypeStyle.caption2)
+ .foregroundStyle(palette.warning)
+ .multilineTextAlignment(.center)
+ }
+ }
+
+ private var practiceEditor: some View {
+ VStack(spacing: 0) {
+ HStack(spacing: Spacing.xs) {
+ Image(systemName: "message.fill")
+ .foregroundStyle(palette.accent)
+ Text("onboarding.experience.practice.editorTitle")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ Spacer()
+ }
+ .padding(.horizontal, Spacing.md)
+ .frame(height: 42)
+
+ Divider().overlay(palette.divider)
+
+ TextEditor(text: $practiceText)
+ .font(TypeStyle.body)
+ .foregroundStyle(palette.textPrimary)
+ .scrollContentBackground(.hidden)
+ .focused($practiceFieldFocused)
+ .padding(Spacing.sm)
+ .accessibilityIdentifier("onboarding.practice.textEditor")
+ }
+ .frame(maxWidth: .infinity, minHeight: 172, maxHeight: 240)
+ .background(palette.surface, in: RoundedRectangle(cornerRadius: Radius.large, style: .continuous))
+ .overlay(
+ RoundedRectangle(cornerRadius: Radius.large, style: .continuous)
+ .stroke(keyboardReady ? palette.accent.opacity(0.42) : palette.divider, lineWidth: 1)
+ )
+ }
+
+ private var practiceTitle: LocalizedStringKey {
+ if !permissionsReady {
+ return "onboarding.experience.practice.permissionsTitle"
+ }
+ if !accountSession.isSignedIn {
+ return "onboarding.experience.practice.signInTitle"
+ }
+ if !config.hasAcknowledgedCloudSharing {
+ return "onboarding.experience.practice.cloudTitle"
+ }
+ if isPreparingManagedPractice || managedPracticeFailed {
+ return "onboarding.experience.practice.creditsTitle"
+ }
+ if !keyboardAppeared {
+ return "onboarding.experience.practice.switchTitle"
+ }
+ if !keyboardReady {
+ return "onboarding.experience.practice.fullAccessTitle"
+ }
+ return "onboarding.experience.practice.speakTitle"
+ }
+
+ private var practiceSubtitle: LocalizedStringKey {
+ if !permissionsReady {
+ return "onboarding.experience.practice.permissionsSubtitle"
+ }
+ if !accountSession.isSignedIn {
+ return "onboarding.experience.practice.signInSubtitle"
+ }
+ if !config.hasAcknowledgedCloudSharing {
+ return "onboarding.experience.practice.cloudSubtitle"
+ }
+ if isPreparingManagedPractice || managedPracticeFailed {
+ return "onboarding.experience.practice.creditsSubtitle"
+ }
+ if !keyboardAppeared {
+ return "onboarding.experience.practice.switchSubtitle"
+ }
+ if !keyboardReady {
+ return "onboarding.experience.practice.fullAccessSubtitle"
+ }
+ return "onboarding.experience.practice.speakSubtitle"
+ }
+
+ // MARK: - Complete
+
+ private var completePage: some View {
+ ScrollView {
+ VStack(spacing: 0) {
+ Spacer(minLength: Spacing.xxl)
+
+ ZStack {
+ Circle()
+ .fill(palette.accentMuted)
+ .frame(width: 108, height: 108)
+ Image(systemName: didVerifyVoiceInsertion ? "checkmark" : "sparkles")
+ .font(.system(size: 44, weight: .semibold))
+ .foregroundStyle(palette.accent)
+ }
+
+ Text(
+ didVerifyVoiceInsertion
+ ? "onboarding.experience.complete.verifiedTitle"
+ : "onboarding.experience.complete.title"
+ )
+ .font(TypeStyle.largeTitle)
+ .foregroundStyle(palette.textPrimary)
+ .multilineTextAlignment(.center)
+ .padding(.top, Spacing.xxl)
+
+ Text("onboarding.experience.complete.subtitle")
+ .font(TypeStyle.body)
+ .foregroundStyle(palette.textSecondary)
+ .multilineTextAlignment(.center)
+ .padding(.top, Spacing.sm)
+
+ if !practiceText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+ Text(practiceText)
+ .font(TypeStyle.body)
+ .foregroundStyle(palette.textPrimary)
+ .frame(maxWidth: .infinity, alignment: .leading)
+ .padding(Spacing.md)
+ .background(
+ palette.surface,
+ in: RoundedRectangle(cornerRadius: Radius.large, style: .continuous)
+ )
+ .overlay(
+ RoundedRectangle(cornerRadius: Radius.large, style: .continuous)
+ .stroke(palette.divider, lineWidth: 0.5)
+ )
+ .padding(.top, Spacing.xl)
+ }
+
+ HStack(spacing: Spacing.xs) {
+ capability("mic.fill", "onboarding.experience.complete.dictate")
+ capability("sparkles", "onboarding.experience.complete.agent")
+ capability("wand.and.stars", "onboarding.experience.complete.edit")
+ }
+ .padding(.top, Spacing.xxl)
+ }
+ .padding(.horizontal, Spacing.xl)
+ .padding(.bottom, Spacing.xl)
+ .frame(maxWidth: 560)
+ .frame(maxWidth: .infinity)
+ }
+ }
+
+ private func capability(_ icon: String, _ title: LocalizedStringKey) -> some View {
+ VStack(spacing: Spacing.xs) {
+ Image(systemName: icon)
+ .font(.system(size: 20, weight: .semibold))
+ .foregroundStyle(palette.accent)
+ Text(title)
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textPrimary)
+ }
+ .frame(maxWidth: .infinity)
+ .padding(.vertical, Spacing.md)
+ .background(palette.surface, in: RoundedRectangle(cornerRadius: Radius.medium))
+ }
+
+ // MARK: - Bottom action
+
+ private var bottomAction: some View {
+ Button(action: performPrimaryAction) {
+ HStack(spacing: Spacing.xs) {
+ if isRequestingPermissions {
+ ProgressView()
+ .tint(palette.textOnAccent)
+ }
+ Text(primaryActionTitle)
+ }
+ .primaryButton()
+ }
+ .buttonStyle(.plain)
+ .disabled(isRequestingPermissions)
+ }
+
+ private var primaryActionTitle: LocalizedStringKey {
+ switch currentStep {
+ case .introduction:
+ return "onboarding.experience.intro.action"
+ case .permissions:
+ if permissionsReady { return "common.continue" }
+ if micStatus == .denied || speechPermissionDenied {
+ return "onboarding.permission.openSettings"
+ }
+ return "common.continue"
+ case .keyboard:
+ if keyboardReady { return "onboarding.experience.keyboard.practiceAction" }
+ return hasOpenedKeyboardSettings
+ ? "common.continue"
+ : "onboarding.enable.openSettings"
+ case .practice:
+ return "common.continue"
+ case .complete:
+ return "onboarding.experience.complete.action"
+ }
+ }
+
+ private func performPrimaryAction() {
+ switch currentStep {
+ case .introduction:
+ goForward()
+ case .permissions:
+ handlePermissionAction()
+ case .keyboard:
+ if keyboardReady || hasOpenedKeyboardSettings {
+ goForward()
+ } else {
+ openKeyboardSettings()
+ }
+ case .practice:
+ break
+ case .complete:
+ finishOnboarding()
+ }
+ }
+
+ // MARK: - State and actions
+
+ private var permissionsReady: Bool {
+ micStatus == .granted && speechStatus == .granted
+ }
+
+ private var speechPermissionDenied: Bool {
+ speechStatus == .denied || speechStatus == .restricted
+ }
+
+ private func handlePermissionAction() {
+ if micStatus == .denied || speechPermissionDenied {
+ AppPermissions.openSystemSettings()
+ return
+ }
+ if permissionsReady {
+ goForward()
+ return
+ }
+
+ isRequestingPermissions = true
+ Task { @MainActor in
+ await AppPermissions.requestFlowPermissionsIfNeeded()
+ refreshState()
+ isRequestingPermissions = false
+ if permissionsReady {
+ goForward()
+ }
+ }
+ }
+
+ private func openKeyboardSettings() {
+ hasOpenedKeyboardSettings = true
+ AppPermissions.openSystemSettings()
+ }
+
+ private func beginPracticeIfNeeded() {
+ if practiceStartedAt == nil {
+ beginPractice()
+ } else if managedPracticeReady, permissionsReady {
+ KeyboardSetupBridge.setOnboardingPracticeActive(true)
+ flowManager.activateOnForeground(reason: "onboarding.practice.resume")
+ focusPracticeField()
+ } else if accountSession.isSignedIn, config.hasAcknowledgedCloudSharing {
+ prepareManagedPractice()
+ }
+ }
+
+ private func beginPractice() {
+ refreshState()
+ practiceStartedAt = nil
+ didVerifyVoiceInsertion = false
+ managedPracticeReady = false
+ managedPracticeFailed = false
+ KeyboardSetupBridge.setOnboardingPracticeActive(false)
+ if accountSession.isSignedIn, config.hasAcknowledgedCloudSharing {
+ prepareManagedPractice()
+ }
+ }
+
+ private func prepareManagedPractice() {
+ guard currentStep == .practice,
+ accountSession.isSignedIn,
+ config.hasAcknowledgedCloudSharing,
+ !isPreparingManagedPractice else { return }
+ isPreparingManagedPractice = true
+ managedPracticeFailed = false
+ managedPracticeReady = false
+ KeyboardSetupBridge.setOnboardingPracticeActive(false)
+
+ // OOBE keeps audio on-device. Only the transcript is sent to the
+ // managed polish gateway, where the request is tagged and audited.
+ config.engineMode = "local"
+ config.modeId = "polish"
+
+ Task { @MainActor in
+ let ready = await accountSession.prepareManagedGateway()
+ guard currentStep == .practice else { return }
+ isPreparingManagedPractice = false
+ guard ready else {
+ managedPracticeFailed = true
+ return
+ }
+
+ config.credentialSource = .managed
+ managedPracticeReady = true
+ practiceStartedAt = Date()
+ KeyboardSetupBridge.setOnboardingPracticeActive(true)
+ if permissionsReady {
+ flowManager.activateOnForeground(reason: "onboarding.practice.managed")
+ }
+ focusPracticeField()
+ }
+ }
+
+ private func focusPracticeField() {
+ Task { @MainActor in
+ try? await Task.sleep(for: .milliseconds(350))
+ guard currentStep == .practice else { return }
+ practiceFieldFocused = true
+ }
+ }
+
+ private func endPractice() {
+ practiceFieldFocused = false
+ isPreparingManagedPractice = false
+ managedPracticeReady = false
+ KeyboardSetupBridge.setOnboardingPracticeActive(false)
+ }
+
+ @MainActor
+ private func monitorPractice() async {
+ while !Task.isCancelled, currentStep == .practice {
+ refreshState()
+ if let startedAt = practiceStartedAt,
+ let insertedAt = KeyboardSetupBridge.lastVoiceInsertionAt,
+ insertedAt >= startedAt {
+ didVerifyVoiceInsertion = true
+ UINotificationFeedbackGenerator().notificationOccurred(.success)
+ try? await Task.sleep(for: .milliseconds(650))
+ guard !Task.isCancelled, currentStep == .practice else { return }
+ goToComplete()
+ return
+ }
+ try? await Task.sleep(for: .milliseconds(350))
+ }
+ }
+
+ private func refreshState() {
+ micStatus = AppPermissions.micStatus
+ speechStatus = AppPermissions.speechStatus
+ keyboardAppeared = KeyboardSetupBridge.hasAppeared
+ keyboardReady = KeyboardSetupBridge.isReadyForOnboardingSkip
+ }
+
+ private func goForward() {
+ let next = min(currentStep.rawValue + 1, OnboardingExperienceStep.complete.rawValue)
+ withAnimation(Motion.soft) {
+ config.onboardingPage = next
+ }
+ }
+
+ private func goBack() {
+ let previous = max(currentStep.rawValue - 1, OnboardingExperienceStep.introduction.rawValue)
+ withAnimation(Motion.soft) {
+ config.onboardingPage = previous
+ }
+ }
+
+ private func goToComplete() {
+ withAnimation(Motion.soft) {
+ config.onboardingPage = OnboardingExperienceStep.complete.rawValue
+ }
+ }
+
+ private func finishOnboarding() {
+ endPractice()
+ var transaction = Transaction()
+ transaction.disablesAnimations = true
+ withTransaction(transaction) {
+ config.hasCompletedOnboarding = true
+ }
+ }
+
+ private func applyPrivacySafeDefaultsIfNeeded() {
+ guard !config.hasCompletedOnboarding, config.onboardingPage == 0 else { return }
+ // First-run voice should work without asking users to understand an
+ // ASR provider or supply a cloud key.
+ if config.apiKey.isEmpty, config.engineMode == "cloud" {
+ config.engineMode = "local"
+ }
+ }
+
+ private func migrateLegacyProgressIfNeeded() {
+ let defaults = UserDefaults.standard
+ guard !defaults.bool(forKey: Self.migrationKey) else {
+ if OnboardingExperienceStep(rawValue: config.onboardingPage) == nil {
+ config.onboardingPage = 0
+ }
+ return
+ }
+
+ if !config.hasCompletedOnboarding {
+ switch config.onboardingPage {
+ case 1, 2:
+ config.onboardingPage = OnboardingExperienceStep.permissions.rawValue
+ case 3:
+ config.onboardingPage = OnboardingExperienceStep.keyboard.rawValue
+ case 4, 5:
+ config.onboardingPage = OnboardingExperienceStep.introduction.rawValue
+ default:
+ config.onboardingPage = OnboardingExperienceStep.introduction.rawValue
+ }
+ }
+ defaults.set(true, forKey: Self.migrationKey)
+ }
+}
+
+private extension View {
+ func practiceSetupCard(palette: ThemePalette) -> some View {
+ frame(maxWidth: .infinity, minHeight: 172)
+ .padding(Spacing.lg)
+ .background(
+ palette.surface,
+ in: RoundedRectangle(cornerRadius: Radius.large, style: .continuous)
+ )
+ .overlay(
+ RoundedRectangle(cornerRadius: Radius.large, style: .continuous)
+ .stroke(palette.divider, lineWidth: 0.5)
+ )
+ }
+}
+
+private struct OnboardingExperienceShell: View {
+ @Environment(\.themePalette) private var palette
+
+ let title: LocalizedStringKey
+ let subtitle: LocalizedStringKey
+ let onBack: () -> Void
+ @ViewBuilder let content: Content
+
+ var body: some View {
+ ScrollView {
+ VStack(spacing: 0) {
+ HStack {
+ Button(action: onBack) {
+ Image(systemName: "chevron.left")
+ .font(.system(size: 17, weight: .semibold))
+ .foregroundStyle(palette.textPrimary)
+ .frame(width: 44, height: 44)
+ .contentShape(Rectangle())
+ }
+ .buttonStyle(.plain)
+ .accessibilityLabel(Text("common.back"))
+ Spacer()
+ }
+
+ VStack(spacing: Spacing.sm) {
+ Text(title)
+ .font(TypeStyle.largeTitle)
+ .foregroundStyle(palette.textPrimary)
+ Text(subtitle)
+ .font(TypeStyle.body)
+ .foregroundStyle(palette.textSecondary)
+ .fixedSize(horizontal: false, vertical: true)
+ }
+ .multilineTextAlignment(.center)
+ .padding(.top, Spacing.xl)
+
+ content
+
+ Spacer(minLength: Spacing.xl)
+ }
+ .padding(.horizontal, Spacing.xl)
+ .frame(maxWidth: 560)
+ .frame(maxWidth: .infinity)
+ }
+ }
+}
+
+private struct KeyboardSettingsPreview: View {
+ @Environment(\.themePalette) private var palette
+
+ let isReady: Bool
+
+ var body: some View {
+ VStack(spacing: 0) {
+ HStack {
+ Text("onboarding.experience.keyboard.previewTitle")
+ .font(TypeStyle.caption)
+ .foregroundStyle(palette.textSecondary)
+ Spacer()
+ }
+ .padding(.horizontal, Spacing.md)
+ .frame(height: 42)
+
+ Divider().overlay(palette.divider)
+
+ HStack(spacing: Spacing.md) {
+ Image("OSGBrandMark")
+ .renderingMode(.template)
+ .resizable()
+ .scaledToFit()
+ .foregroundStyle(palette.textPrimary)
+ .frame(width: 28, height: 28)
+
+ Text("OSGKeyboard")
+ .font(TypeStyle.bodyEmph)
+ .foregroundStyle(palette.textPrimary)
+
+ Spacer()
+
+ ZStack(alignment: isReady ? .trailing : .leading) {
+ Capsule()
+ .fill(isReady ? palette.accent : palette.surfaceElevated)
+ .frame(width: 48, height: 28)
+ Circle()
+ .fill(isReady ? palette.textOnAccent : palette.textTertiary)
+ .frame(width: 22, height: 22)
+ .padding(3)
+ }
+ .animation(Motion.quick, value: isReady)
+ .accessibilityHidden(true)
+ }
+ .padding(Spacing.md)
+ }
+ .background(palette.surface, in: RoundedRectangle(cornerRadius: Radius.xl, style: .continuous))
+ .overlay(
+ RoundedRectangle(cornerRadius: Radius.xl, style: .continuous)
+ .stroke(palette.dividerStrong, lineWidth: 0.5)
+ )
+ }
+}
diff --git a/OSGKeyboard/Views/SettingsSecondaryPages.swift b/OSGKeyboard/Views/SettingsSecondaryPages.swift
index 7944263..6c6e106 100644
--- a/OSGKeyboard/Views/SettingsSecondaryPages.swift
+++ b/OSGKeyboard/Views/SettingsSecondaryPages.swift
@@ -565,11 +565,35 @@ struct ClipboardSettingsView: View {
struct AboutSettingsView: View {
@Environment(\.themePalette) private var palette: ThemePalette
@Environment(\.openURL) private var openURL
+ @EnvironmentObject private var analytics: AnalyticsHostService
@ObservedObject var config: ProviderConfig
var body: some View {
ScrollView {
CardPageContent {
+ CardSection("settings.analytics.section") {
+ VStack(alignment: .leading, spacing: 0) {
+ Toggle(
+ "settings.analytics.title",
+ isOn: Binding(
+ get: { analytics.isEnabled },
+ set: { analytics.setEnabled($0) }
+ )
+ )
+ .tint(palette.accent)
+ .settingsListRow()
+
+ Divider().background(palette.divider)
+
+ Text("settings.analytics.description")
+ .font(TypeStyle.caption2)
+ .foregroundStyle(palette.textSecondary)
+ .fixedSize(horizontal: false, vertical: true)
+ .settingsListRow()
+ }
+ .surfaceCard()
+ }
+
CardSection("settings.about.title") {
VStack(spacing: 0) {
Button {
@@ -637,5 +661,8 @@ struct AboutSettingsView: View {
.navigationTitle("settings.about.title")
.navigationBarTitleDisplayMode(.inline)
.hidesTabBarWhenPushed()
+ .onAppear {
+ analytics.refreshEnabledState()
+ }
}
}
diff --git a/OSGKeyboard/en.lproj/Localizable.strings b/OSGKeyboard/en.lproj/Localizable.strings
index f881ab2..9476887 100644
--- a/OSGKeyboard/en.lproj/Localizable.strings
+++ b/OSGKeyboard/en.lproj/Localizable.strings
@@ -36,6 +36,58 @@
"onboarding.polish.title" = "Text polish (LLM)";
"onboarding.polish.subtitle" = "Cleans up the transcript after recognition. Can differ from the ASR provider.";
"onboarding.polish.localHint" = "Fill in an API key to enable AI polish. Without a key, raw ASR text is inserted.";
+"onboarding.experience.intro.eyebrow" = "AI AGENT VOICE KEYBOARD";
+"onboarding.experience.intro.title" = "Speak. It’s written.";
+"onboarding.experience.intro.subtitle" = "More than dictation. OSGKeyboard understands, writes, translates, and edits—then its AI Agent helps with what comes next.";
+"onboarding.experience.intro.action" = "Get Started";
+"onboarding.experience.privacy.local.title" = "On-device transcription available";
+"onboarding.experience.privacy.local.body" = "With the local engine, speech recognition stays on your device.";
+"onboarding.experience.privacy.cloud.title" = "Clear cloud boundaries";
+"onboarding.experience.privacy.cloud.body" = "Audio or text is sent only when you choose cloud recognition or an AI feature, and only to the configured service.";
+"onboarding.experience.privacy.anywhere.title" = "Your AI Agent, in any app";
+"onboarding.experience.privacy.anywhere.body" = "Dictate, translate, edit, and act from chat, email, notes, or code.";
+"onboarding.experience.permissions.title" = "Let OSGKeyboard hear you";
+"onboarding.experience.permissions.subtitle" = "Voice input needs microphone and speech recognition access. Two system prompts will appear next.";
+"onboarding.experience.permissions.systemHint" = "These permissions are used only when you start voice input.";
+"onboarding.experience.permissions.later" = "Set Up Later";
+"onboarding.experience.keyboard.title" = "Add OSGKeyboard";
+"onboarding.experience.keyboard.subtitle" = "Add the keyboard in iOS Settings and turn on Allow Full Access.";
+"onboarding.experience.keyboard.ready" = "OSGKeyboard and Full Access are ready";
+"onboarding.experience.keyboard.fullAccess" = "Full Access connects the keyboard to the host app microphone and optional AI services";
+"onboarding.experience.keyboard.openAgain" = "Open Settings Again";
+"onboarding.experience.keyboard.practiceAction" = "Try It Now";
+"onboarding.experience.keyboard.previewTitle" = "Keyboards";
+"onboarding.experience.practice.skip" = "Try Later";
+"onboarding.experience.practice.sample" = "“I’ll arrive tomorrow afternoon and message you when I’m there.”";
+"onboarding.experience.practice.editorTitle" = "New Message";
+"onboarding.experience.practice.permissionsTitle" = "Voice access is still needed";
+"onboarding.experience.practice.permissionsSubtitle" = "Go back to finish permission setup, then try your first voice input.";
+"onboarding.experience.practice.switchTitle" = "Switch to OSGKeyboard";
+"onboarding.experience.practice.switchSubtitle" = "Tap the field below, hold the globe key, then choose OSGKeyboard.";
+"onboarding.experience.practice.fullAccessTitle" = "One more setting";
+"onboarding.experience.practice.fullAccessSubtitle" = "OSGKeyboard is enabled. Turn on Allow Full Access to use voice input.";
+"onboarding.experience.practice.fullAccessAction" = "Turn On Full Access";
+"onboarding.experience.practice.signInTitle" = "Sign in for a free AI writing trial";
+"onboarding.experience.practice.signInSubtitle" = "The lesson uses OSG Credits by default. This OOBE request will not deduct any credits.";
+"onboarding.experience.practice.signInBody" = "Sign in with Apple to claim one free OOBE AI polish. Speech is still transcribed on your device.";
+"onboarding.experience.practice.cloudTitle" = "Enable the free OOBE experience";
+"onboarding.experience.practice.cloudSubtitle" = "Only this transcript is sent to OSG managed AI and explicitly tagged as OOBE.";
+"onboarding.experience.practice.cloudBody" = "The server verifies this lesson as OOBE, with no credit reservation or charge. OSG Credits becomes your default AI service afterward.";
+"onboarding.experience.practice.cloudAction" = "Agree & Try for Free";
+"onboarding.experience.practice.creditsTitle" = "Preparing OSG Credits";
+"onboarding.experience.practice.creditsSubtitle" = "This OOBE lesson is completely free.";
+"onboarding.experience.practice.preparingCredits" = "Preparing your free OOBE request…";
+"onboarding.experience.practice.creditsFailed" = "OSG Credits is temporarily unavailable. Try again—no credits were deducted.";
+"onboarding.experience.practice.speakTitle" = "Now, say something";
+"onboarding.experience.practice.speakSubtitle" = "Tap the microphone on the keyboard, speak, then tap it again. Your text will appear here.";
+"onboarding.experience.complete.verifiedTitle" = "That’s it.";
+"onboarding.experience.complete.title" = "You’re ready";
+"onboarding.experience.complete.subtitle" = "Switch to OSGKeyboard in any text field to speak, write, or hand off the next step to your AI Agent.";
+"onboarding.experience.complete.dictate" = "Voice to Text";
+"onboarding.experience.complete.translate" = "Translate";
+"onboarding.experience.complete.agent" = "AI Agent";
+"onboarding.experience.complete.edit" = "Voice Edit";
+"onboarding.experience.complete.action" = "Start Using";
"settings.onboarding.replay" = "Restart permission setup";
/* Common navigation */
@@ -419,6 +471,11 @@
"home.setup.keyboardHint" = "Don't see OSGKeyboard? Add it in iOS Settings.";
"home.setup.keyboardHint.dismiss" = "Got it";
"home.flow.starting" = "Starting voice session…";
+"home.flow.preparingProgress" = "Preparing background session (%d/%d)…";
+"home.flow.recoveringProgress" = "Restoring background session (%d/%d)…";
+"home.flow.waitingForForeground" = "Background session paused — reopen this app to restore it";
+"home.flow.recoveryFailed" = "Background session needs attention";
+"home.flow.retry" = "Retry";
"home.flow.openSettings" = "Open Settings to grant permissions";
"home.flow.start" = "Start voice session";
"home.flow.end" = "End voice session";
@@ -805,3 +862,6 @@
"account.managed.accountCredits" = "Account credits";
"account.managed.explanation" = "This choice is independent from local or cloud speech recognition. Account sessions remain private to the host app; the keyboard receives only a short-lived, limited grant.";
"account.managed.preparing" = "Preparing managed access…";
+"settings.analytics.section" = "Privacy";
+"settings.analytics.title" = "Product Analytics";
+"settings.analytics.description" = "Helps improve reliability with limited first-party events. Keyboard input, audio, transcripts, prompts, model output, credentials, and personal identifiers are never collected. Turning this off deletes queued events from this device.";
diff --git a/OSGKeyboard/zh-Hans.lproj/Localizable.strings b/OSGKeyboard/zh-Hans.lproj/Localizable.strings
index 87f193d..eb3aeee 100644
--- a/OSGKeyboard/zh-Hans.lproj/Localizable.strings
+++ b/OSGKeyboard/zh-Hans.lproj/Localizable.strings
@@ -36,6 +36,58 @@
"onboarding.polish.title" = "文本润色（LLM）";
"onboarding.polish.subtitle" = "识别完成后整理文字，可与 ASR 服务商不同。";
"onboarding.polish.localHint" = "填写 API Key 才能开启 AI 润色；未填写时将直接插入原始识别结果。";
+"onboarding.experience.intro.eyebrow" = "AI AGENT 语音输入法";
+"onboarding.experience.intro.title" = "开口，即成文";
+"onboarding.experience.intro.subtitle" = "不只是语音输入。OSGKeyboard 能听懂、成文、翻译和编辑，也能调用 AI Agent 帮你处理下一步。";
+"onboarding.experience.intro.action" = "开始设置";
+"onboarding.experience.privacy.local.title" = "支持设备端转写";
+"onboarding.experience.privacy.local.body" = "使用本地引擎时，语音识别在你的设备上完成。";
+"onboarding.experience.privacy.cloud.title" = "明确的云端边界";
+"onboarding.experience.privacy.cloud.body" = "只有选择云端识别或 AI 功能时，相应的语音或文字才会发送给已配置的服务。";
+"onboarding.experience.privacy.anywhere.title" = "AI Agent，随处可用";
+"onboarding.experience.privacy.anywhere.body" = "在聊天、邮件、笔记或代码编辑中，随时口述、翻译、编辑和处理任务。";
+"onboarding.experience.permissions.title" = "让 OSGKeyboard 听见你";
+"onboarding.experience.permissions.subtitle" = "语音输入需要麦克风和语音识别。接下来会依次出现两个系统提示。";
+"onboarding.experience.permissions.systemHint" = "权限只在你主动使用语音输入时生效。";
+"onboarding.experience.permissions.later" = "暂时跳过";
+"onboarding.experience.keyboard.title" = "添加 OSGKeyboard";
+"onboarding.experience.keyboard.subtitle" = "在 iOS 设置中添加键盘，并打开「允许完全访问」。";
+"onboarding.experience.keyboard.ready" = "OSGKeyboard 与完全访问均已就绪";
+"onboarding.experience.keyboard.fullAccess" = "完全访问用于连接主 App 的麦克风和可选 AI 服务";
+"onboarding.experience.keyboard.openAgain" = "再次打开设置";
+"onboarding.experience.keyboard.practiceAction" = "开始体验";
+"onboarding.experience.keyboard.previewTitle" = "键盘";
+"onboarding.experience.practice.skip" = "稍后体验";
+"onboarding.experience.practice.sample" = "“我明天下午到，到了以后给你消息。”";
+"onboarding.experience.practice.editorTitle" = "新消息";
+"onboarding.experience.practice.permissionsTitle" = "还需要语音权限";
+"onboarding.experience.practice.permissionsSubtitle" = "返回上一步完成权限设置，然后开始第一次语音输入。";
+"onboarding.experience.practice.switchTitle" = "切换到 OSGKeyboard";
+"onboarding.experience.practice.switchSubtitle" = "点一下下面的文本框，长按地球键，然后选择 OSGKeyboard。";
+"onboarding.experience.practice.fullAccessTitle" = "再完成一个设置";
+"onboarding.experience.practice.fullAccessSubtitle" = "OSGKeyboard 已启用。打开「允许完全访问」后就能使用语音。";
+"onboarding.experience.practice.fullAccessAction" = "去设置打开完全访问";
+"onboarding.experience.practice.signInTitle" = "登录，免费体验 AI 成文";
+"onboarding.experience.practice.signInSubtitle" = "教学体验默认使用 OSG 积分服务，本次 OOBE 请求不会扣除任何积分。";
+"onboarding.experience.practice.signInBody" = "使用 Apple 登录以领取一次免费的 OOBE AI 润色。语音仍在设备端转写。";
+"onboarding.experience.practice.cloudTitle" = "启用免费 OOBE 体验";
+"onboarding.experience.practice.cloudSubtitle" = "仅将本次转写文字发送到 OSG 托管 AI，并明确标记为 OOBE。";
+"onboarding.experience.practice.cloudBody" = "本次教学请求由服务端验证为 OOBE，不预扣、不结算积分。完成后，OSG 积分将作为默认 AI 服务。";
+"onboarding.experience.practice.cloudAction" = "同意并免费体验";
+"onboarding.experience.practice.creditsTitle" = "正在准备 OSG 积分服务";
+"onboarding.experience.practice.creditsSubtitle" = "本次 OOBE 教学完全免费。";
+"onboarding.experience.practice.preparingCredits" = "正在准备免费 OOBE 请求…";
+"onboarding.experience.practice.creditsFailed" = "暂时无法连接 OSG 积分服务，请重试。不会扣除积分。";
+"onboarding.experience.practice.speakTitle" = "现在，说一句话";
+"onboarding.experience.practice.speakSubtitle" = "点按键盘上的麦克风，说完后再点一次。文字会直接出现在这里。";
+"onboarding.experience.complete.verifiedTitle" = "就是这样。";
+"onboarding.experience.complete.title" = "已经准备好了";
+"onboarding.experience.complete.subtitle" = "以后在任何输入框切换到 OSGKeyboard，开口成文，也可以继续交给 AI Agent。";
+"onboarding.experience.complete.dictate" = "语音成文";
+"onboarding.experience.complete.translate" = "翻译";
+"onboarding.experience.complete.agent" = "AI Agent";
+"onboarding.experience.complete.edit" = "语音编辑";
+"onboarding.experience.complete.action" = "开始使用";
"settings.onboarding.replay" = "重新开始权限引导";
/* Common navigation */
@@ -418,6 +470,11 @@
"home.setup.keyboardHint" = "列表里没有？去系统设置里添加键盘。";
"home.setup.keyboardHint.dismiss" = "知道了";
"home.flow.starting" = "正在启动语音会话…";
+"home.flow.preparingProgress" = "正在准备后台会话（%d/%d）…";
+"home.flow.recoveringProgress" = "正在恢复后台会话（%d/%d）…";
+"home.flow.waitingForForeground" = "后台会话已暂停，重新打开本 App 后自动恢复";
+"home.flow.recoveryFailed" = "后台会话需要恢复";
+"home.flow.retry" = "重试";
"home.flow.openSettings" = "去设置打开权限";
"home.flow.start" = "启动语音会话";
"home.flow.end" = "结束语音会话";
@@ -804,3 +861,6 @@
"account.managed.accountCredits" = "账号积分";
"account.managed.explanation" = "该选择与本地或云端语音识别相互独立。账号会话仅保存在主 App，键盘只能获得短时、受限的网关授权。";
"account.managed.preparing" = "正在准备托管服务…";
+"settings.analytics.section" = "隐私";
+"settings.analytics.title" = "产品分析";
+"settings.analytics.description" = "通过有限的第一方事件帮助改进可靠性。绝不收集键盘输入、音频、转录、Prompt、模型输出、凭证或个人标识。关闭后会删除本机尚未上传的事件。";
diff --git a/OSGKeyboardExt/KeyboardViewController.swift b/OSGKeyboardExt/KeyboardViewController.swift
index 1713bb4..afd4fcb 100644
--- a/OSGKeyboardExt/KeyboardViewController.swift
+++ b/OSGKeyboardExt/KeyboardViewController.swift
@@ -205,6 +205,7 @@ public final class KeyboardViewController: UIInputViewController {
public override func viewWillDisappear(_ animated: Bool) {
super.viewWillDisappear(animated)
+ AnalyticsExtensionService.shared.keyboardWillDisappear()
assistantFieldActionRefreshTask?.cancel()
assistantFieldActionRefreshTask = nil
clipboardCapture?.keyboardWillDisappear()
@@ -305,6 +306,9 @@ public final class KeyboardViewController: UIInputViewController {
public override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
+ AnalyticsExtensionService.shared.recordPresentation(
+ hasFullAccess: hasFullAccess
+ )
OSGDiag.log(
"KVC.viewDidAppear begin surface=\(state.surface.rawValue) \(OSGDiag.memoryTag())",
category: "boot"
diff --git a/OSGKeyboardExt/PrivacyInfo.xcprivacy b/OSGKeyboardExt/PrivacyInfo.xcprivacy
index 93cac16..db59cb7 100644
--- a/OSGKeyboardExt/PrivacyInfo.xcprivacy
+++ b/OSGKeyboardExt/PrivacyInfo.xcprivacy
@@ -5,7 +5,44 @@
NSPrivacyTracking
NSPrivacyCollectedDataTypes
-
+
+
+ NSPrivacyCollectedDataType
+ NSPrivacyCollectedDataTypeDeviceID
+ NSPrivacyCollectedDataTypeLinked
+
+ NSPrivacyCollectedDataTypeTracking
+
+ NSPrivacyCollectedDataTypePurposes
+
+ NSPrivacyCollectedDataTypePurposeAnalytics
+
+
+
+ NSPrivacyCollectedDataType
+ NSPrivacyCollectedDataTypeProductInteraction
+ NSPrivacyCollectedDataTypeLinked
+
+ NSPrivacyCollectedDataTypeTracking
+
+ NSPrivacyCollectedDataTypePurposes
+
+ NSPrivacyCollectedDataTypePurposeAnalytics
+
+
+
+ NSPrivacyCollectedDataType
+ NSPrivacyCollectedDataTypeOtherUsageData
+ NSPrivacyCollectedDataTypeLinked
+
+ NSPrivacyCollectedDataTypeTracking
+
+ NSPrivacyCollectedDataTypePurposes
+
+ NSPrivacyCollectedDataTypePurposeAnalytics
+
+
+
NSPrivacyAccessedAPITypes
diff --git a/OSGKeyboardExt/Services/AnalyticsExtensionService.swift b/OSGKeyboardExt/Services/AnalyticsExtensionService.swift
new file mode 100644
index 0000000..9d87144
--- /dev/null
+++ b/OSGKeyboardExt/Services/AnalyticsExtensionService.swift
@@ -0,0 +1,110 @@
+// AnalyticsExtensionService.swift
+// OSGKeyboard · Keyboard Extension
+//
+// The extension records into the shared SQLite queue and only attempts one
+// short anonymous batch when Full Access permits network use.
+
+import Foundation
+import OSGKeyboardShared
+import OSLog
+
+private actor ExtensionAnalyticsUploadSignal: AnalyticsUploadTriggering {
+ typealias Action = @Sendable () async -> Void
+
+ private var action: Action?
+ private var canUpload = false
+ private var isUploading = false
+
+ func install(_ action: @escaping Action) {
+ self.action = action
+ }
+
+ func setCanUpload(_ canUpload: Bool) {
+ self.canUpload = canUpload
+ }
+
+ func requestUpload() {
+ guard canUpload, !isUploading, let action else { return }
+ isUploading = true
+ Task {
+ await action()
+ uploadFinished()
+ }
+ }
+
+ private func uploadFinished() {
+ isUploading = false
+ }
+}
+
+private struct ExtensionAnalyticsLogger: AnalyticsLogging {
+ private let logger = Logger(
+ subsystem: Bundle.main.bundleIdentifier ?? "com.osgkeyboard.ios.keyboard",
+ category: "analytics"
+ )
+
+ func log(_ entry: AnalyticsUploadLogEntry) {
+ let statusCode = entry.statusCode ?? 0
+ let errorCategory = entry.errorCategory?.rawValue ?? "none"
+ logger.info(
+ "outcome=\(entry.outcome.rawValue, privacy: .public) count=\(entry.eventCount, privacy: .public) status=\(statusCode, privacy: .public) attempt=\(entry.attempt, privacy: .public) error=\(errorCategory, privacy: .public)"
+ )
+ }
+}
+
+final class AnalyticsExtensionService: Sendable {
+ static let shared = AnalyticsExtensionService()
+
+ let client: any AnalyticsClient
+
+ private let runtime: AnalyticsRuntime
+ private let uploadSignal: ExtensionAnalyticsUploadSignal
+
+ private init() {
+ let signal = ExtensionAnalyticsUploadSignal()
+ uploadSignal = signal
+ let runtime = AnalyticsRuntime.keyboardExtension(
+ environment: Self.environment,
+ uploadConfiguration: AnalyticsUploadConfiguration(endpoint: Self.endpoint),
+ trigger: signal,
+ logger: ExtensionAnalyticsLogger()
+ )
+ self.runtime = runtime
+ client = runtime.client
+
+ Task {
+ await signal.install {
+ await runtime.uploadCoordinator.uploadAvailableEvents(maximumBatches: 1)
+ }
+ }
+ }
+
+ func recordPresentation(hasFullAccess: Bool) {
+ Task {
+ await uploadSignal.setCanUpload(hasFullAccess)
+ client.recordSessionActivity()
+ client.recordKeyboardActivated()
+ }
+ }
+
+ func keyboardWillDisappear() {
+ Task {
+ await uploadSignal.setCanUpload(false)
+ }
+ }
+
+ private static let endpoint = URL(
+ string: "https://account.osglab.com/v1/analytics/events"
+ )!
+
+ private static var environment: AnalyticsEnvironment {
+ let appVersion = Bundle.main.object(
+ forInfoDictionaryKey: "CFBundleShortVersionString"
+ ) as? String ?? "unknown"
+ let version = ProcessInfo.processInfo.operatingSystemVersion
+ return AnalyticsEnvironment(
+ appVersion: appVersion,
+ osVersion: "\(version.majorVersion).\(version.minorVersion).\(version.patchVersion)"
+ )
+ }
+}
diff --git a/OSGKeyboardExt/Services/KeyboardConfigSync.swift b/OSGKeyboardExt/Services/KeyboardConfigSync.swift
index ca160d8..afc723c 100644
--- a/OSGKeyboardExt/Services/KeyboardConfigSync.swift
+++ b/OSGKeyboardExt/Services/KeyboardConfigSync.swift
@@ -92,6 +92,7 @@ final class KeyboardConfigSync {
// Keychain fallback: a reboot must not resurrect the mic gate when
// App Group transiently reads empty.
state.hasCompletedOnboarding = store.hasCompletedOnboarding || Keychain.hasCompletedOnboarding()
+ state.isOnboardingPracticeActive = KeyboardSetupBridge.isOnboardingPracticeActive
}
func persistLocale(_ id: String) {
diff --git a/OSGKeyboardExt/Services/KeyboardFlowCoordinator.swift b/OSGKeyboardExt/Services/KeyboardFlowCoordinator.swift
index 140676d..b67531b 100644
--- a/OSGKeyboardExt/Services/KeyboardFlowCoordinator.swift
+++ b/OSGKeyboardExt/Services/KeyboardFlowCoordinator.swift
@@ -125,6 +125,10 @@ final class KeyboardFlowCoordinator {
|| currentUtteranceRequest != nil
}
+ private var voiceSetupReady: Bool {
+ state.hasCompletedOnboarding || state.isOnboardingPracticeActive
+ }
+
var isEditSessionActive: Bool { currentUtteranceRequest?.isEdit == true }
/// Session/transcription changes are pushed in real time by Darwin
@@ -159,7 +163,7 @@ final class KeyboardFlowCoordinator {
/// noise used to call this again while `ready` briefly lagged).
func ensurePiPReadyOnKeyboardOpen() {
guard FlowHandoffPolicy.allowsProactiveHostAutoLaunch,
- state.hasCompletedOnboarding,
+ voiceSetupReady,
hasFullAccess(),
AppGroup.isAvailable,
!isPendingFlowStart,
@@ -335,7 +339,7 @@ final class KeyboardFlowCoordinator {
appGroupAvailable: AppGroup.isAvailable,
hostReady: hostReady,
isPreparingSession: isPendingFlowStart || hostWarming,
- hasCompletedOnboarding: state.hasCompletedOnboarding
+ hasCompletedOnboarding: voiceSetupReady
)
let signature = [
"phase=\(String(describing: state.phase))",
@@ -1070,7 +1074,7 @@ final class KeyboardFlowCoordinator {
}
func beginFlowStart(recordAfterHandoff: Bool = false) {
- guard state.hasCompletedOnboarding else {
+ guard voiceSetupReady else {
promptFinishSetupInApp()
return
}
@@ -1177,6 +1181,8 @@ final class KeyboardFlowCoordinator {
let mode: FlowUtteranceMode? = request.mode == .dictation
? nil
: request.mode
+ let managedRequestPurpose = request.managedRequestPurpose
+ ?? (state.isOnboardingPracticeActive && request.mode == .dictation ? .oobe : nil)
let command = FlowCommand(
sessionId: activeSessionId,
utteranceId: currentUtteranceId,
@@ -1194,6 +1200,7 @@ final class KeyboardFlowCoordinator {
sourceHistoryEntryRevision: request.sourceHistoryEntryRevision,
aiConversationID: request.aiConversationID,
aiTaskKind: request.aiTaskKind,
+ managedRequestPurpose: managedRequestPurpose,
startDeadlineAt: action == .startRecording ? currentStartDeadlineAt : nil,
processingDeadlineAt: action == .stopRecording && request.isEdit
? Date().timeIntervalSince1970
diff --git a/OSGKeyboardExt/Services/KeyboardTextInserter.swift b/OSGKeyboardExt/Services/KeyboardTextInserter.swift
index 4fcf25f..319b904 100644
--- a/OSGKeyboardExt/Services/KeyboardTextInserter.swift
+++ b/OSGKeyboardExt/Services/KeyboardTextInserter.swift
@@ -88,6 +88,7 @@ final class KeyboardTextInserter {
)
let inserted = separator + trimmed
insertText(inserted)
+ KeyboardSetupBridge.markVoiceInsertion()
state.noteUserDidInputText()
recordLastInsertion(
inserted,
diff --git a/OSGKeyboardExt/Views/AIKeyboardView.swift b/OSGKeyboardExt/Views/AIKeyboardView.swift
index 3231a79..b62e010 100644
--- a/OSGKeyboardExt/Views/AIKeyboardView.swift
+++ b/OSGKeyboardExt/Views/AIKeyboardView.swift
@@ -292,7 +292,15 @@ struct AIKeyboardView: View {
@ViewBuilder
private var contextArea: some View {
ZStack {
- if let tip = state.skillTipText, !tip.isEmpty {
+ if state.isOnboardingPracticeActive, activeStatus == nil {
+ Text(ExtL10n.string("keyboard.onboarding.practice.mic"))
+ .font(.system(size: 13, weight: .semibold))
+ .foregroundStyle(palette.textPrimary)
+ .lineLimit(1)
+ .padding(.horizontal, 14)
+ .frame(height: Layout.hotwordHeight)
+ .background(palette.accentMuted, in: Capsule())
+ } else if let tip = state.skillTipText, !tip.isEmpty {
IntrinsicWidthCap(maxWidth: Layout.skillTipMaxWidth) {
Text(tip)
.font(TypeStyle.body)
diff --git a/OSGKeyboardExt/en.lproj/Keyboard.strings b/OSGKeyboardExt/en.lproj/Keyboard.strings
index cd10f5b..c255b60 100644
--- a/OSGKeyboardExt/en.lproj/Keyboard.strings
+++ b/OSGKeyboardExt/en.lproj/Keyboard.strings
@@ -14,6 +14,7 @@
"onboarding.api.subtitle" = "Local ASR needs no key; add an API key to enable AI polish.";
"onboarding.api.localReady.title" = "Local ASR is ready";
"onboarding.api.localReady.body" = "Recognition works on-device. Add an API key in Settings for AI polish.";
+"keyboard.onboarding.practice.mic" = "Tap the mic, then tap again when done";
/* Common navigation */
"common.back" = "Back";
diff --git a/OSGKeyboardExt/zh-Hans.lproj/Keyboard.strings b/OSGKeyboardExt/zh-Hans.lproj/Keyboard.strings
index 81e2770..e71e0db 100644
--- a/OSGKeyboardExt/zh-Hans.lproj/Keyboard.strings
+++ b/OSGKeyboardExt/zh-Hans.lproj/Keyboard.strings
@@ -14,6 +14,7 @@
"onboarding.api.subtitle" = "本地识别无需 Key；填写 API Key 后可开启 AI 润色。";
"onboarding.api.localReady.title" = "本地识别已就绪";
"onboarding.api.localReady.body" = "识别在端侧完成。请在设置中填写 API Key 以开启 AI 润色。";
+"keyboard.onboarding.practice.mic" = "点按麦克风，说完后再点一次";
/* Common navigation */
"common.back" = "返回";
diff --git a/OSGKeyboardExtTests/AnalyticsExtensionPrivacyTests.swift b/OSGKeyboardExtTests/AnalyticsExtensionPrivacyTests.swift
new file mode 100644
index 0000000..513858c
--- /dev/null
+++ b/OSGKeyboardExtTests/AnalyticsExtensionPrivacyTests.swift
@@ -0,0 +1,138 @@
+// AnalyticsExtensionPrivacyTests.swift
+// OSGKeyboardExtTests
+//
+// The keyboard analytics runtime is anonymous and emits only typed dimensions.
+
+import Foundation
+@testable import OSGKeyboardShared
+import XCTest
+
+final class AnalyticsExtensionPrivacyTests: XCTestCase {
+ func testKeyboardRuntimeUploadsWithoutAuthorizationOrSensitiveInputFields() async throws {
+ let databaseURL = try temporaryDatabaseURL()
+ let network = ExtensionAnalyticsNetwork()
+ let runtime = AnalyticsRuntime.keyboardExtension(
+ environment: AnalyticsEnvironment(appVersion: "2.0.0", osVersion: "26.0"),
+ repositoryConfiguration: AnalyticsRepositoryConfiguration(
+ databaseURL: databaseURL
+ ),
+ uploadConfiguration: AnalyticsUploadConfiguration(
+ endpoint: URL(string: "https://analytics.test/v1/events")!
+ ),
+ network: network,
+ wallClock: ExtensionAnalyticsClock(),
+ monotonicClock: ExtensionAnalyticsMonotonicClock(),
+ uuidGenerator: ExtensionAnalyticsUUIDGenerator(),
+ random: ExtensionAnalyticsRandomGenerator()
+ )
+
+ runtime.client.recordKeyboardActivated()
+ for _ in 0..<200 {
+ if await runtime.repository.debugSnapshot().pendingEvents.count == 1 {
+ break
+ }
+ try await Task.sleep(for: .milliseconds(10))
+ }
+ let pendingSnapshot = await runtime.repository.debugSnapshot()
+ XCTAssertEqual(pendingSnapshot.pendingEvents.count, 1)
+
+ await runtime.uploadCoordinator.uploadAvailableEvents()
+
+ let requests = await network.requests()
+ let request = try XCTUnwrap(requests.first)
+ XCTAssertEqual(requests.count, 1)
+ XCTAssertNil(
+ request.headers.first {
+ $0.key.caseInsensitiveCompare("Authorization") == .orderedSame
+ }
+ )
+ let upload = try JSONDecoder().decode(
+ AnalyticsUploadRequest.self,
+ from: request.body
+ )
+ XCTAssertEqual(upload.events.count, 1)
+ XCTAssertEqual(upload.events.first?.surface, .keyboard)
+ XCTAssertEqual(upload.events.first?.eventType, .keyboardActivated)
+
+ let root = try XCTUnwrap(
+ JSONSerialization.jsonObject(with: request.body) as? [String: Any]
+ )
+ let eventObjects = try XCTUnwrap(root["events"] as? [[String: Any]])
+ let event = try XCTUnwrap(eventObjects.first)
+ XCTAssertFalse(event.keys.contains("properties"))
+ XCTAssertFalse(event.keys.contains("text"))
+ XCTAssertFalse(event.keys.contains("prompt"))
+ XCTAssertFalse(event.keys.contains("transcript"))
+ }
+
+ private func temporaryDatabaseURL() throws -> URL {
+ let directory = FileManager.default.temporaryDirectory
+ .appendingPathComponent("OSGKeyboardExtensionAnalyticsTests", isDirectory: true)
+ .appendingPathComponent(UUID().uuidString, isDirectory: true)
+ try FileManager.default.createDirectory(
+ at: directory,
+ withIntermediateDirectories: true
+ )
+ return directory.appendingPathComponent("analytics.sqlite3")
+ }
+}
+
+private struct ExtensionAnalyticsClock: AnalyticsWallClock {
+ func now() -> Date {
+ Date(timeIntervalSince1970: 1_700_000_000)
+ }
+}
+
+private struct ExtensionAnalyticsMonotonicClock: AnalyticsMonotonicClock {
+ func nowNanoseconds() -> UInt64 {
+ 0
+ }
+}
+
+private final class ExtensionAnalyticsUUIDGenerator:
+ AnalyticsUUIDGenerating,
+ @unchecked Sendable {
+ private let lock = NSLock()
+ private var value = 1
+
+ func makeUUID() -> UUID {
+ lock.withLock {
+ defer { value += 1 }
+ return UUID(
+ uuidString: String(
+ format: "00000000-0000-0000-0000-%012x",
+ value
+ )
+ )!
+ }
+ }
+}
+
+private struct ExtensionAnalyticsRandomGenerator: AnalyticsRandomGenerating {
+ func next(upperBound: UInt64) -> UInt64 {
+ 0
+ }
+}
+
+private actor ExtensionAnalyticsNetwork: AnalyticsNetworking {
+ private var captured: [AnalyticsHTTPRequest] = []
+
+ func send(_ request: AnalyticsHTTPRequest) async throws -> AnalyticsHTTPResponse {
+ captured.append(request)
+ let upload = try JSONDecoder().decode(
+ AnalyticsUploadRequest.self,
+ from: request.body
+ )
+ return AnalyticsHTTPResponse(
+ statusCode: 200,
+ headers: [:],
+ body: Data(
+ #"{"accepted":\#(upload.events.count),"replayed":0}"#.utf8
+ )
+ )
+ }
+
+ func requests() -> [AnalyticsHTTPRequest] {
+ captured
+ }
+}
diff --git a/OSGKeyboardExtTests/ManagedGatewayTests.swift b/OSGKeyboardExtTests/ManagedGatewayTests.swift
index 6c36d76..bbeee4f 100644
--- a/OSGKeyboardExtTests/ManagedGatewayTests.swift
+++ b/OSGKeyboardExtTests/ManagedGatewayTests.swift
@@ -209,6 +209,27 @@ final class ManagedGatewayTests: XCTestCase {
XCTAssertEqual(taskKinds, cases.map { $0.1.rawValue })
}
+ func testManagedClientSerializesOOBERequestPurpose() async throws {
+ let now = Date(timeIntervalSince1970: 3_750)
+ let store = MemoryGrantStore(credentials(accessToken: "access", receivedAt: now))
+ GatewayStub.shared.enqueue(200, Data(#"{"output_text":"ok"}"#.utf8))
+ let client = ManagedLLMClient(
+ capability: .polish,
+ taskKind: .dictationPolish,
+ requestPurpose: .oobe,
+ grants: makeCoordinator(store: store, now: { now }),
+ baseURL: baseURL,
+ session: stubSession()
+ )
+
+ _ = try await client.polish("input", systemPrompt: "context")
+
+ let request = try XCTUnwrap(GatewayStub.shared.requests().last)
+ let body = try jsonBody(request)
+ XCTAssertEqual(body["taskKind"] as? String, "dictation_polish")
+ XCTAssertEqual(body["requestPurpose"] as? String, "oobe")
+ }
+
func testManagedTaskKindWireValuesMatchServerContract() {
XCTAssertEqual(
ManagedGatewayTaskKind.allCases.map(\.rawValue),
diff --git a/OSGKeyboardShared/Core/Configuration/ConfigurationStore.swift b/OSGKeyboardShared/Core/Configuration/ConfigurationStore.swift
index 413b82e..d91c6fe 100644
--- a/OSGKeyboardShared/Core/Configuration/ConfigurationStore.swift
+++ b/OSGKeyboardShared/Core/Configuration/ConfigurationStore.swift
@@ -40,7 +40,10 @@ public protocol ConfigurationStore: Sendable {
/// Provider-specific ASR caches (e.g. Alibaba Fun-ASR vocabulary IDs).
var cloudASRPersistence: UserDefaults { get }
- func makeClient(taskKind: ManagedGatewayTaskKind?) -> LLMClient
+ func makeClient(
+ taskKind: ManagedGatewayTaskKind?,
+ requestPurpose: ManagedGatewayRequestPurpose?
+ ) -> LLMClient
}
public extension ConfigurationStore {
@@ -48,6 +51,10 @@ public extension ConfigurationStore {
var credentialSource: CredentialSource { .byok }
func makeClient() -> LLMClient {
- makeClient(taskKind: nil)
+ makeClient(taskKind: nil, requestPurpose: nil)
+ }
+
+ func makeClient(taskKind: ManagedGatewayTaskKind?) -> LLMClient {
+ makeClient(taskKind: taskKind, requestPurpose: nil)
}
}
diff --git a/OSGKeyboardShared/Core/Configuration/LiveConfigurationStore.swift b/OSGKeyboardShared/Core/Configuration/LiveConfigurationStore.swift
index f2b004b..258a095 100644
--- a/OSGKeyboardShared/Core/Configuration/LiveConfigurationStore.swift
+++ b/OSGKeyboardShared/Core/Configuration/LiveConfigurationStore.swift
@@ -124,11 +124,15 @@ public struct LiveConfigurationStore: ConfigurationStore, @unchecked Sendable {
public var detectedAppContext: (context: AppContext, observedAt: Date)? { snapshot.detectedAppContext }
public var cloudASRPersistence: UserDefaults { snapshot.cloudASRPersistence }
- public func makeClient(taskKind: ManagedGatewayTaskKind?) -> LLMClient {
+ public func makeClient(
+ taskKind: ManagedGatewayTaskKind?,
+ requestPurpose: ManagedGatewayRequestPurpose?
+ ) -> LLMClient {
if credentialSource == .managed {
return ManagedLLMClient(
capability: .polish,
taskKind: taskKind,
+ requestPurpose: requestPurpose,
grants: GatewayGrantCoordinator()
)
}
diff --git a/OSGKeyboardShared/Features/Analytics/AnalyticsClient.swift b/OSGKeyboardShared/Features/Analytics/AnalyticsClient.swift
new file mode 100644
index 0000000..59e0860
--- /dev/null
+++ b/OSGKeyboardShared/Features/Analytics/AnalyticsClient.swift
@@ -0,0 +1,404 @@
+// AnalyticsClient.swift
+// OSGKeyboard · Shared
+//
+// Synchronous, type-safe fire-and-forget API. Every asynchronous task owns only
+// Sendable dependencies and analytics failures never escape into feature code.
+
+import Foundation
+
+public protocol AnalyticsClient: Sendable {
+ func recordSessionActivity()
+ func recordKeyboardActivated()
+ func recordPurchaseViewed()
+ func recordPurchaseStarted()
+ func recordPurchaseCancelled()
+ func recordReferralShared()
+ func recordInviteOpened(
+ acquisitionChannel: AnalyticsAcquisitionChannel,
+ surface: AnalyticsSurface
+ )
+ func startAIFeature(
+ _ feature: AnalyticsFeature,
+ executionMode: AnalyticsExecutionMode
+ ) -> any AnalyticsAIOperation
+}
+
+public extension AnalyticsClient {
+ func recordInviteOpened(
+ acquisitionChannel: AnalyticsAcquisitionChannel = .referral
+ ) {
+ recordInviteOpened(
+ acquisitionChannel: acquisitionChannel,
+ surface: .inviteWeb
+ )
+ }
+}
+
+public protocol AnalyticsAIOperation: Sendable {
+ func succeed()
+ func fail(category: AnalyticsFailureCategory)
+ func cancel()
+}
+
+public final class LiveAnalyticsClient: AnalyticsClient, Sendable {
+ private let repository: AnalyticsRepository
+ private let context: AnalyticsBootstrapContext
+ private let monotonicClock: any AnalyticsMonotonicClock
+ private let trigger: any AnalyticsUploadTriggering
+
+ public init(
+ repository: AnalyticsRepository,
+ context: AnalyticsBootstrapContext,
+ monotonicClock: any AnalyticsMonotonicClock = SystemAnalyticsMonotonicClock(),
+ trigger: any AnalyticsUploadTriggering = NoopAnalyticsUploadTrigger()
+ ) {
+ self.repository = repository
+ self.context = context
+ self.monotonicClock = monotonicClock
+ self.trigger = trigger
+ }
+
+ public func recordSessionActivity() {
+ Task {
+ await repository.recordSessionIfNeeded(context: context)
+ await trigger.requestUpload()
+ }
+ }
+
+ public func recordKeyboardActivated() {
+ enqueue(eventType: .keyboardActivated)
+ }
+
+ public func recordPurchaseViewed() {
+ enqueue(eventType: .purchaseViewed)
+ }
+
+ public func recordPurchaseStarted() {
+ enqueue(eventType: .purchaseStarted)
+ }
+
+ public func recordPurchaseCancelled() {
+ enqueue(
+ eventType: .purchaseCancelled,
+ dimensions: AnalyticsEventDimensions(failureCategory: .cancelled)
+ )
+ }
+
+ public func recordReferralShared() {
+ enqueue(eventType: .referralShared)
+ }
+
+ public func recordInviteOpened(
+ acquisitionChannel: AnalyticsAcquisitionChannel,
+ surface: AnalyticsSurface
+ ) {
+ enqueue(
+ eventType: .inviteOpened,
+ surfaceOverride: surface,
+ dimensions: AnalyticsEventDimensions(
+ acquisitionChannel: acquisitionChannel
+ )
+ )
+ }
+
+ public func startAIFeature(
+ _ feature: AnalyticsFeature,
+ executionMode: AnalyticsExecutionMode
+ ) -> any AnalyticsAIOperation {
+ let startNanoseconds = monotonicClock.nowNanoseconds()
+ let dimensions = AnalyticsEventDimensions(
+ feature: feature,
+ executionMode: executionMode
+ )
+ let startedTask = enqueue(
+ eventType: .aiFeatureStarted,
+ dimensions: dimensions
+ )
+ return LiveAnalyticsAIOperation(
+ repository: repository,
+ context: context,
+ feature: feature,
+ executionMode: executionMode,
+ startNanoseconds: startNanoseconds,
+ startedTask: startedTask,
+ monotonicClock: monotonicClock,
+ trigger: trigger
+ )
+ }
+
+ @discardableResult
+ private func enqueue(
+ eventType: AnalyticsEventType,
+ surfaceOverride: AnalyticsSurface? = nil,
+ dimensions: AnalyticsEventDimensions = .none
+ ) -> Task {
+ let recordTask = Task {
+ await repository.record(
+ eventType: eventType,
+ context: context,
+ surfaceOverride: surfaceOverride,
+ dimensions: dimensions
+ )
+ }
+ Task {
+ await recordTask.value
+ await trigger.requestUpload()
+ }
+ return recordTask
+ }
+}
+
+public final class LiveAnalyticsAIOperation: AnalyticsAIOperation, @unchecked Sendable {
+ private let repository: AnalyticsRepository
+ private let context: AnalyticsBootstrapContext
+ private let feature: AnalyticsFeature
+ private let executionMode: AnalyticsExecutionMode
+ private let startNanoseconds: UInt64
+ private let startedTask: Task
+ private let monotonicClock: any AnalyticsMonotonicClock
+ private let trigger: any AnalyticsUploadTriggering
+ private let terminalLock = NSLock()
+ private var reachedTerminalState = false
+
+ init(
+ repository: AnalyticsRepository,
+ context: AnalyticsBootstrapContext,
+ feature: AnalyticsFeature,
+ executionMode: AnalyticsExecutionMode,
+ startNanoseconds: UInt64,
+ startedTask: Task,
+ monotonicClock: any AnalyticsMonotonicClock,
+ trigger: any AnalyticsUploadTriggering
+ ) {
+ self.repository = repository
+ self.context = context
+ self.feature = feature
+ self.executionMode = executionMode
+ self.startNanoseconds = startNanoseconds
+ self.startedTask = startedTask
+ self.monotonicClock = monotonicClock
+ self.trigger = trigger
+ }
+
+ public func succeed() {
+ finish(eventType: .aiFeatureSucceeded, failureCategory: nil)
+ }
+
+ public func fail(category: AnalyticsFailureCategory) {
+ finish(eventType: .aiFeatureFailed, failureCategory: category)
+ }
+
+ public func cancel() {
+ fail(category: .cancelled)
+ }
+
+ private func finish(
+ eventType: AnalyticsEventType,
+ failureCategory: AnalyticsFailureCategory?
+ ) {
+ terminalLock.lock()
+ guard !reachedTerminalState else {
+ terminalLock.unlock()
+ return
+ }
+ reachedTerminalState = true
+ terminalLock.unlock()
+
+ let endNanoseconds = monotonicClock.nowNanoseconds()
+ let elapsed = endNanoseconds >= startNanoseconds
+ ? endNanoseconds - startNanoseconds
+ : 0
+ let dimensions = AnalyticsEventDimensions(
+ feature: feature,
+ executionMode: executionMode,
+ failureCategory: failureCategory,
+ durationBucket: AnalyticsDurationBucket(elapsedNanoseconds: elapsed)
+ )
+ Task {
+ // This explicit dependency guarantees STARTED reaches the repository
+ // before any terminal event, even when completion is immediate.
+ await startedTask.value
+ await repository.record(
+ eventType: eventType,
+ context: context,
+ dimensions: dimensions
+ )
+ await trigger.requestUpload()
+ }
+ }
+}
+
+public struct NoopAnalyticsAIOperation: AnalyticsAIOperation {
+ public init() {}
+
+ public func succeed() {}
+ public func fail(category: AnalyticsFailureCategory) {}
+ public func cancel() {}
+}
+
+public struct NoopAnalyticsClient: AnalyticsClient {
+ public init() {}
+
+ public func recordSessionActivity() {}
+ public func recordKeyboardActivated() {}
+ public func recordPurchaseViewed() {}
+ public func recordPurchaseStarted() {}
+ public func recordPurchaseCancelled() {}
+ public func recordReferralShared() {}
+
+ public func recordInviteOpened(
+ acquisitionChannel: AnalyticsAcquisitionChannel,
+ surface: AnalyticsSurface
+ ) {}
+
+ public func startAIFeature(
+ _ feature: AnalyticsFeature,
+ executionMode: AnalyticsExecutionMode
+ ) -> any AnalyticsAIOperation {
+ NoopAnalyticsAIOperation()
+ }
+}
+
+public typealias AnalyticsAISpan = any AnalyticsAIOperation
+
+public struct AnalyticsRuntime: Sendable {
+ public let repository: AnalyticsRepository
+ public let client: any AnalyticsClient
+ public let uploadCoordinator: AnalyticsUploadCoordinator
+ public let context: AnalyticsBootstrapContext
+
+ private init(
+ surface: AnalyticsSurface,
+ environment: AnalyticsEnvironment,
+ repositoryConfiguration: AnalyticsRepositoryConfiguration,
+ uploadConfiguration: AnalyticsUploadConfiguration,
+ network: any AnalyticsNetworking,
+ bearerProvider: (any AnalyticsBearerProviding)?,
+ wallClock: any AnalyticsWallClock,
+ monotonicClock: any AnalyticsMonotonicClock,
+ uuidGenerator: any AnalyticsUUIDGenerating,
+ random: any AnalyticsRandomGenerating,
+ trigger: any AnalyticsUploadTriggering,
+ logger: any AnalyticsLogging
+ ) {
+ let context = AnalyticsBootstrapContext(
+ surface: surface,
+ environment: environment
+ )
+ let repository = AnalyticsRepository(
+ configuration: repositoryConfiguration,
+ clock: wallClock,
+ uuidGenerator: uuidGenerator
+ )
+ self.context = context
+ self.repository = repository
+ client = LiveAnalyticsClient(
+ repository: repository,
+ context: context,
+ monotonicClock: monotonicClock,
+ trigger: trigger
+ )
+ uploadCoordinator = AnalyticsUploadCoordinator(
+ repository: repository,
+ configuration: uploadConfiguration,
+ network: network,
+ bearerProvider: bearerProvider,
+ clock: wallClock,
+ uuidGenerator: uuidGenerator,
+ random: random,
+ logger: logger
+ )
+ }
+
+ /// Main-app runtime. A bearer provider may be supplied by host-only account
+ /// code without making the shared framework depend on that code.
+ public static func mainApp(
+ environment: AnalyticsEnvironment,
+ repositoryConfiguration: AnalyticsRepositoryConfiguration = .appGroupDefault(),
+ uploadConfiguration: AnalyticsUploadConfiguration,
+ network: any AnalyticsNetworking = URLSessionAnalyticsNetwork(),
+ bearerProvider: (any AnalyticsBearerProviding)? = nil,
+ wallClock: any AnalyticsWallClock = SystemAnalyticsWallClock(),
+ monotonicClock: any AnalyticsMonotonicClock = SystemAnalyticsMonotonicClock(),
+ uuidGenerator: any AnalyticsUUIDGenerating = SystemAnalyticsUUIDGenerator(),
+ random: any AnalyticsRandomGenerating = SystemAnalyticsRandomGenerator(),
+ trigger: any AnalyticsUploadTriggering = NoopAnalyticsUploadTrigger(),
+ logger: any AnalyticsLogging = NoopAnalyticsLogger()
+ ) -> Self {
+ Self(
+ surface: .app,
+ environment: environment,
+ repositoryConfiguration: repositoryConfiguration,
+ uploadConfiguration: uploadConfiguration,
+ network: network,
+ bearerProvider: bearerProvider,
+ wallClock: wallClock,
+ monotonicClock: monotonicClock,
+ uuidGenerator: uuidGenerator,
+ random: random,
+ trigger: trigger,
+ logger: logger
+ )
+ }
+
+ /// Keyboard-extension runtime. This factory intentionally has no bearer
+ /// parameter, so extension uploads are anonymous by construction.
+ public static func keyboardExtension(
+ environment: AnalyticsEnvironment,
+ repositoryConfiguration: AnalyticsRepositoryConfiguration = .appGroupDefault(),
+ uploadConfiguration: AnalyticsUploadConfiguration,
+ network: any AnalyticsNetworking = URLSessionAnalyticsNetwork(),
+ wallClock: any AnalyticsWallClock = SystemAnalyticsWallClock(),
+ monotonicClock: any AnalyticsMonotonicClock = SystemAnalyticsMonotonicClock(),
+ uuidGenerator: any AnalyticsUUIDGenerating = SystemAnalyticsUUIDGenerator(),
+ random: any AnalyticsRandomGenerating = SystemAnalyticsRandomGenerator(),
+ trigger: any AnalyticsUploadTriggering = NoopAnalyticsUploadTrigger(),
+ logger: any AnalyticsLogging = NoopAnalyticsLogger()
+ ) -> Self {
+ Self(
+ surface: .keyboard,
+ environment: environment,
+ repositoryConfiguration: repositoryConfiguration,
+ uploadConfiguration: uploadConfiguration,
+ network: network,
+ bearerProvider: nil,
+ wallClock: wallClock,
+ monotonicClock: monotonicClock,
+ uuidGenerator: uuidGenerator,
+ random: random,
+ trigger: trigger,
+ logger: logger
+ )
+ }
+
+ public func setEnabled(_ enabled: Bool) async {
+ await repository.setEnabled(enabled)
+ }
+
+ /// Host-only explicit initialization point. Call after processing the
+ /// cold-start URL so FIRST_OPEN receives the final acquisition channel.
+ public func prepare(
+ firstOpenAcquisitionChannel: AnalyticsAcquisitionChannel = .unknown
+ ) async {
+ await repository.prepare(
+ using: context,
+ firstOpenAcquisitionChannel: firstOpenAcquisitionChannel
+ )
+ }
+
+ public func isEnabled() async -> Bool {
+ await repository.isEnabled()
+ }
+
+ public func observeAccount(
+ stableIdentifier: String
+ ) async -> AnalyticsAccountObservation {
+ await repository.observeAccount(
+ stableIdentifier: stableIdentifier
+ )
+ }
+
+ public func handleAccountDeletion() async {
+ await repository.handleAccountDeletion()
+ }
+}
diff --git a/OSGKeyboardShared/Features/Analytics/AnalyticsDependencies.swift b/OSGKeyboardShared/Features/Analytics/AnalyticsDependencies.swift
new file mode 100644
index 0000000..7255a46
--- /dev/null
+++ b/OSGKeyboardShared/Features/Analytics/AnalyticsDependencies.swift
@@ -0,0 +1,227 @@
+// AnalyticsDependencies.swift
+// OSGKeyboard · Shared
+//
+// Injectable system boundaries used by both the host app and keyboard extension.
+
+import Foundation
+
+public protocol AnalyticsWallClock: Sendable {
+ func now() -> Date
+}
+
+public protocol AnalyticsMonotonicClock: Sendable {
+ func nowNanoseconds() -> UInt64
+}
+
+public protocol AnalyticsUUIDGenerating: Sendable {
+ func makeUUID() -> UUID
+}
+
+public protocol AnalyticsRandomGenerating: Sendable {
+ /// Returns a value in the closed range 0...upperBound.
+ func next(upperBound: UInt64) -> UInt64
+}
+
+public struct SystemAnalyticsWallClock: AnalyticsWallClock {
+ public init() {}
+
+ public func now() -> Date {
+ Date()
+ }
+}
+
+public struct SystemAnalyticsMonotonicClock: AnalyticsMonotonicClock {
+ public init() {}
+
+ public func nowNanoseconds() -> UInt64 {
+ DispatchTime.now().uptimeNanoseconds
+ }
+}
+
+public struct SystemAnalyticsUUIDGenerator: AnalyticsUUIDGenerating {
+ public init() {}
+
+ public func makeUUID() -> UUID {
+ UUID()
+ }
+}
+
+public final class SystemAnalyticsRandomGenerator: AnalyticsRandomGenerating, @unchecked Sendable {
+ private let lock = NSLock()
+ private var generator = SystemRandomNumberGenerator()
+
+ public init() {}
+
+ public func next(upperBound: UInt64) -> UInt64 {
+ guard upperBound > 0 else { return 0 }
+ lock.lock()
+ defer { lock.unlock() }
+ return UInt64.random(in: 0...upperBound, using: &generator)
+ }
+}
+
+public struct AnalyticsHTTPRequest: Sendable {
+ public let url: URL
+ public let headers: [String: String]
+ public let body: Data
+
+ public init(url: URL, headers: [String: String], body: Data) {
+ self.url = url
+ self.headers = headers
+ self.body = body
+ }
+}
+
+public struct AnalyticsHTTPResponse: Sendable {
+ public let statusCode: Int
+ public let headers: [String: String]
+ public let body: Data
+
+ public init(statusCode: Int, headers: [String: String], body: Data) {
+ self.statusCode = statusCode
+ self.headers = headers
+ self.body = body
+ }
+
+ func header(named name: String) -> String? {
+ headers.first { $0.key.caseInsensitiveCompare(name) == .orderedSame }?.value
+ }
+}
+
+public protocol AnalyticsNetworking: Sendable {
+ func send(_ request: AnalyticsHTTPRequest) async throws -> AnalyticsHTTPResponse
+}
+
+public protocol AnalyticsBearerProviding: Sendable {
+ func bearerToken() async throws -> String?
+ func refreshBearerToken(
+ afterUnauthorizedAccessToken failedToken: String?
+ ) async throws -> String?
+}
+
+public protocol AnalyticsUploadTriggering: Sendable {
+ func requestUpload() async
+}
+
+public struct NoopAnalyticsUploadTrigger: AnalyticsUploadTriggering {
+ public init() {}
+
+ public func requestUpload() async {}
+}
+
+public enum AnalyticsUploadErrorCategory: String, Sendable {
+ case network
+ case timeout
+ case authentication
+ case rateLimited
+ case server
+ case client
+ case decoding
+ case countMismatch
+ case storage
+}
+
+public struct AnalyticsUploadLogEntry: Sendable {
+ public enum Outcome: String, Sendable {
+ case uploaded
+ case retryScheduled
+ case quarantined
+ case skipped
+ }
+
+ public let outcome: Outcome
+ public let eventCount: Int
+ public let statusCode: Int?
+ public let attempt: Int
+ public let errorCategory: AnalyticsUploadErrorCategory?
+
+ public init(
+ outcome: Outcome,
+ eventCount: Int,
+ statusCode: Int? = nil,
+ attempt: Int = 0,
+ errorCategory: AnalyticsUploadErrorCategory? = nil
+ ) {
+ self.outcome = outcome
+ self.eventCount = eventCount
+ self.statusCode = statusCode
+ self.attempt = attempt
+ self.errorCategory = errorCategory
+ }
+}
+
+public protocol AnalyticsLogging: Sendable {
+ func log(_ entry: AnalyticsUploadLogEntry)
+}
+
+public struct NoopAnalyticsLogger: AnalyticsLogging {
+ public init() {}
+
+ public func log(_ entry: AnalyticsUploadLogEntry) {}
+}
+
+public struct AnalyticsRepositoryConfiguration: Sendable {
+ public static let defaultDatabaseFilename = "analytics.sqlite3"
+
+ public let databaseURL: URL?
+ public let maximumEventCount: Int
+ public let maximumStoredBytes: Int
+ public let eventRetention: TimeInterval
+ public let busyTimeoutMilliseconds: Int32
+
+ public init(
+ databaseURL: URL?,
+ maximumEventCount: Int = 10_000,
+ maximumStoredBytes: Int = 5 * 1_024 * 1_024,
+ eventRetention: TimeInterval = 34 * 24 * 60 * 60,
+ busyTimeoutMilliseconds: Int32 = 2_000
+ ) {
+ self.databaseURL = databaseURL
+ self.maximumEventCount = max(1, maximumEventCount)
+ self.maximumStoredBytes = max(1_024, maximumStoredBytes)
+ self.eventRetention = max(60, eventRetention)
+ self.busyTimeoutMilliseconds = max(0, busyTimeoutMilliseconds)
+ }
+
+ public static func appGroupDefault(
+ appGroupIdentifier: String = AppGroup.identifier
+ ) -> Self {
+ let container = FileManager.default.containerURL(
+ forSecurityApplicationGroupIdentifier: appGroupIdentifier
+ )
+ let directory = container?.appendingPathComponent(
+ "Library/Application Support/Analytics",
+ isDirectory: true
+ )
+ return Self(
+ databaseURL: directory?.appendingPathComponent(defaultDatabaseFilename)
+ )
+ }
+}
+
+public struct AnalyticsUploadConfiguration: Sendable {
+ public let endpoint: URL
+ public let maximumBatchCount: Int
+ public let maximumBodyBytes: Int
+ public let globalLeaseDuration: TimeInterval
+ public let eventLeaseDuration: TimeInterval
+ public let maximumBackoff: TimeInterval
+
+ public init(
+ endpoint: URL,
+ maximumBatchCount: Int = 50,
+ maximumBodyBytes: Int = 60 * 1_024,
+ globalLeaseDuration: TimeInterval = 2 * 60,
+ eventLeaseDuration: TimeInterval = 5 * 60,
+ maximumBackoff: TimeInterval = 6 * 60 * 60
+ ) {
+ self.endpoint = endpoint
+ self.maximumBatchCount = min(50, max(1, maximumBatchCount))
+ self.maximumBodyBytes = min(60 * 1_024, max(1_024, maximumBodyBytes))
+ // Both leases outlive the default 30-second transport timeout. The
+ // coordinator also renews them immediately before every request.
+ self.globalLeaseDuration = max(60, globalLeaseDuration)
+ self.eventLeaseDuration = max(60, eventLeaseDuration)
+ self.maximumBackoff = min(6 * 60 * 60, max(60, maximumBackoff))
+ }
+}
diff --git a/OSGKeyboardShared/Features/Analytics/AnalyticsModels.swift b/OSGKeyboardShared/Features/Analytics/AnalyticsModels.swift
new file mode 100644
index 0000000..e58ff92
--- /dev/null
+++ b/OSGKeyboardShared/Features/Analytics/AnalyticsModels.swift
@@ -0,0 +1,446 @@
+// AnalyticsModels.swift
+// OSGKeyboard · Shared
+//
+// Privacy-preserving analytics wire contract. There is intentionally no
+// free-form properties dictionary or user-provided text in this model.
+
+import Foundation
+
+public enum AnalyticsEventType: String, Codable, CaseIterable, Sendable {
+ case firstOpen = "FIRST_OPEN"
+ case sessionStarted = "SESSION_STARTED"
+ case keyboardActivated = "KEYBOARD_ACTIVATED"
+ case aiFeatureStarted = "AI_FEATURE_STARTED"
+ case aiFeatureSucceeded = "AI_FEATURE_SUCCEEDED"
+ case aiFeatureFailed = "AI_FEATURE_FAILED"
+ case purchaseViewed = "PURCHASE_VIEWED"
+ case purchaseStarted = "PURCHASE_STARTED"
+ case purchaseCancelled = "PURCHASE_CANCELLED"
+ case referralShared = "REFERRAL_SHARED"
+ case inviteOpened = "INVITE_OPENED"
+}
+
+public enum AnalyticsSurface: String, Codable, CaseIterable, Sendable {
+ case app = "APP"
+ case keyboard = "KEYBOARD"
+ case inviteWeb = "INVITE_WEB"
+}
+
+public enum AnalyticsAcquisitionChannel: String, Codable, CaseIterable, Sendable {
+ case appStoreOrganic = "APP_STORE_ORGANIC"
+ case referral = "REFERRAL"
+ case socialContent = "SOCIAL_CONTENT"
+ case unknown = "UNKNOWN"
+}
+
+public enum AnalyticsFeature: String, Codable, CaseIterable, Sendable {
+ case transcription = "TRANSCRIPTION"
+ case polish = "POLISH"
+ case aiAssistant = "AI_ASSISTANT"
+ case agent = "AGENT"
+ case hotword = "HOTWORD"
+ case other = "OTHER"
+}
+
+public enum AnalyticsExecutionMode: String, Codable, CaseIterable, Sendable {
+ case managed = "MANAGED"
+ case local = "LOCAL"
+ case byok = "BYOK"
+}
+
+public enum AnalyticsFailureCategory: String, Codable, CaseIterable, Sendable {
+ case network = "NETWORK"
+ case provider = "PROVIDER"
+ case timeout = "TIMEOUT"
+ case cancelled = "CANCELLED"
+ case insufficientCredits = "INSUFFICIENT_CREDITS"
+ case validation = "VALIDATION"
+ case unknown = "UNKNOWN"
+}
+
+public enum AnalyticsDurationBucket: String, Codable, CaseIterable, Sendable {
+ case lessThanOneSecond = "LT_1S"
+ case oneToThreeSeconds = "S1_TO_3"
+ case threeToTenSeconds = "S3_TO_10"
+ case tenToThirtySeconds = "S10_TO_30"
+ case thirtySecondsOrMore = "GTE_30S"
+
+ public init(elapsedNanoseconds: UInt64) {
+ switch elapsedNanoseconds {
+ case ..<1_000_000_000:
+ self = .lessThanOneSecond
+ case ..<3_000_000_000:
+ self = .oneToThreeSeconds
+ case ..<10_000_000_000:
+ self = .threeToTenSeconds
+ case ..<30_000_000_000:
+ self = .tenToThirtySeconds
+ default:
+ self = .thirtySecondsOrMore
+ }
+ }
+}
+
+public enum AnalyticsModelError: Error, Sendable {
+ case unknownField(String)
+ case invalidDimensions(AnalyticsEventType)
+ case invalidVersion
+ case invalidResponseCounts
+}
+
+public struct AnalyticsEvent: Codable, Equatable, Sendable {
+ public let installationId: UUID
+ public let clientEventId: UUID
+ public let eventType: AnalyticsEventType
+ public let occurredAt: Date
+ public let surface: AnalyticsSurface
+ public let appVersion: String
+ public let osVersion: String
+ public let acquisitionChannel: AnalyticsAcquisitionChannel?
+ public let feature: AnalyticsFeature?
+ public let executionMode: AnalyticsExecutionMode?
+ public let failureCategory: AnalyticsFailureCategory?
+ public let durationBucket: AnalyticsDurationBucket?
+
+ public init(
+ installationId: UUID,
+ clientEventId: UUID,
+ eventType: AnalyticsEventType,
+ occurredAt: Date,
+ surface: AnalyticsSurface,
+ appVersion: String,
+ osVersion: String,
+ acquisitionChannel: AnalyticsAcquisitionChannel? = nil,
+ feature: AnalyticsFeature? = nil,
+ executionMode: AnalyticsExecutionMode? = nil,
+ failureCategory: AnalyticsFailureCategory? = nil,
+ durationBucket: AnalyticsDurationBucket? = nil
+ ) throws {
+ guard AnalyticsEnvironment.isSafeVersion(appVersion),
+ AnalyticsEnvironment.isSafeVersion(osVersion) else {
+ throw AnalyticsModelError.invalidVersion
+ }
+
+ self.installationId = installationId
+ self.clientEventId = clientEventId
+ self.eventType = eventType
+ self.occurredAt = occurredAt
+ self.surface = surface
+ self.appVersion = appVersion
+ self.osVersion = osVersion
+ self.acquisitionChannel = acquisitionChannel
+ self.feature = feature
+ self.executionMode = executionMode
+ self.failureCategory = failureCategory
+ self.durationBucket = durationBucket
+
+ guard dimensionsAreAllowed else {
+ throw AnalyticsModelError.invalidDimensions(eventType)
+ }
+ }
+
+ private enum CodingKeys: String, CodingKey, CaseIterable {
+ case installationId
+ case clientEventId
+ case eventType
+ case occurredAt
+ case surface
+ case appVersion
+ case osVersion
+ case acquisitionChannel
+ case feature
+ case executionMode
+ case failureCategory
+ case durationBucket
+ }
+
+ public init(from decoder: Decoder) throws {
+ try AnalyticsCodableAllowlist.rejectUnknownKeys(
+ in: decoder,
+ allowed: Set(CodingKeys.allCases.map(\.rawValue))
+ )
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ let installationId = try container.decode(UUID.self, forKey: .installationId)
+ let clientEventId = try container.decode(UUID.self, forKey: .clientEventId)
+ let eventType = try container.decode(AnalyticsEventType.self, forKey: .eventType)
+ let occurredAtText = try container.decode(String.self, forKey: .occurredAt)
+ guard let occurredAt = AnalyticsWireDate.date(from: occurredAtText) else {
+ throw DecodingError.dataCorruptedError(
+ forKey: .occurredAt,
+ in: container,
+ debugDescription: "occurredAt must be a UTC ISO-8601 timestamp"
+ )
+ }
+ try self.init(
+ installationId: installationId,
+ clientEventId: clientEventId,
+ eventType: eventType,
+ occurredAt: occurredAt,
+ surface: try container.decode(AnalyticsSurface.self, forKey: .surface),
+ appVersion: try container.decode(String.self, forKey: .appVersion),
+ osVersion: try container.decode(String.self, forKey: .osVersion),
+ acquisitionChannel: try container.decodeIfPresent(
+ AnalyticsAcquisitionChannel.self,
+ forKey: .acquisitionChannel
+ ),
+ feature: try container.decodeIfPresent(AnalyticsFeature.self, forKey: .feature),
+ executionMode: try container.decodeIfPresent(
+ AnalyticsExecutionMode.self,
+ forKey: .executionMode
+ ),
+ failureCategory: try container.decodeIfPresent(
+ AnalyticsFailureCategory.self,
+ forKey: .failureCategory
+ ),
+ durationBucket: try container.decodeIfPresent(
+ AnalyticsDurationBucket.self,
+ forKey: .durationBucket
+ )
+ )
+ }
+
+ public func encode(to encoder: Encoder) throws {
+ guard dimensionsAreAllowed else {
+ throw AnalyticsModelError.invalidDimensions(eventType)
+ }
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ try container.encode(installationId, forKey: .installationId)
+ try container.encode(clientEventId, forKey: .clientEventId)
+ try container.encode(eventType, forKey: .eventType)
+ try container.encode(AnalyticsWireDate.string(from: occurredAt), forKey: .occurredAt)
+ try container.encode(surface, forKey: .surface)
+ try container.encode(appVersion, forKey: .appVersion)
+ try container.encode(osVersion, forKey: .osVersion)
+ try container.encodeIfPresent(acquisitionChannel, forKey: .acquisitionChannel)
+ try container.encodeIfPresent(feature, forKey: .feature)
+ try container.encodeIfPresent(executionMode, forKey: .executionMode)
+ try container.encodeIfPresent(failureCategory, forKey: .failureCategory)
+ try container.encodeIfPresent(durationBucket, forKey: .durationBucket)
+ }
+
+ private var dimensionsAreAllowed: Bool {
+ let present = DimensionSet(
+ acquisitionChannel: acquisitionChannel != nil,
+ feature: feature != nil,
+ executionMode: executionMode != nil,
+ failureCategory: failureCategory != nil,
+ durationBucket: durationBucket != nil
+ )
+ guard eventType.allowedDimensionSets.contains(present) else {
+ return false
+ }
+ if eventType == .purchaseCancelled {
+ return failureCategory == .cancelled
+ }
+ return true
+ }
+}
+
+public struct AnalyticsUploadRequest: Codable, Equatable, Sendable {
+ public let events: [AnalyticsEvent]
+
+ public init(events: [AnalyticsEvent]) {
+ self.events = events
+ }
+
+ private enum CodingKeys: String, CodingKey, CaseIterable {
+ case events
+ }
+
+ public init(from decoder: Decoder) throws {
+ try AnalyticsCodableAllowlist.rejectUnknownKeys(
+ in: decoder,
+ allowed: Set(CodingKeys.allCases.map(\.rawValue))
+ )
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ events = try container.decode([AnalyticsEvent].self, forKey: .events)
+ }
+}
+
+public struct AnalyticsUploadResponse: Codable, Equatable, Sendable {
+ public let accepted: Int
+ public let replayed: Int
+
+ public init(accepted: Int, replayed: Int) throws {
+ guard accepted >= 0, replayed >= 0 else {
+ throw AnalyticsModelError.invalidResponseCounts
+ }
+ self.accepted = accepted
+ self.replayed = replayed
+ }
+
+ private enum CodingKeys: String, CodingKey, CaseIterable {
+ case accepted
+ case replayed
+ }
+
+ public init(from decoder: Decoder) throws {
+ try AnalyticsCodableAllowlist.rejectUnknownKeys(
+ in: decoder,
+ allowed: Set(CodingKeys.allCases.map(\.rawValue))
+ )
+ let container = try decoder.container(keyedBy: CodingKeys.self)
+ try self.init(
+ accepted: container.decode(Int.self, forKey: .accepted),
+ replayed: container.decode(Int.self, forKey: .replayed)
+ )
+ }
+}
+
+public struct AnalyticsEnvironment: Equatable, Sendable {
+ public let appVersion: String
+ public let osVersion: String
+
+ public init(appVersion: String, osVersion: String) {
+ self.appVersion = Self.sanitizedVersion(appVersion)
+ self.osVersion = Self.sanitizedVersion(osVersion)
+ }
+
+ static func isSafeVersion(_ value: String) -> Bool {
+ !value.isEmpty
+ && value.utf8.count <= 32
+ && value.unicodeScalars.allSatisfy {
+ CharacterSet(charactersIn: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.-_")
+ .contains($0)
+ }
+ }
+
+ private static func sanitizedVersion(_ value: String) -> String {
+ let allowed = CharacterSet(
+ charactersIn: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.-_"
+ )
+ let filtered = String(value.unicodeScalars.filter(allowed.contains).prefix(32))
+ return filtered.isEmpty ? "unknown" : filtered
+ }
+}
+
+private struct DimensionSet: Hashable {
+ let acquisitionChannel: Bool
+ let feature: Bool
+ let executionMode: Bool
+ let failureCategory: Bool
+ let durationBucket: Bool
+
+ static let none = Self(
+ acquisitionChannel: false,
+ feature: false,
+ executionMode: false,
+ failureCategory: false,
+ durationBucket: false
+ )
+}
+
+private extension AnalyticsEventType {
+ var allowedDimensionSets: Set {
+ switch self {
+ case .firstOpen, .inviteOpened:
+ return [
+ DimensionSet(
+ acquisitionChannel: true,
+ feature: false,
+ executionMode: false,
+ failureCategory: false,
+ durationBucket: false
+ )
+ ]
+ case .aiFeatureStarted:
+ return [
+ DimensionSet(
+ acquisitionChannel: false,
+ feature: true,
+ executionMode: true,
+ failureCategory: false,
+ durationBucket: false
+ )
+ ]
+ case .aiFeatureSucceeded:
+ return [
+ DimensionSet(
+ acquisitionChannel: false,
+ feature: true,
+ executionMode: true,
+ failureCategory: false,
+ durationBucket: true
+ )
+ ]
+ case .aiFeatureFailed:
+ return [
+ DimensionSet(
+ acquisitionChannel: false,
+ feature: true,
+ executionMode: true,
+ failureCategory: true,
+ durationBucket: true
+ )
+ ]
+ case .sessionStarted,
+ .keyboardActivated,
+ .purchaseViewed,
+ .purchaseStarted,
+ .referralShared:
+ return [.none]
+ case .purchaseCancelled:
+ return [
+ DimensionSet(
+ acquisitionChannel: false,
+ feature: false,
+ executionMode: false,
+ failureCategory: true,
+ durationBucket: false
+ )
+ ]
+ }
+ }
+}
+
+enum AnalyticsCanonicalJSON {
+ static func encode(_ value: T) throws -> Data {
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+ return try encoder.encode(value)
+ }
+}
+
+enum AnalyticsWireDate {
+ static func string(from date: Date) -> String {
+ formatter.string(from: date)
+ }
+
+ static func date(from value: String) -> Date? {
+ formatter.date(from: value)
+ }
+
+ private static var formatter: ISO8601DateFormatter {
+ let formatter = ISO8601DateFormatter()
+ formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+ formatter.timeZone = TimeZone(secondsFromGMT: 0)
+ return formatter
+ }
+}
+
+private enum AnalyticsCodableAllowlist {
+ static func rejectUnknownKeys(
+ in decoder: Decoder,
+ allowed: Set
+ ) throws {
+ let container = try decoder.container(keyedBy: AnyCodingKey.self)
+ if let unknown = container.allKeys.first(where: { !allowed.contains($0.stringValue) }) {
+ throw AnalyticsModelError.unknownField(unknown.stringValue)
+ }
+ }
+}
+
+private struct AnyCodingKey: CodingKey {
+ let stringValue: String
+ let intValue: Int?
+
+ init?(stringValue: String) {
+ self.stringValue = stringValue
+ intValue = nil
+ }
+
+ init?(intValue: Int) {
+ stringValue = String(intValue)
+ self.intValue = intValue
+ }
+}
diff --git a/OSGKeyboardShared/Features/Analytics/AnalyticsRepository.swift b/OSGKeyboardShared/Features/Analytics/AnalyticsRepository.swift
new file mode 100644
index 0000000..1c9b1b5
--- /dev/null
+++ b/OSGKeyboardShared/Features/Analytics/AnalyticsRepository.swift
@@ -0,0 +1,1397 @@
+// AnalyticsRepository.swift
+// OSGKeyboard · Shared
+//
+// Cross-process SQLite queue. The actor is the in-process isolation boundary;
+// WAL and BEGIN IMMEDIATE provide the corresponding cross-process boundary.
+
+import CryptoKit
+import Foundation
+import SQLite3
+
+public struct AnalyticsBootstrapContext: Sendable {
+ public let surface: AnalyticsSurface
+ public let environment: AnalyticsEnvironment
+
+ public init(
+ surface: AnalyticsSurface,
+ environment: AnalyticsEnvironment
+ ) {
+ self.surface = surface
+ self.environment = environment
+ }
+}
+
+public enum AnalyticsAccountObservation: Sendable {
+ case firstAccount
+ case unchanged
+ case switchedAccount
+ case analyticsDisabled
+ case unavailable
+}
+
+public struct AnalyticsPendingEventDiagnostic: Sendable {
+ public let rowID: Int64
+ public let eventType: AnalyticsEventType?
+ public let attemptCount: Int
+ public let nextAttemptAt: Date
+ public let payloadSize: Int
+}
+
+public struct AnalyticsQuarantinedEventDiagnostic: Sendable {
+ public let rowID: Int64
+ public let eventType: AnalyticsEventType?
+ public let attemptCount: Int
+ public let reason: String
+ public let payloadSize: Int
+}
+
+public struct AnalyticsRepositoryDebugSnapshot: Sendable {
+ public let isAvailable: Bool
+ public let enabled: Bool
+ public let installationID: UUID?
+ public let firstOpenRecorded: Bool
+ public let pendingEvents: [AnalyticsPendingEventDiagnostic]
+ public let quarantinedEvents: [AnalyticsQuarantinedEventDiagnostic]
+}
+
+struct AnalyticsEventDimensions: Sendable {
+ var acquisitionChannel: AnalyticsAcquisitionChannel?
+ var feature: AnalyticsFeature?
+ var executionMode: AnalyticsExecutionMode?
+ var failureCategory: AnalyticsFailureCategory?
+ var durationBucket: AnalyticsDurationBucket?
+
+ static let none = Self()
+}
+
+struct AnalyticsLeasedEvent: Sendable {
+ let rowID: Int64
+ let payload: Data
+ let attemptCount: Int
+}
+
+struct AnalyticsLeasedBatch: Sendable {
+ let leaseID: String
+ let events: [AnalyticsLeasedEvent]
+ let body: Data
+}
+
+public actor AnalyticsRepository {
+ private enum MetadataKey {
+ static let enabled = "enabled"
+ static let installationID = "installationId"
+ static let firstOpenRecorded = "firstOpenRecorded"
+ static let accountFingerprint = "accountFingerprint"
+ static let uploadLeaseOwner = "uploadLeaseOwner"
+ static let uploadLeaseExpiresAt = "uploadLeaseExpiresAt"
+ static let expiredDropCount = "diagnostic.expiredDropCount"
+ static let capacityDropCount = "diagnostic.capacityDropCount"
+
+ static func lastSession(_ surface: AnalyticsSurface) -> String {
+ "lastSession.\(surface.rawValue)"
+ }
+ }
+
+ private let configuration: AnalyticsRepositoryConfiguration
+ private let clock: any AnalyticsWallClock
+ private let uuidGenerator: any AnalyticsUUIDGenerating
+ private var database: SQLiteDatabase?
+
+ public init(
+ configuration: AnalyticsRepositoryConfiguration = .appGroupDefault(),
+ clock: any AnalyticsWallClock = SystemAnalyticsWallClock(),
+ uuidGenerator: any AnalyticsUUIDGenerating = SystemAnalyticsUUIDGenerator()
+ ) {
+ self.configuration = configuration
+ self.clock = clock
+ self.uuidGenerator = uuidGenerator
+ }
+
+ /// The host calls this only after cold-start attribution has been resolved.
+ /// Installation identity, FIRST_OPEN and its marker share one transaction.
+ public func prepare(
+ using context: AnalyticsBootstrapContext,
+ firstOpenAcquisitionChannel: AnalyticsAcquisitionChannel
+ ) {
+ guard context.surface == .app else { return }
+ guard let database = openDatabaseIfNeeded() else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ _ = try ensureEnabled(database)
+ guard try isEnabled(database) else { return }
+ let installationID = try ensureInstallation(database)
+ guard try metadata(
+ for: MetadataKey.firstOpenRecorded,
+ database: database
+ ) == nil else {
+ return
+ }
+ let event = try AnalyticsEvent(
+ installationId: installationID,
+ clientEventId: uuidGenerator.makeUUID(),
+ eventType: .firstOpen,
+ occurredAt: clock.now(),
+ surface: .app,
+ appVersion: context.environment.appVersion,
+ osVersion: context.environment.osVersion,
+ acquisitionChannel: firstOpenAcquisitionChannel
+ )
+ try insert(event, database: database)
+ try setMetadata(
+ "1",
+ for: MetadataKey.firstOpenRecorded,
+ database: database
+ )
+ try enforceStoragePolicy(database)
+ }
+ }
+ }
+
+ public func isEnabled() -> Bool {
+ guard let database = openDatabaseIfNeeded() else { return true }
+ do {
+ return try database.immediateTransaction {
+ try ensureEnabled(database)
+ }
+ } catch {
+ return true
+ }
+ }
+
+ /// Read-only diagnostics for tests and support tooling. Event payload content
+ /// is deliberately excluded from this public snapshot.
+ public func debugSnapshot() -> AnalyticsRepositoryDebugSnapshot {
+ guard let database = openDatabaseIfNeeded() else {
+ return Self.unavailableDebugSnapshot
+ }
+ do {
+ return try database.immediateTransaction {
+ let enabled = try ensureEnabled(database)
+ let installationID = try metadata(
+ for: MetadataKey.installationID,
+ database: database
+ ).flatMap(UUID.init(uuidString:))
+ let firstOpenRecorded = try metadata(
+ for: MetadataKey.firstOpenRecorded,
+ database: database
+ ) == "1"
+ let pending = try database.query(
+ """
+ SELECT id, event_type, attempt_count, next_attempt_at, payload_size
+ FROM pending_events
+ ORDER BY id ASC
+ """
+ ).compactMap { row -> AnalyticsPendingEventDiagnostic? in
+ guard let rowID = row.int64(at: 0),
+ let eventTypeText = row.text(at: 1),
+ let attemptCount = row.int64(at: 2),
+ let nextAttemptAt = row.double(at: 3),
+ let payloadSize = row.int64(at: 4) else {
+ return nil
+ }
+ return AnalyticsPendingEventDiagnostic(
+ rowID: rowID,
+ eventType: AnalyticsEventType(rawValue: eventTypeText),
+ attemptCount: Int(attemptCount),
+ nextAttemptAt: Date(timeIntervalSince1970: nextAttemptAt),
+ payloadSize: Int(payloadSize)
+ )
+ }
+ let quarantined = try database.query(
+ """
+ SELECT id, event_type, attempt_count, reason, payload_size
+ FROM quarantined_events
+ ORDER BY id ASC
+ """
+ ).compactMap { row -> AnalyticsQuarantinedEventDiagnostic? in
+ guard let rowID = row.int64(at: 0),
+ let eventTypeText = row.text(at: 1),
+ let attemptCount = row.int64(at: 2),
+ let reason = row.text(at: 3),
+ let payloadSize = row.int64(at: 4) else {
+ return nil
+ }
+ return AnalyticsQuarantinedEventDiagnostic(
+ rowID: rowID,
+ eventType: AnalyticsEventType(rawValue: eventTypeText),
+ attemptCount: Int(attemptCount),
+ reason: reason,
+ payloadSize: Int(payloadSize)
+ )
+ }
+ return AnalyticsRepositoryDebugSnapshot(
+ isAvailable: true,
+ enabled: enabled,
+ installationID: installationID,
+ firstOpenRecorded: firstOpenRecorded,
+ pendingEvents: pending,
+ quarantinedEvents: quarantined
+ )
+ }
+ } catch {
+ return Self.unavailableDebugSnapshot
+ }
+ }
+
+ /// Internal raw-byte access is intentionally limited to @testable imports.
+ func debugPayloadBytes(rowID: Int64, quarantined: Bool = false) -> Data? {
+ guard let database = openDatabaseIfNeeded() else { return nil }
+ let table = quarantined ? "quarantined_events" : "pending_events"
+ do {
+ return try database.query(
+ "SELECT payload FROM \(table) WHERE id = ?",
+ bindings: [.int64(rowID)]
+ ).first?.data(at: 0)
+ } catch {
+ return nil
+ }
+ }
+
+ public func setEnabled(_ enabled: Bool) {
+ guard let database = openDatabaseIfNeeded() else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ let wasEnabled = try ensureEnabled(database)
+ guard wasEnabled != enabled else {
+ if enabled {
+ _ = try ensureInstallation(database)
+ }
+ return
+ }
+
+ if enabled {
+ try setMetadata("1", for: MetadataKey.enabled, database: database)
+ try rotateInstallation(database)
+ } else {
+ try setMetadata("0", for: MetadataKey.enabled, database: database)
+ try clearQueues(database)
+ try clearUploadLease(database)
+ }
+ }
+ }
+ }
+
+ public func observeAccount(
+ stableIdentifier: String
+ ) -> AnalyticsAccountObservation {
+ guard let database = openDatabaseIfNeeded() else { return .unavailable }
+ do {
+ return try database.immediateTransaction {
+ _ = try ensureEnabled(database)
+ guard try isEnabled(database) else { return .analyticsDisabled }
+ _ = try ensureInstallation(database)
+
+ let fingerprint = Self.accountFingerprint(stableIdentifier)
+ guard let existing = try metadata(
+ for: MetadataKey.accountFingerprint,
+ database: database
+ ) else {
+ try setMetadata(
+ fingerprint,
+ for: MetadataKey.accountFingerprint,
+ database: database
+ )
+ return .firstAccount
+ }
+ guard existing != fingerprint else { return .unchanged }
+
+ try setMetadata(
+ fingerprint,
+ for: MetadataKey.accountFingerprint,
+ database: database
+ )
+ try rotateInstallation(database)
+ return .switchedAccount
+ }
+ } catch {
+ return .unavailable
+ }
+ }
+
+ /// Account deletion creates a fresh anonymous analytics identity and removes
+ /// queued events while preserving the once-per-install FIRST_OPEN marker.
+ public func handleAccountDeletion() {
+ guard let database = openDatabaseIfNeeded() else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ _ = try ensureEnabled(database)
+ try removeMetadata(
+ for: MetadataKey.accountFingerprint,
+ database: database
+ )
+ guard try isEnabled(database) else {
+ try clearQueues(database)
+ return
+ }
+ try rotateInstallation(database)
+ }
+ }
+ }
+
+ func record(
+ eventType: AnalyticsEventType,
+ context: AnalyticsBootstrapContext,
+ surfaceOverride: AnalyticsSurface? = nil,
+ dimensions: AnalyticsEventDimensions = .none
+ ) {
+ guard let database = openDatabaseIfNeeded() else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ _ = try ensureEnabled(database)
+ guard try isEnabled(database) else { return }
+ let installationID = try ensureInstallation(database)
+ let event = try AnalyticsEvent(
+ installationId: installationID,
+ clientEventId: uuidGenerator.makeUUID(),
+ eventType: eventType,
+ occurredAt: clock.now(),
+ surface: surfaceOverride ?? context.surface,
+ appVersion: context.environment.appVersion,
+ osVersion: context.environment.osVersion,
+ acquisitionChannel: dimensions.acquisitionChannel,
+ feature: dimensions.feature,
+ executionMode: dimensions.executionMode,
+ failureCategory: dimensions.failureCategory,
+ durationBucket: dimensions.durationBucket
+ )
+ try insert(event, database: database)
+ try enforceStoragePolicy(database)
+ }
+ }
+ }
+
+ /// Starts at most one session per surface in each rolling 30-minute window.
+ func recordSessionIfNeeded(
+ context: AnalyticsBootstrapContext
+ ) {
+ guard let database = openDatabaseIfNeeded() else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ _ = try ensureEnabled(database)
+ guard try isEnabled(database) else { return }
+ let now = clock.now()
+ let key = MetadataKey.lastSession(context.surface)
+ if let text = try metadata(for: key, database: database),
+ let previous = TimeInterval(text) {
+ let elapsed = now.timeIntervalSince1970 - previous
+ if elapsed >= 0, elapsed < 30 * 60 {
+ // Session windows are based on inactivity, so every
+ // presentation refreshes the last-active timestamp.
+ try setMetadata(
+ String(now.timeIntervalSince1970),
+ for: key,
+ database: database
+ )
+ return
+ }
+ }
+
+ let installationID = try ensureInstallation(database)
+ let event = try AnalyticsEvent(
+ installationId: installationID,
+ clientEventId: uuidGenerator.makeUUID(),
+ eventType: .sessionStarted,
+ occurredAt: now,
+ surface: context.surface,
+ appVersion: context.environment.appVersion,
+ osVersion: context.environment.osVersion
+ )
+ try insert(event, database: database)
+ try setMetadata(
+ String(now.timeIntervalSince1970),
+ for: key,
+ database: database
+ )
+ try enforceStoragePolicy(database)
+ }
+ }
+ }
+
+ func leaseBatch(
+ ownerID: String,
+ configuration upload: AnalyticsUploadConfiguration
+ ) -> AnalyticsLeasedBatch? {
+ guard let database = openDatabaseIfNeeded() else { return nil }
+ do {
+ return try database.immediateTransaction {
+ let now = clock.now().timeIntervalSince1970
+ guard try acquireGlobalLease(
+ ownerID: ownerID,
+ expiresAt: now + upload.globalLeaseDuration,
+ now: now,
+ database: database
+ ) else {
+ return nil
+ }
+
+ try releaseExpiredEventLeases(now: now, database: database)
+ try deleteExpiredEvents(now: now, database: database)
+
+ let candidates = try database.query(
+ """
+ SELECT id, payload, attempt_count
+ FROM pending_events
+ WHERE next_attempt_at <= ? AND lease_id IS NULL
+ ORDER BY priority DESC, created_at ASC
+ LIMIT ?
+ """,
+ bindings: [.double(now), .int64(Int64(upload.maximumBatchCount))]
+ )
+
+ var selected: [AnalyticsLeasedEvent] = []
+ var bodySize = Self.emptyRequestBody.count
+ for row in candidates {
+ guard let rowID = row.int64(at: 0),
+ let payload = row.data(at: 1),
+ let attempts = row.int64(at: 2) else {
+ continue
+ }
+ let additional = payload.count + (selected.isEmpty ? 0 : 1)
+ guard bodySize + additional <= upload.maximumBodyBytes else {
+ if selected.isEmpty {
+ try quarantineRows(
+ [rowID],
+ reason: "oversized",
+ database: database
+ )
+ }
+ break
+ }
+ selected.append(
+ AnalyticsLeasedEvent(
+ rowID: rowID,
+ payload: payload,
+ attemptCount: Int(attempts)
+ )
+ )
+ bodySize += additional
+ }
+
+ guard !selected.isEmpty else {
+ try clearUploadLease(database)
+ return nil
+ }
+
+ let leaseID = uuidGenerator.makeUUID().uuidString.lowercased()
+ let leaseExpiry = now + upload.eventLeaseDuration
+ for event in selected {
+ try database.execute(
+ """
+ UPDATE pending_events
+ SET lease_id = ?, lease_expires_at = ?
+ WHERE id = ? AND lease_id IS NULL
+ """,
+ bindings: [
+ .text(leaseID),
+ .double(leaseExpiry),
+ .int64(event.rowID)
+ ]
+ )
+ }
+ return AnalyticsLeasedBatch(
+ leaseID: leaseID,
+ events: selected,
+ body: Self.requestBody(for: selected)
+ )
+ }
+ } catch {
+ return nil
+ }
+ }
+
+ func complete(
+ rowIDs: [Int64],
+ leaseID: String
+ ) -> Bool {
+ guard let database = openDatabaseIfNeeded(), !rowIDs.isEmpty else { return false }
+ do {
+ return try database.immediateTransaction {
+ var deleted = 0
+ for rowID in rowIDs {
+ try database.execute(
+ "DELETE FROM pending_events WHERE id = ? AND lease_id = ?",
+ bindings: [.int64(rowID), .text(leaseID)]
+ )
+ deleted += Int(database.changes)
+ }
+ guard deleted == rowIDs.count else {
+ throw SQLiteStoreError(
+ code: SQLITE_CONSTRAINT,
+ category: .constraint,
+ operation: "complete leased events"
+ )
+ }
+ return true
+ }
+ } catch {
+ return false
+ }
+ }
+
+ func quarantine(
+ rowIDs: [Int64],
+ leaseID: String,
+ reason: String
+ ) {
+ guard let database = openDatabaseIfNeeded(), !rowIDs.isEmpty else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ try quarantineRows(
+ rowIDs,
+ leaseID: leaseID,
+ reason: reason,
+ database: database
+ )
+ }
+ }
+ }
+
+ func scheduleRetry(
+ events: [AnalyticsLeasedEvent],
+ leaseID: String,
+ delay: TimeInterval
+ ) {
+ guard let database = openDatabaseIfNeeded(), !events.isEmpty else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ let nextAttempt = clock.now().addingTimeInterval(max(0, delay))
+ .timeIntervalSince1970
+ for event in events {
+ try database.execute(
+ """
+ UPDATE pending_events
+ SET attempt_count = attempt_count + 1,
+ next_attempt_at = ?,
+ lease_id = NULL,
+ lease_expires_at = NULL
+ WHERE id = ? AND lease_id = ?
+ """,
+ bindings: [
+ .double(nextAttempt),
+ .int64(event.rowID),
+ .text(leaseID)
+ ]
+ )
+ }
+ }
+ }
+ }
+
+ func releaseGlobalLease(ownerID: String) {
+ guard let database = openDatabaseIfNeeded() else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ try releaseGlobalLease(ownerID: ownerID, database: database)
+ }
+ }
+ }
+
+ func renewUploadLease(
+ ownerID: String,
+ leaseID: String,
+ globalLeaseDuration: TimeInterval,
+ eventLeaseDuration: TimeInterval
+ ) -> Bool {
+ guard let database = openDatabaseIfNeeded() else { return false }
+ do {
+ return try database.immediateTransaction {
+ guard try metadata(
+ for: MetadataKey.uploadLeaseOwner,
+ database: database
+ ) == ownerID else {
+ return false
+ }
+ let now = clock.now().timeIntervalSince1970
+ try setMetadata(
+ String(now + globalLeaseDuration),
+ for: MetadataKey.uploadLeaseExpiresAt,
+ database: database
+ )
+ try database.execute(
+ """
+ UPDATE pending_events
+ SET lease_expires_at = ?
+ WHERE lease_id = ?
+ """,
+ bindings: [
+ .double(now + eventLeaseDuration),
+ .text(leaseID)
+ ]
+ )
+ return true
+ }
+ } catch {
+ return false
+ }
+ }
+
+ func releaseEvents(
+ _ events: [AnalyticsLeasedEvent],
+ leaseID: String
+ ) {
+ guard let database = openDatabaseIfNeeded(), !events.isEmpty else { return }
+ absorbDatabaseErrors {
+ try database.immediateTransaction {
+ for event in events {
+ try database.execute(
+ """
+ UPDATE pending_events
+ SET lease_id = NULL, lease_expires_at = NULL
+ WHERE id = ? AND lease_id = ?
+ """,
+ bindings: [.int64(event.rowID), .text(leaseID)]
+ )
+ }
+ }
+ }
+ }
+
+ // MARK: - Identity and queue policy
+
+ private func ensureInstallation(
+ _ database: SQLiteDatabase
+ ) throws -> UUID {
+ if let value = try metadata(for: MetadataKey.installationID, database: database),
+ let identifier = UUID(uuidString: value) {
+ return identifier
+ }
+
+ let identifier = uuidGenerator.makeUUID()
+ try setMetadata(
+ identifier.uuidString.lowercased(),
+ for: MetadataKey.installationID,
+ database: database
+ )
+ return identifier
+ }
+
+ private func rotateInstallation(
+ _ database: SQLiteDatabase
+ ) throws {
+ try clearQueues(database)
+ try clearUploadLease(database)
+ try removeMetadata(for: MetadataKey.installationID, database: database)
+ for surface in AnalyticsSurface.allCases {
+ try removeMetadata(
+ for: MetadataKey.lastSession(surface),
+ database: database
+ )
+ }
+ _ = try ensureInstallation(database)
+ }
+
+ private func insert(
+ _ event: AnalyticsEvent,
+ database: SQLiteDatabase
+ ) throws {
+ let payload = try AnalyticsCanonicalJSON.encode(event)
+ try database.execute(
+ """
+ INSERT OR IGNORE INTO pending_events (
+ client_event_id, event_type, occurred_at, surface, payload,
+ payload_size, priority, lease_id, lease_expires_at,
+ attempt_count, next_attempt_at, created_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, NULL, NULL, 0, 0, ?)
+ """,
+ bindings: [
+ .text(event.clientEventId.uuidString.lowercased()),
+ .text(event.eventType.rawValue),
+ .double(event.occurredAt.timeIntervalSince1970),
+ .text(event.surface.rawValue),
+ .blob(payload),
+ .int64(Int64(payload.count)),
+ .int64(Int64(Self.priority(for: event.eventType))),
+ .double(clock.now().timeIntervalSince1970)
+ ]
+ )
+ }
+
+ private func enforceStoragePolicy(_ database: SQLiteDatabase) throws {
+ try deleteExpiredEvents(
+ now: clock.now().timeIntervalSince1970,
+ database: database
+ )
+ while true {
+ let row = try database.query(
+ """
+ SELECT
+ (SELECT COUNT(*) FROM pending_events)
+ + (SELECT COUNT(*) FROM quarantined_events),
+ (SELECT COALESCE(SUM(payload_size), 0) FROM pending_events)
+ + (SELECT COALESCE(SUM(payload_size), 0) FROM quarantined_events)
+ """
+ ).first
+ let count = row?.int64(at: 0) ?? 0
+ let bytes = row?.int64(at: 1) ?? 0
+ guard count > Int64(configuration.maximumEventCount)
+ || bytes > Int64(configuration.maximumStoredBytes) else {
+ return
+ }
+
+ // Quarantined poison events are the least valuable retained records.
+ try database.execute(
+ """
+ DELETE FROM quarantined_events
+ WHERE id = (
+ SELECT id FROM quarantined_events
+ ORDER BY quarantined_at ASC
+ LIMIT 1
+ )
+ """
+ )
+ if database.changes > 0 {
+ try incrementDiagnostic(
+ MetadataKey.capacityDropCount,
+ by: Int64(database.changes),
+ database: database
+ )
+ continue
+ }
+ try database.execute(
+ """
+ DELETE FROM pending_events
+ WHERE id = (
+ SELECT id FROM pending_events
+ WHERE lease_id IS NULL
+ ORDER BY priority ASC, created_at ASC
+ LIMIT 1
+ )
+ """
+ )
+ guard database.changes > 0 else { return }
+ try incrementDiagnostic(
+ MetadataKey.capacityDropCount,
+ by: Int64(database.changes),
+ database: database
+ )
+ }
+ }
+
+ private func deleteExpiredEvents(
+ now: TimeInterval,
+ database: SQLiteDatabase
+ ) throws {
+ try database.execute(
+ "DELETE FROM pending_events WHERE occurred_at < ?",
+ bindings: [.double(now - configuration.eventRetention)]
+ )
+ var deleted = Int64(database.changes)
+ try database.execute(
+ "DELETE FROM quarantined_events WHERE occurred_at < ?",
+ bindings: [.double(now - configuration.eventRetention)]
+ )
+ deleted += Int64(database.changes)
+ try incrementDiagnostic(
+ MetadataKey.expiredDropCount,
+ by: deleted,
+ database: database
+ )
+ }
+
+ private func clearQueues(_ database: SQLiteDatabase) throws {
+ try database.execute("DELETE FROM pending_events")
+ try database.execute("DELETE FROM quarantined_events")
+ }
+
+ // MARK: - Leases
+
+ private func acquireGlobalLease(
+ ownerID: String,
+ expiresAt: TimeInterval,
+ now: TimeInterval,
+ database: SQLiteDatabase
+ ) throws -> Bool {
+ let existingOwner = try metadata(
+ for: MetadataKey.uploadLeaseOwner,
+ database: database
+ )
+ let existingExpiry = try metadata(
+ for: MetadataKey.uploadLeaseExpiresAt,
+ database: database
+ ).flatMap(TimeInterval.init) ?? 0
+ guard existingOwner == nil || existingOwner == ownerID || existingExpiry <= now else {
+ return false
+ }
+ try setMetadata(ownerID, for: MetadataKey.uploadLeaseOwner, database: database)
+ try setMetadata(
+ String(expiresAt),
+ for: MetadataKey.uploadLeaseExpiresAt,
+ database: database
+ )
+ return true
+ }
+
+ private func releaseGlobalLease(
+ ownerID: String,
+ database: SQLiteDatabase
+ ) throws {
+ guard try metadata(
+ for: MetadataKey.uploadLeaseOwner,
+ database: database
+ ) == ownerID else {
+ return
+ }
+ try clearUploadLease(database)
+ }
+
+ private func clearUploadLease(_ database: SQLiteDatabase) throws {
+ try removeMetadata(for: MetadataKey.uploadLeaseOwner, database: database)
+ try removeMetadata(for: MetadataKey.uploadLeaseExpiresAt, database: database)
+ }
+
+ private func releaseExpiredEventLeases(
+ now: TimeInterval,
+ database: SQLiteDatabase
+ ) throws {
+ try database.execute(
+ """
+ UPDATE pending_events
+ SET lease_id = NULL, lease_expires_at = NULL
+ WHERE lease_expires_at IS NOT NULL AND lease_expires_at <= ?
+ """,
+ bindings: [.double(now)]
+ )
+ }
+
+ private func quarantineRows(
+ _ rowIDs: [Int64],
+ leaseID: String? = nil,
+ reason: String,
+ database: SQLiteDatabase
+ ) throws {
+ for rowID in rowIDs {
+ var bindings: [SQLiteBinding] = [
+ .text(reason),
+ .double(clock.now().timeIntervalSince1970),
+ .int64(rowID)
+ ]
+ var leaseClause = ""
+ if let leaseID {
+ leaseClause = " AND lease_id = ?"
+ bindings.append(.text(leaseID))
+ }
+ try database.execute(
+ """
+ INSERT INTO quarantined_events (
+ client_event_id, event_type, occurred_at, surface, payload,
+ payload_size, attempt_count, reason, quarantined_at
+ )
+ SELECT client_event_id, event_type, occurred_at, surface, payload,
+ payload_size, attempt_count, ?, ?
+ FROM pending_events
+ WHERE id = ?\(leaseClause)
+ """,
+ bindings: bindings
+ )
+ try database.execute(
+ "DELETE FROM pending_events WHERE id = ?\(leaseClause)",
+ bindings: leaseID.map {
+ [.int64(rowID), .text($0)]
+ } ?? [.int64(rowID)]
+ )
+ }
+ try enforceStoragePolicy(database)
+ }
+
+ private static let emptyRequestBody = Data(#"{"events":[]}"#.utf8)
+
+ private static func requestBody(for events: [AnalyticsLeasedEvent]) -> Data {
+ var body = Data(#"{"events":["#.utf8)
+ for index in events.indices {
+ if index > 0 {
+ body.append(UInt8(ascii: ","))
+ }
+ body.append(events[index].payload)
+ }
+ body.append(Data("]}".utf8))
+ return body
+ }
+
+ private static func priority(for eventType: AnalyticsEventType) -> Int {
+ switch eventType {
+ case .firstOpen, .aiFeatureSucceeded, .aiFeatureFailed:
+ return 2
+ case .aiFeatureStarted,
+ .purchaseViewed,
+ .purchaseStarted,
+ .purchaseCancelled,
+ .referralShared,
+ .inviteOpened:
+ return 1
+ case .sessionStarted, .keyboardActivated:
+ return 0
+ }
+ }
+
+ // MARK: - Metadata and setup
+
+ private func openDatabaseIfNeeded() -> SQLiteDatabase? {
+ if let database {
+ return database
+ }
+ guard let url = configuration.databaseURL else { return nil }
+ do {
+ let parent = url.deletingLastPathComponent()
+ try FileManager.default.createDirectory(
+ at: parent,
+ withIntermediateDirectories: true,
+ attributes: Self.directoryProtectionAttributes
+ )
+ let opened = try SQLiteDatabase(
+ url: url,
+ busyTimeoutMilliseconds: configuration.busyTimeoutMilliseconds
+ )
+ try migrate(opened)
+ applyFileProtection(to: url)
+ database = opened
+ return opened
+ } catch {
+ return nil
+ }
+ }
+
+ private func migrate(_ database: SQLiteDatabase) throws {
+ let version = try database.scalarInt64("PRAGMA user_version") ?? 0
+ guard version <= 1 else {
+ throw SQLiteStoreError(
+ code: SQLITE_MISMATCH,
+ category: .schema,
+ operation: "validate schema version"
+ )
+ }
+ if version == 0 {
+ try database.immediateTransaction {
+ try database.execute(
+ """
+ CREATE TABLE IF NOT EXISTS metadata (
+ key TEXT PRIMARY KEY NOT NULL,
+ value BLOB NOT NULL
+ ) WITHOUT ROWID
+ """
+ )
+ try database.execute(
+ """
+ CREATE TABLE IF NOT EXISTS pending_events (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ client_event_id TEXT UNIQUE NOT NULL,
+ event_type TEXT NOT NULL,
+ occurred_at REAL NOT NULL,
+ surface TEXT NOT NULL,
+ payload BLOB NOT NULL,
+ payload_size INTEGER NOT NULL CHECK(payload_size >= 0),
+ priority INTEGER NOT NULL,
+ lease_id TEXT,
+ lease_expires_at REAL,
+ attempt_count INTEGER NOT NULL DEFAULT 0,
+ next_attempt_at REAL NOT NULL DEFAULT 0,
+ created_at REAL NOT NULL
+ )
+ """
+ )
+ try database.execute(
+ """
+ CREATE INDEX IF NOT EXISTS pending_events_ready
+ ON pending_events(next_attempt_at, lease_id, priority, created_at)
+ """
+ )
+ try database.execute(
+ """
+ CREATE INDEX IF NOT EXISTS pending_events_expiry
+ ON pending_events(occurred_at)
+ """
+ )
+ try database.execute(
+ """
+ CREATE TABLE IF NOT EXISTS quarantined_events (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ client_event_id TEXT UNIQUE NOT NULL,
+ event_type TEXT NOT NULL,
+ occurred_at REAL NOT NULL,
+ surface TEXT NOT NULL,
+ payload BLOB NOT NULL,
+ payload_size INTEGER NOT NULL,
+ attempt_count INTEGER NOT NULL,
+ reason TEXT NOT NULL,
+ quarantined_at REAL NOT NULL
+ )
+ """
+ )
+ try database.execute("PRAGMA user_version = 1")
+ }
+ }
+ }
+
+ private func applyFileProtection(to databaseURL: URL) {
+ #if os(iOS)
+ for url in [
+ databaseURL,
+ URL(fileURLWithPath: databaseURL.path + "-wal"),
+ URL(fileURLWithPath: databaseURL.path + "-shm")
+ ] where FileManager.default.fileExists(atPath: url.path) {
+ try? FileManager.default.setAttributes(
+ [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication],
+ ofItemAtPath: url.path
+ )
+ }
+ #endif
+ }
+
+ private static var directoryProtectionAttributes: [
+ FileAttributeKey: Any
+ ]? {
+ #if os(iOS)
+ return [
+ .protectionKey: FileProtectionType.completeUntilFirstUserAuthentication
+ ]
+ #else
+ return nil
+ #endif
+ }
+
+ @discardableResult
+ private func ensureEnabled(_ database: SQLiteDatabase) throws -> Bool {
+ if let value = try metadata(for: MetadataKey.enabled, database: database) {
+ return value == "1"
+ }
+ try setMetadata("1", for: MetadataKey.enabled, database: database)
+ return true
+ }
+
+ private func isEnabled(_ database: SQLiteDatabase) throws -> Bool {
+ try metadata(for: MetadataKey.enabled, database: database) != "0"
+ }
+
+ private func metadata(
+ for key: String,
+ database: SQLiteDatabase
+ ) throws -> String? {
+ try database.query(
+ "SELECT value FROM metadata WHERE key = ?",
+ bindings: [.text(key)]
+ ).first?.text(at: 0)
+ }
+
+ private func setMetadata(
+ _ value: String,
+ for key: String,
+ database: SQLiteDatabase
+ ) throws {
+ try database.execute(
+ """
+ INSERT INTO metadata(key, value) VALUES(?, ?)
+ ON CONFLICT(key) DO UPDATE SET value = excluded.value
+ """,
+ bindings: [.text(key), .text(value)]
+ )
+ }
+
+ private func removeMetadata(
+ for key: String,
+ database: SQLiteDatabase
+ ) throws {
+ try database.execute(
+ "DELETE FROM metadata WHERE key = ?",
+ bindings: [.text(key)]
+ )
+ }
+
+ private func incrementDiagnostic(
+ _ key: String,
+ by amount: Int64,
+ database: SQLiteDatabase
+ ) throws {
+ guard amount > 0 else { return }
+ let existing = try metadata(for: key, database: database).flatMap(Int64.init) ?? 0
+ try setMetadata(String(existing + amount), for: key, database: database)
+ }
+
+ private func absorbDatabaseErrors(_ operation: () throws -> Void) {
+ do {
+ try operation()
+ } catch {
+ // Analytics must never alter the host app's business control flow.
+ }
+ }
+
+ private static let unavailableDebugSnapshot = AnalyticsRepositoryDebugSnapshot(
+ isAvailable: false,
+ enabled: true,
+ installationID: nil,
+ firstOpenRecorded: false,
+ pendingEvents: [],
+ quarantinedEvents: []
+ )
+
+ private static func accountFingerprint(_ identifier: String) -> String {
+ SHA256.hash(data: Data(identifier.utf8))
+ .map { String(format: "%02x", $0) }
+ .joined()
+ }
+}
+
+// MARK: - SQLite C API boundary
+
+private enum SQLiteErrorCategory: Sendable {
+ case busy
+ case constraint
+ case corrupt
+ case io
+ case schema
+ case other
+}
+
+private struct SQLiteStoreError: Error, Sendable {
+ let code: Int32
+ let category: SQLiteErrorCategory
+ let operation: String
+}
+
+private enum SQLiteBinding {
+ case null
+ case int64(Int64)
+ case double(Double)
+ case text(String)
+ case blob(Data)
+}
+
+private struct SQLiteRow {
+ private let values: [SQLiteValue]
+
+ init(statement: OpaquePointer) {
+ values = (0.. 0, let pointer = sqlite3_column_blob(statement, index) else {
+ return .blob(Data())
+ }
+ return .blob(Data(bytes: pointer, count: count))
+ default:
+ return .null
+ }
+ }
+ }
+
+ func int64(at index: Int) -> Int64? {
+ guard values.indices.contains(index), case .int64(let value) = values[index] else {
+ return nil
+ }
+ return value
+ }
+
+ func text(at index: Int) -> String? {
+ guard values.indices.contains(index) else { return nil }
+ switch values[index] {
+ case .text(let value):
+ return value
+ case .blob(let data):
+ return String(data: data, encoding: .utf8)
+ default:
+ return nil
+ }
+ }
+
+ func double(at index: Int) -> Double? {
+ guard values.indices.contains(index) else { return nil }
+ switch values[index] {
+ case .double(let value):
+ return value
+ case .int64(let value):
+ return Double(value)
+ default:
+ return nil
+ }
+ }
+
+ func data(at index: Int) -> Data? {
+ guard values.indices.contains(index), case .blob(let value) = values[index] else {
+ return nil
+ }
+ return value
+ }
+}
+
+private enum SQLiteValue {
+ case null
+ case int64(Int64)
+ case double(Double)
+ case text(String)
+ case blob(Data)
+}
+
+private final class SQLiteDatabase {
+ private static let transient = unsafeBitCast(
+ -1,
+ to: sqlite3_destructor_type.self
+ )
+
+ private var handle: OpaquePointer?
+
+ init(url: URL, busyTimeoutMilliseconds: Int32) throws {
+ var opened: OpaquePointer?
+ let flags = SQLITE_OPEN_CREATE | SQLITE_OPEN_READWRITE | SQLITE_OPEN_FULLMUTEX
+ let result = sqlite3_open_v2(url.path, &opened, flags, nil)
+ guard result == SQLITE_OK, let opened else {
+ if let opened {
+ sqlite3_close_v2(opened)
+ }
+ throw Self.error(code: result, operation: "open database")
+ }
+ handle = opened
+ sqlite3_extended_result_codes(opened, 1)
+ sqlite3_busy_timeout(opened, busyTimeoutMilliseconds)
+ do {
+ try execute("PRAGMA journal_mode = WAL")
+ try execute("PRAGMA synchronous = NORMAL")
+ try execute("PRAGMA foreign_keys = ON")
+ } catch {
+ sqlite3_close_v2(opened)
+ handle = nil
+ throw error
+ }
+ }
+
+ deinit {
+ if let handle {
+ sqlite3_close_v2(handle)
+ }
+ }
+
+ var changes: Int32 {
+ guard let handle else { return 0 }
+ return sqlite3_changes(handle)
+ }
+
+ func execute(
+ _ sql: String,
+ bindings: [SQLiteBinding] = []
+ ) throws {
+ let statement = try prepare(sql)
+ defer { sqlite3_finalize(statement) }
+ try bind(bindings, to: statement)
+ let result = sqlite3_step(statement)
+ guard result == SQLITE_DONE || result == SQLITE_ROW else {
+ throw currentError(operation: "execute statement")
+ }
+ }
+
+ func query(
+ _ sql: String,
+ bindings: [SQLiteBinding] = []
+ ) throws -> [SQLiteRow] {
+ let statement = try prepare(sql)
+ defer { sqlite3_finalize(statement) }
+ try bind(bindings, to: statement)
+ var rows: [SQLiteRow] = []
+ while true {
+ switch sqlite3_step(statement) {
+ case SQLITE_ROW:
+ rows.append(SQLiteRow(statement: statement))
+ case SQLITE_DONE:
+ return rows
+ default:
+ throw currentError(operation: "query statement")
+ }
+ }
+ }
+
+ func scalarInt64(_ sql: String) throws -> Int64? {
+ try query(sql).first?.int64(at: 0)
+ }
+
+ func immediateTransaction(_ operation: () throws -> T) throws -> T {
+ try execute("BEGIN IMMEDIATE")
+ do {
+ let value = try operation()
+ try execute("COMMIT")
+ return value
+ } catch {
+ try? execute("ROLLBACK")
+ throw error
+ }
+ }
+
+ private func prepare(_ sql: String) throws -> OpaquePointer {
+ guard let handle else {
+ throw Self.error(code: SQLITE_MISUSE, operation: "prepare closed database")
+ }
+ var statement: OpaquePointer?
+ let result = sqlite3_prepare_v2(handle, sql, -1, &statement, nil)
+ guard result == SQLITE_OK, let statement else {
+ throw currentError(operation: "prepare statement")
+ }
+ return statement
+ }
+
+ private func bind(
+ _ bindings: [SQLiteBinding],
+ to statement: OpaquePointer
+ ) throws {
+ for (offset, binding) in bindings.enumerated() {
+ let index = Int32(offset + 1)
+ let result: Int32
+ switch binding {
+ case .null:
+ result = sqlite3_bind_null(statement, index)
+ case .int64(let value):
+ result = sqlite3_bind_int64(statement, index, value)
+ case .double(let value):
+ result = sqlite3_bind_double(statement, index, value)
+ case .text(let value):
+ result = sqlite3_bind_text(statement, index, value, -1, Self.transient)
+ case .blob(let data):
+ result = data.withUnsafeBytes { bytes in
+ sqlite3_bind_blob(
+ statement,
+ index,
+ bytes.baseAddress,
+ Int32(bytes.count),
+ Self.transient
+ )
+ }
+ }
+ guard result == SQLITE_OK else {
+ throw currentError(operation: "bind statement")
+ }
+ }
+ }
+
+ private func currentError(operation: String) -> SQLiteStoreError {
+ guard let handle else {
+ return Self.error(code: SQLITE_MISUSE, operation: operation)
+ }
+ return Self.error(code: sqlite3_extended_errcode(handle), operation: operation)
+ }
+
+ private static func error(
+ code: Int32,
+ operation: String
+ ) -> SQLiteStoreError {
+ let primary = code & 0xFF
+ let category: SQLiteErrorCategory
+ switch primary {
+ case SQLITE_BUSY, SQLITE_LOCKED:
+ category = .busy
+ case SQLITE_CONSTRAINT:
+ category = .constraint
+ case SQLITE_CORRUPT, SQLITE_NOTADB:
+ category = .corrupt
+ case SQLITE_IOERR, SQLITE_CANTOPEN, SQLITE_FULL:
+ category = .io
+ case SQLITE_SCHEMA, SQLITE_MISMATCH:
+ category = .schema
+ default:
+ category = .other
+ }
+ return SQLiteStoreError(code: code, category: category, operation: operation)
+ }
+}
diff --git a/OSGKeyboardShared/Features/Analytics/AnalyticsUploadCoordinator.swift b/OSGKeyboardShared/Features/Analytics/AnalyticsUploadCoordinator.swift
new file mode 100644
index 0000000..c70fe76
--- /dev/null
+++ b/OSGKeyboardShared/Features/Analytics/AnalyticsUploadCoordinator.swift
@@ -0,0 +1,484 @@
+// AnalyticsUploadCoordinator.swift
+// OSGKeyboard · Shared
+//
+// Bounded uploader with cross-process leases, retry policy and poison-event
+// isolation. Logs never contain payloads, identifiers, endpoints or tokens.
+
+import Foundation
+
+public final class URLSessionAnalyticsNetwork: AnalyticsNetworking, @unchecked Sendable {
+ private let session: URLSession
+
+ public init(session: URLSession = .shared) {
+ self.session = session
+ }
+
+ public func send(_ request: AnalyticsHTTPRequest) async throws -> AnalyticsHTTPResponse {
+ var urlRequest = URLRequest(url: request.url)
+ urlRequest.httpMethod = "POST"
+ urlRequest.httpBody = request.body
+ urlRequest.timeoutInterval = 30
+ for (name, value) in request.headers {
+ urlRequest.setValue(value, forHTTPHeaderField: name)
+ }
+
+ let (body, response) = try await session.data(for: urlRequest)
+ guard let httpResponse = response as? HTTPURLResponse else {
+ throw AnalyticsNetworkError.nonHTTPResponse
+ }
+ var headers: [String: String] = [:]
+ for (key, value) in httpResponse.allHeaderFields {
+ headers[String(describing: key)] = String(describing: value)
+ }
+ return AnalyticsHTTPResponse(
+ statusCode: httpResponse.statusCode,
+ headers: headers,
+ body: body
+ )
+ }
+}
+
+public actor AnalyticsUploadCoordinator {
+ private struct AuthorizationState {
+ var token: String?
+ var didRefresh = false
+ }
+
+ private let repository: AnalyticsRepository
+ private let configuration: AnalyticsUploadConfiguration
+ private let network: any AnalyticsNetworking
+ private let bearerProvider: (any AnalyticsBearerProviding)?
+ private let clock: any AnalyticsWallClock
+ private let uuidGenerator: any AnalyticsUUIDGenerating
+ private let random: any AnalyticsRandomGenerating
+ private let logger: any AnalyticsLogging
+ private var uploadInProgress = false
+
+ public init(
+ repository: AnalyticsRepository,
+ configuration: AnalyticsUploadConfiguration,
+ network: any AnalyticsNetworking = URLSessionAnalyticsNetwork(),
+ bearerProvider: (any AnalyticsBearerProviding)? = nil,
+ clock: any AnalyticsWallClock = SystemAnalyticsWallClock(),
+ uuidGenerator: any AnalyticsUUIDGenerating = SystemAnalyticsUUIDGenerator(),
+ random: any AnalyticsRandomGenerating = SystemAnalyticsRandomGenerator(),
+ logger: any AnalyticsLogging = NoopAnalyticsLogger()
+ ) {
+ self.repository = repository
+ self.configuration = configuration
+ self.network = network
+ self.bearerProvider = bearerProvider
+ self.clock = clock
+ self.uuidGenerator = uuidGenerator
+ self.random = random
+ self.logger = logger
+ }
+
+ /// Performs a bounded drain. The default keeps extension execution time and
+ /// memory predictable while allowing a host app to request more batches.
+ public func uploadAvailableEvents(maximumBatches: Int = 1) async {
+ guard !uploadInProgress else { return }
+ uploadInProgress = true
+ defer { uploadInProgress = false }
+
+ guard configuration.endpoint.scheme?.lowercased() == "https" else {
+ logger.log(
+ AnalyticsUploadLogEntry(
+ outcome: .skipped,
+ eventCount: 0,
+ errorCategory: .client
+ )
+ )
+ return
+ }
+
+ let ownerID = uuidGenerator.makeUUID().uuidString.lowercased()
+ let batchLimit = max(1, maximumBatches)
+ for _ in 0.. AnalyticsHTTPResponse {
+ var headers = [
+ "Accept": "application/json",
+ "Content-Type": "application/json"
+ ]
+ if let token, !token.isEmpty {
+ headers["Authorization"] = "Bearer \(token)"
+ }
+ return try await network.send(
+ AnalyticsHTTPRequest(
+ url: configuration.endpoint,
+ headers: headers,
+ body: Self.requestBody(for: events)
+ )
+ )
+ }
+
+ private func renewLease(
+ events: [AnalyticsLeasedEvent],
+ leaseID: String,
+ ownerID: String
+ ) async -> Bool {
+ let renewed = await repository.renewUploadLease(
+ ownerID: ownerID,
+ leaseID: leaseID,
+ globalLeaseDuration: configuration.globalLeaseDuration,
+ eventLeaseDuration: configuration.eventLeaseDuration
+ )
+ guard renewed else {
+ await repository.releaseEvents(events, leaseID: leaseID)
+ logger.log(
+ AnalyticsUploadLogEntry(
+ outcome: .skipped,
+ eventCount: events.count,
+ attempt: maximumAttempt(in: events),
+ errorCategory: .storage
+ )
+ )
+ return false
+ }
+ return true
+ }
+
+ private func scheduleRetry(
+ events: [AnalyticsLeasedEvent],
+ leaseID: String,
+ response: AnalyticsHTTPResponse?,
+ category: AnalyticsUploadErrorCategory,
+ minimumDelay: TimeInterval = 0
+ ) async {
+ let attempt = maximumAttempt(in: events) + 1
+ let exponent = min(attempt - 1, 16)
+ let ceiling = min(
+ configuration.maximumBackoff,
+ pow(2, Double(exponent))
+ )
+ let jitterMilliseconds = random.next(
+ upperBound: UInt64(max(0, ceiling * 1_000))
+ )
+ let jitter = TimeInterval(jitterMilliseconds) / 1_000
+ let retryAfter = response.flatMap(retryAfterDelay) ?? 0
+ let delay = min(
+ configuration.maximumBackoff,
+ max(minimumDelay, retryAfter, jitter)
+ )
+ await repository.scheduleRetry(
+ events: events,
+ leaseID: leaseID,
+ delay: delay
+ )
+ logger.log(
+ AnalyticsUploadLogEntry(
+ outcome: .retryScheduled,
+ eventCount: events.count,
+ statusCode: response?.statusCode,
+ attempt: attempt,
+ errorCategory: category
+ )
+ )
+ }
+
+ private func retryAfterDelay(_ response: AnalyticsHTTPResponse) -> TimeInterval? {
+ guard let value = response.header(named: "Retry-After")?
+ .trimmingCharacters(in: .whitespacesAndNewlines) else {
+ return nil
+ }
+ if let seconds = TimeInterval(value) {
+ return min(configuration.maximumBackoff, max(0, seconds))
+ }
+ guard let date = Self.httpDateFormatter.date(from: value) else {
+ return nil
+ }
+ return min(
+ configuration.maximumBackoff,
+ max(0, date.timeIntervalSince(clock.now()))
+ )
+ }
+
+ private func maximumAttempt(in events: [AnalyticsLeasedEvent]) -> Int {
+ events.map(\.attemptCount).max() ?? 0
+ }
+
+ private static func requestBody(for events: [AnalyticsLeasedEvent]) -> Data {
+ var body = Data(#"{"events":["#.utf8)
+ for index in events.indices {
+ if index > 0 {
+ body.append(UInt8(ascii: ","))
+ }
+ body.append(events[index].payload)
+ }
+ body.append(Data("]}".utf8))
+ return body
+ }
+
+ private static func networkCategory(for error: Error) -> AnalyticsUploadErrorCategory {
+ guard let urlError = error as? URLError else { return .network }
+ switch urlError.code {
+ case .timedOut:
+ return .timeout
+ case .userAuthenticationRequired,
+ .userCancelledAuthentication:
+ return .authentication
+ default:
+ return .network
+ }
+ }
+
+ private static var httpDateFormatter: DateFormatter {
+ let formatter = DateFormatter()
+ formatter.locale = Locale(identifier: "en_US_POSIX")
+ formatter.timeZone = TimeZone(secondsFromGMT: 0)
+ formatter.dateFormat = "EEE',' dd MMM yyyy HH':'mm':'ss z"
+ return formatter
+ }
+}
+
+private enum AnalyticsNetworkError: Error {
+ case nonHTTPResponse
+}
diff --git a/OSGKeyboardShared/Features/ManagedGateway/ManagedGatewayModels.swift b/OSGKeyboardShared/Features/ManagedGateway/ManagedGatewayModels.swift
index ddc81e6..282af92 100644
--- a/OSGKeyboardShared/Features/ManagedGateway/ManagedGatewayModels.swift
+++ b/OSGKeyboardShared/Features/ManagedGateway/ManagedGatewayModels.swift
@@ -24,6 +24,12 @@ public enum ManagedGatewayTaskKind: String, Codable, CaseIterable, Sendable {
case agentPlanning = "agent_planning"
}
+/// Optional server-audited purpose. A purpose may affect billing only when the
+/// authenticated gateway independently verifies its eligibility.
+public enum ManagedGatewayRequestPurpose: String, Codable, Sendable {
+ case oobe
+}
+
public struct ManagedGatewayGrantCredentials: Codable, Equatable, Sendable {
public static let maximumAccessLifetime: TimeInterval = 5 * 60
@@ -143,4 +149,5 @@ struct ManagedGatewayTextRequest: Encodable, Sendable {
let temperature: Double
let stream: Bool
let taskKind: ManagedGatewayTaskKind
+ let requestPurpose: ManagedGatewayRequestPurpose?
}
diff --git a/OSGKeyboardShared/Features/ManagedGateway/ManagedLLMClient.swift b/OSGKeyboardShared/Features/ManagedGateway/ManagedLLMClient.swift
index 47b485a..5698e32 100644
--- a/OSGKeyboardShared/Features/ManagedGateway/ManagedLLMClient.swift
+++ b/OSGKeyboardShared/Features/ManagedGateway/ManagedLLMClient.swift
@@ -50,6 +50,7 @@ public struct ManagedLLMClient: LLMClient {
public let capability: Capability
public let taskKind: ManagedGatewayTaskKind
+ public let requestPurpose: ManagedGatewayRequestPurpose?
public let requestTimeout: TimeInterval
private let baseURL: URL
@@ -60,6 +61,7 @@ public struct ManagedLLMClient: LLMClient {
public init(
capability: Capability,
taskKind: ManagedGatewayTaskKind? = nil,
+ requestPurpose: ManagedGatewayRequestPurpose? = nil,
grants: GatewayGrantCoordinator,
baseURL: URL = GatewayGrantCoordinator.defaultBaseURL,
session: URLSession = .shared,
@@ -68,6 +70,7 @@ public struct ManagedLLMClient: LLMClient {
) {
self.capability = capability
self.taskKind = taskKind ?? capability.defaultTaskKind
+ self.requestPurpose = requestPurpose
self.grants = grants
self.baseURL = baseURL
self.session = session
@@ -287,7 +290,8 @@ public struct ManagedLLMClient: LLMClient {
maxOutputTokens: min(max(attempt.options.maxTokens ?? 512, 1), 4_096),
temperature: min(max(attempt.options.temperature ?? 0.2, 0), 1),
stream: stream,
- taskKind: taskKind
+ taskKind: taskKind,
+ requestPurpose: requestPurpose
)
var request = URLRequest(
@@ -419,6 +423,7 @@ public struct ManagedLLMClient: LLMClient {
public enum ManagedGatewayLLMClientFactory {
public static func polish(
taskKind: ManagedGatewayTaskKind = .dictationPolish,
+ requestPurpose: ManagedGatewayRequestPurpose? = nil,
grants: GatewayGrantCoordinator,
baseURL: URL = GatewayGrantCoordinator.defaultBaseURL,
session: URLSession = .shared
@@ -426,6 +431,7 @@ public enum ManagedGatewayLLMClientFactory {
ManagedLLMClient(
capability: .polish,
taskKind: taskKind,
+ requestPurpose: requestPurpose,
grants: grants,
baseURL: baseURL,
session: session
diff --git a/OSGKeyboardShared/Models/AppGroupConfiguration.swift b/OSGKeyboardShared/Models/AppGroupConfiguration.swift
index 9c489c3..45e3835 100644
--- a/OSGKeyboardShared/Models/AppGroupConfiguration.swift
+++ b/OSGKeyboardShared/Models/AppGroupConfiguration.swift
@@ -193,11 +193,15 @@ public struct AppGroupConfiguration: Sendable, Equatable {
)
}
- public func makeClient(taskKind: ManagedGatewayTaskKind? = nil) -> LLMClient {
+ public func makeClient(
+ taskKind: ManagedGatewayTaskKind? = nil,
+ requestPurpose: ManagedGatewayRequestPurpose? = nil
+ ) -> LLMClient {
if credentialSource == .managed {
return ManagedLLMClient(
capability: .polish,
taskKind: taskKind,
+ requestPurpose: requestPurpose,
grants: GatewayGrantCoordinator()
)
}
diff --git a/OSGKeyboardShared/Models/FlowSession/FlowCommand.swift b/OSGKeyboardShared/Models/FlowSession/FlowCommand.swift
index 96172f7..64d7e19 100644
--- a/OSGKeyboardShared/Models/FlowSession/FlowCommand.swift
+++ b/OSGKeyboardShared/Models/FlowSession/FlowCommand.swift
@@ -20,8 +20,8 @@ public struct FlowCommand: Codable, Equatable, Sendable {
case submitAIQuestion
}
- /// Wire version that includes managed-gateway AI task intent.
- public static let currentProtocolVersion = 6
+ /// Wire version that includes managed-gateway request purpose.
+ public static let currentProtocolVersion = 7
public let protocolVersion: Int
public let sessionId: UUID
@@ -43,6 +43,8 @@ public struct FlowCommand: Codable, Equatable, Sendable {
public let aiQuestionText: String?
/// Fine-grained managed-gateway intent for AI question submissions.
public let aiTaskKind: ManagedGatewayTaskKind?
+ /// Optional server-audited purpose for managed gateway billing policy.
+ public let managedRequestPurpose: ManagedGatewayRequestPurpose?
/// Clipboard-skill thinking override. Nil keeps AI-mode default (on).
public let aiThinkingEnabled: Bool?
/// Absolute wall-clock deadlines survive extension reconstruction.
@@ -65,6 +67,7 @@ public struct FlowCommand: Codable, Equatable, Sendable {
aiConversationID: UUID? = nil,
aiQuestionText: String? = nil,
aiTaskKind: ManagedGatewayTaskKind? = nil,
+ managedRequestPurpose: ManagedGatewayRequestPurpose? = nil,
aiThinkingEnabled: Bool? = nil,
startDeadlineAt: TimeInterval? = nil,
processingDeadlineAt: TimeInterval? = nil
@@ -84,6 +87,7 @@ public struct FlowCommand: Codable, Equatable, Sendable {
self.aiConversationID = aiConversationID
self.aiQuestionText = aiQuestionText
self.aiTaskKind = aiTaskKind
+ self.managedRequestPurpose = managedRequestPurpose
self.aiThinkingEnabled = aiThinkingEnabled
self.startDeadlineAt = startDeadlineAt
self.processingDeadlineAt = processingDeadlineAt
diff --git a/OSGKeyboardShared/Models/FlowUtteranceRequest.swift b/OSGKeyboardShared/Models/FlowUtteranceRequest.swift
index 914f084..de5a397 100644
--- a/OSGKeyboardShared/Models/FlowUtteranceRequest.swift
+++ b/OSGKeyboardShared/Models/FlowUtteranceRequest.swift
@@ -15,6 +15,8 @@ public struct FlowUtteranceRequest: Equatable, Sendable {
public let aiQuestionText: String?
/// Fine-grained managed-gateway intent. Regular questions keep the default.
public let aiTaskKind: ManagedGatewayTaskKind?
+ /// Optional server-audited purpose for managed gateway billing policy.
+ public let managedRequestPurpose: ManagedGatewayRequestPurpose?
/// Clipboard-skill thinking override. Nil keeps AI-mode default (on).
public let aiThinkingEnabled: Bool?
@@ -28,6 +30,7 @@ public struct FlowUtteranceRequest: Equatable, Sendable {
aiConversationID: UUID? = nil,
aiQuestionText: String? = nil,
aiTaskKind: ManagedGatewayTaskKind? = nil,
+ managedRequestPurpose: ManagedGatewayRequestPurpose? = nil,
aiThinkingEnabled: Bool? = nil
) {
self.mode = mode
@@ -37,6 +40,7 @@ public struct FlowUtteranceRequest: Equatable, Sendable {
self.aiConversationID = aiConversationID
self.aiQuestionText = aiQuestionText
self.aiTaskKind = aiTaskKind
+ self.managedRequestPurpose = managedRequestPurpose
self.aiThinkingEnabled = aiThinkingEnabled
}
diff --git a/OSGKeyboardShared/Services/AIQuestionService.swift b/OSGKeyboardShared/Services/AIQuestionService.swift
index 501b741..5661f02 100644
--- a/OSGKeyboardShared/Services/AIQuestionService.swift
+++ b/OSGKeyboardShared/Services/AIQuestionService.swift
@@ -114,22 +114,33 @@ public struct AIQuestionService: Sendable {
private let client: any LLMClient
private let conversations: AIConversationStore
private let responseLength: AIResponseLength
+ private let analyticsClient: any AnalyticsClient
+ private let analyticsFeature: AnalyticsFeature
+ private let analyticsExecutionMode: AnalyticsExecutionMode
public init(
client: any LLMClient,
conversations: AIConversationStore,
- responseLength: AIResponseLength = .default
+ responseLength: AIResponseLength = .default,
+ analyticsClient: any AnalyticsClient = NoopAnalyticsClient(),
+ analyticsFeature: AnalyticsFeature = .aiAssistant,
+ analyticsExecutionMode: AnalyticsExecutionMode = .byok
) {
self.client = client
self.conversations = conversations
self.responseLength = responseLength
+ self.analyticsClient = analyticsClient
+ self.analyticsFeature = analyticsFeature
+ self.analyticsExecutionMode = analyticsExecutionMode
}
public static func configured(
store: any ConfigurationStore,
conversations: AIConversationStore,
taskKind: ManagedGatewayTaskKind = .aiQuestion,
- thinkingEnabled: Bool = true
+ thinkingEnabled: Bool = true,
+ analyticsClient: any AnalyticsClient = NoopAnalyticsClient(),
+ analyticsFeature: AnalyticsFeature = .aiAssistant
) throws -> AIQuestionService {
if store.credentialSource == .managed {
return AIQuestionService(
@@ -139,7 +150,10 @@ public struct AIQuestionService: Sendable {
grants: GatewayGrantCoordinator()
),
conversations: conversations,
- responseLength: store.aiResponseLength
+ responseLength: store.aiResponseLength,
+ analyticsClient: analyticsClient,
+ analyticsFeature: analyticsFeature,
+ analyticsExecutionMode: .managed
)
}
// Same provider + baseURL + model resolution as dictation polish so the
@@ -172,7 +186,10 @@ public struct AIQuestionService: Sendable {
thinkingEnabled: thinkingEnabled
),
conversations: conversations,
- responseLength: store.aiResponseLength
+ responseLength: store.aiResponseLength,
+ analyticsClient: analyticsClient,
+ analyticsFeature: analyticsFeature,
+ analyticsExecutionMode: .byok
)
}
@@ -199,28 +216,38 @@ public struct AIQuestionService: Sendable {
maxTokens: Self.outputTokenLimit
)
- var accumulated = ""
- for try await event in client.completeStreaming(
- messages: messages,
- timeout: Self.requestTimeout,
- options: options
- ) {
- try Task.checkCancellation()
- switch event {
- case .delta(let chunk):
- accumulated += chunk
- let preview = Self.streamingPreview(accumulated)
- onPartial?(preview)
- case .restart:
- accumulated = ""
- onPartial?("")
+ let operation = analyticsClient.startAIFeature(
+ analyticsFeature,
+ executionMode: analyticsExecutionMode
+ )
+ do {
+ var accumulated = ""
+ for try await event in client.completeStreaming(
+ messages: messages,
+ timeout: Self.requestTimeout,
+ options: options
+ ) {
+ try Task.checkCancellation()
+ switch event {
+ case .delta(let chunk):
+ accumulated += chunk
+ let preview = Self.streamingPreview(accumulated)
+ onPartial?(preview)
+ case .restart:
+ accumulated = ""
+ onPartial?("")
+ }
}
- }
- try Task.checkCancellation()
+ try Task.checkCancellation()
- let answer = Self.boundedAnswer(accumulated)
- guard !answer.isEmpty else { throw ServiceError.emptyAnswer }
- return answer
+ let answer = Self.boundedAnswer(accumulated)
+ guard !answer.isEmpty else { throw ServiceError.emptyAnswer }
+ operation.succeed()
+ return answer
+ } catch {
+ operation.fail(category: Self.analyticsFailureCategory(for: error))
+ throw error
+ }
}
/// Commit only after the host wins the utterance terminal claim. Keeping
@@ -254,6 +281,42 @@ public struct AIQuestionService: Sendable {
return String(prefix.dropLast()) + "…"
}
+ private static func analyticsFailureCategory(
+ for error: Error
+ ) -> AnalyticsFailureCategory {
+ if error is CancellationError {
+ return .cancelled
+ }
+ if error is ServiceError {
+ return .validation
+ }
+ if let error = error as? ManagedGatewayError {
+ switch error {
+ case .insufficientCredits:
+ return .insufficientCredits
+ case .timeout:
+ return .timeout
+ case .missingGrant, .scopeNotGranted, .invalidGrant:
+ return .validation
+ case .server:
+ return .provider
+ }
+ }
+ if let error = error as? LLMError {
+ switch error {
+ case .cancelled:
+ return .cancelled
+ case .transport, .rateLimited:
+ return .network
+ case .invalidURL, .noAPIKey, .decoding:
+ return .validation
+ case .http:
+ return .provider
+ }
+ }
+ return .unknown
+ }
+
/// Soft cap for live drafts — no ellipsis mid-stream.
public static func streamingPreview(_ value: String) -> String {
if value.count <= AIQuestionLimits.maximumAnswerCharacterCount {
diff --git a/OSGKeyboardShared/Services/AppGroupStore.swift b/OSGKeyboardShared/Services/AppGroupStore.swift
index f6a0d16..6bddf76 100644
--- a/OSGKeyboardShared/Services/AppGroupStore.swift
+++ b/OSGKeyboardShared/Services/AppGroupStore.swift
@@ -394,7 +394,13 @@ public struct AppGroupStore: @unchecked Sendable {
// MARK: - Client
- public func makeClient(taskKind: ManagedGatewayTaskKind?) -> LLMClient {
- configuration.makeClient(taskKind: taskKind)
+ public func makeClient(
+ taskKind: ManagedGatewayTaskKind?,
+ requestPurpose: ManagedGatewayRequestPurpose?
+ ) -> LLMClient {
+ configuration.makeClient(
+ taskKind: taskKind,
+ requestPurpose: requestPurpose
+ )
}
}
diff --git a/OSGKeyboardShared/Services/KeyboardSetupBridge.swift b/OSGKeyboardShared/Services/KeyboardSetupBridge.swift
index 6e633c3..9df2556 100644
--- a/OSGKeyboardShared/Services/KeyboardSetupBridge.swift
+++ b/OSGKeyboardShared/Services/KeyboardSetupBridge.swift
@@ -11,6 +11,8 @@ public enum KeyboardSetupBridge {
private enum Key {
static let fullAccessReady = "keyboard.extension.fullAccessReady"
static let lastSeenAt = "keyboard.extension.lastSeenAt"
+ static let onboardingPracticeExpiresAt = "keyboard.onboarding.practiceExpiresAt"
+ static let lastVoiceInsertionAt = "keyboard.extension.lastVoiceInsertionAt"
}
/// True when the keyboard extension last appeared with Full Access enabled.
@@ -19,11 +21,72 @@ public enum KeyboardSetupBridge {
return AppGroup.defaults.bool(forKey: Key.fullAccessReady)
}
+ /// True after the extension has appeared at least once. Unlike
+ /// `isReadyForOnboardingSkip`, this also covers an appearance without Full
+ /// Access so the host can explain the missing setting precisely.
+ public static var hasAppeared: Bool {
+ guard AppGroup.isAvailable else { return false }
+ return AppGroup.defaults.double(forKey: Key.lastSeenAt) > 0
+ }
+
+ /// A short-lived exception that lets the real keyboard complete its first
+ /// voice insertion while the host still owns the onboarding screen.
+ public static var isOnboardingPracticeActive: Bool {
+ onboardingPracticeIsActive()
+ }
+
+ /// Wall clock of the most recent voice insertion issued by the extension.
+ /// The host compares this with the current practice start time, so an old
+ /// insertion can never complete a new onboarding run.
+ public static var lastVoiceInsertionAt: Date? {
+ guard AppGroup.isAvailable else { return nil }
+ let value = AppGroup.defaults.double(forKey: Key.lastVoiceInsertionAt)
+ return value > 0 ? Date(timeIntervalSince1970: value) : nil
+ }
+
+ public static func onboardingPracticeIsActive(
+ defaults: UserDefaults? = nil,
+ now: Date = Date()
+ ) -> Bool {
+ guard let store = defaults ?? AppGroup.defaultsIfAvailable else { return false }
+ return store.double(forKey: Key.onboardingPracticeExpiresAt) > now.timeIntervalSince1970
+ }
+
+ public static func setOnboardingPracticeActive(
+ _ active: Bool,
+ duration: TimeInterval = 30 * 60,
+ defaults: UserDefaults? = nil,
+ now: Date = Date()
+ ) {
+ guard let store = defaults ?? AppGroup.defaultsIfAvailable else { return }
+ if active {
+ store.set(
+ now.addingTimeInterval(duration).timeIntervalSince1970,
+ forKey: Key.onboardingPracticeExpiresAt
+ )
+ } else {
+ store.removeObject(forKey: Key.onboardingPracticeExpiresAt)
+ }
+ AppGroupConfigDarwin.postConfigChanged()
+ }
+
/// Called from the keyboard extension on each appearance.
public static func markExtensionAppearance(hasFullAccess: Bool) {
guard AppGroup.isAvailable else { return }
let defaults = AppGroup.defaults
defaults.set(Date().timeIntervalSince1970, forKey: Key.lastSeenAt)
defaults.set(hasFullAccess, forKey: Key.fullAccessReady)
+ AppGroupConfigDarwin.postConfigChanged()
+ }
+
+ /// Called only after a Flow transcript has been inserted into the host
+ /// field, not when recognition merely produced a result.
+ public static func markVoiceInsertion() {
+ guard AppGroup.isAvailable else { return }
+ AppGroup.defaults.set(
+ Date().timeIntervalSince1970,
+ forKey: Key.lastVoiceInsertionAt
+ )
+ AppGroupConfigDarwin.postConfigChanged()
}
}
diff --git a/OSGKeyboardShared/Services/KeyboardState.swift b/OSGKeyboardShared/Services/KeyboardState.swift
index 911b9af..1efd9e8 100644
--- a/OSGKeyboardShared/Services/KeyboardState.swift
+++ b/OSGKeyboardShared/Services/KeyboardState.swift
@@ -106,6 +106,9 @@ public final class KeyboardState: ObservableObject {
@Published public var flowSessionActive: Bool = false
/// Unified mic color / tap / hint source for the keyboard extension.
@Published public var micVoiceAvailability: MicVoiceAvailability = .unavailable(.hostNotReady)
+ /// Short-lived host-owned practice mode. It unlocks real dictation before
+ /// onboarding completion, but only while the onboarding text field is live.
+ @Published public var isOnboardingPracticeActive: Bool = false
/// When true, the mic is intentionally disabled (e.g. cloud engine
/// selected but the provider-specific API key is missing).
@Published public var micDisabled: Bool = false
diff --git a/OSGKeyboardShared/Services/PolishingService.swift b/OSGKeyboardShared/Services/PolishingService.swift
index 9ac588a..8e42a51 100644
--- a/OSGKeyboardShared/Services/PolishingService.swift
+++ b/OSGKeyboardShared/Services/PolishingService.swift
@@ -54,6 +54,7 @@ public actor PolishingService {
let systemPrompt: String?
let providerIdOverride: String?
let taskKind: ManagedGatewayTaskKind?
+ let requestPurpose: ManagedGatewayRequestPurpose?
let context: PolishContext?
}
@@ -79,6 +80,7 @@ public actor PolishingService {
private let store: any ConfigurationStore
private let timeout: TimeInterval
+ private let analyticsClient: any AnalyticsClient
/// Optional injected client (mostly for testing). When nil we build
/// one from `store.makeClient()` per call.
private let injectedClient: LLMClient?
@@ -91,11 +93,13 @@ public actor PolishingService {
public init(
store: any ConfigurationStore = AppGroupStore(),
client: LLMClient? = nil,
- timeout: TimeInterval? = nil
+ timeout: TimeInterval? = nil,
+ analyticsClient: any AnalyticsClient = NoopAnalyticsClient()
) {
self.store = store
self.injectedClient = client
self.timeout = timeout ?? LLMClientFactory.defaultRequestTimeout
+ self.analyticsClient = analyticsClient
}
/// Context-aware polish entry point. The optional
@@ -110,6 +114,7 @@ public actor PolishingService {
systemPrompt: String? = nil,
providerIdOverride: String? = nil,
taskKind: ManagedGatewayTaskKind? = nil,
+ requestPurpose: ManagedGatewayRequestPurpose? = nil,
context: PolishContext? = nil
) async throws -> String {
try await performPolish(
@@ -119,6 +124,7 @@ public actor PolishingService {
systemPrompt: systemPrompt,
providerIdOverride: providerIdOverride,
taskKind: taskKind,
+ requestPurpose: requestPurpose,
context: context
)
).text
@@ -132,6 +138,7 @@ public actor PolishingService {
systemPrompt: String? = nil,
providerIdOverride: String? = nil,
taskKind: ManagedGatewayTaskKind? = nil,
+ requestPurpose: ManagedGatewayRequestPurpose? = nil,
context: PolishContext? = nil
) async throws -> PolishOutcome {
try await performPolish(
@@ -141,6 +148,7 @@ public actor PolishingService {
systemPrompt: systemPrompt,
providerIdOverride: providerIdOverride,
taskKind: taskKind,
+ requestPurpose: requestPurpose,
context: context
)
)
@@ -152,6 +160,7 @@ public actor PolishingService {
let systemPrompt = request.systemPrompt
let providerIdOverride = request.providerIdOverride
let taskKind = request.taskKind
+ let requestPurpose = request.requestPurpose
let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
guard !trimmed.isEmpty else { throw PolishError.noTranscript }
@@ -185,14 +194,26 @@ public actor PolishingService {
}
}
- let remoteResult = try await polishRemote(
- trimmed,
- mode: mode,
- systemPrompt: systemPrompt,
- providerIdOverride: providerIdOverride,
- taskKind: taskKind,
- context: resolvedContext
+ let operation = analyticsClient.startAIFeature(
+ .polish,
+ executionMode: analyticsExecutionMode
)
+ let remoteResult: RemotePolishResult
+ do {
+ remoteResult = try await polishRemote(
+ trimmed,
+ mode: mode,
+ systemPrompt: systemPrompt,
+ providerIdOverride: providerIdOverride,
+ taskKind: taskKind,
+ requestPurpose: requestPurpose,
+ context: resolvedContext
+ )
+ operation.succeed()
+ } catch {
+ operation.fail(category: Self.analyticsFailureCategory(for: error))
+ throw error
+ }
// Translation and custom prompts bypass the polish post-processor.
if mode != .polish || (systemPrompt != nil && !(systemPrompt?.isEmpty ?? true)) {
@@ -214,6 +235,51 @@ public actor PolishingService {
return override
}
+ private var analyticsExecutionMode: AnalyticsExecutionMode {
+ store.credentialSource == .managed ? .managed : .byok
+ }
+
+ private static func analyticsFailureCategory(
+ for error: Error
+ ) -> AnalyticsFailureCategory {
+ if error is CancellationError {
+ return .cancelled
+ }
+ if let error = error as? PolishError {
+ switch error {
+ case .timeout:
+ return .timeout
+ case .noTranscript, .missingAPIKey, .keychainLocked:
+ return .validation
+ }
+ }
+ if let error = error as? ManagedGatewayError {
+ switch error {
+ case .insufficientCredits:
+ return .insufficientCredits
+ case .timeout:
+ return .timeout
+ case .missingGrant, .scopeNotGranted, .invalidGrant:
+ return .validation
+ case .server:
+ return .provider
+ }
+ }
+ if let error = error as? LLMError {
+ switch error {
+ case .cancelled:
+ return .cancelled
+ case .transport, .rateLimited:
+ return .network
+ case .invalidURL, .noAPIKey, .decoding:
+ return .validation
+ case .http:
+ return .provider
+ }
+ }
+ return .unknown
+ }
+
static func managedGatewayTaskKind(for mode: PolishMode) -> ManagedGatewayTaskKind {
switch mode {
case .polish:
@@ -229,6 +295,7 @@ public actor PolishingService {
systemPrompt: String? = nil,
providerIdOverride: String? = nil,
taskKind: ManagedGatewayTaskKind? = nil,
+ requestPurpose: ManagedGatewayRequestPurpose? = nil,
context: PolishContext
) async throws -> RemotePolishResult {
let effectiveProviderId = Self.resolvedProviderId(
@@ -240,7 +307,8 @@ public actor PolishingService {
client = injectedClient
} else if store.credentialSource == .managed {
client = store.makeClient(
- taskKind: taskKind ?? Self.managedGatewayTaskKind(for: mode)
+ taskKind: taskKind ?? Self.managedGatewayTaskKind(for: mode),
+ requestPurpose: requestPurpose
)
} else {
let preset = LLMProvider.provider(id: effectiveProviderId)
diff --git a/OSGKeyboardTests/AnalyticsAIOperationTests.swift b/OSGKeyboardTests/AnalyticsAIOperationTests.swift
new file mode 100644
index 0000000..45d09c6
--- /dev/null
+++ b/OSGKeyboardTests/AnalyticsAIOperationTests.swift
@@ -0,0 +1,84 @@
+// AnalyticsAIOperationTests.swift
+// OSGKeyboardTests
+//
+// Ordering, duration, and exactly-once terminal semantics for AI operations.
+
+import Foundation
+@testable import OSGKeyboardShared
+import XCTest
+
+final class AnalyticsAIOperationTests: XCTestCase {
+ func testStartedIsPersistedBeforeTerminalWithDurationBucket() async throws {
+ let monotonicClock = AnalyticsTestMonotonicClock(1_000)
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: AnalyticsTestWallClock(),
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ let client = LiveAnalyticsClient(
+ repository: repository,
+ context: analyticsTestContext,
+ monotonicClock: monotonicClock
+ )
+
+ let operation = client.startAIFeature(.polish, executionMode: .managed)
+ monotonicClock.set(4_000_001_000)
+ operation.succeed()
+
+ _ = await analyticsWaitForPendingEventCount(2, repository: repository)
+ let events = try await analyticsDecodePendingEvents(repository: repository)
+ XCTAssertEqual(events.map(\.eventType), [.aiFeatureStarted, .aiFeatureSucceeded])
+ XCTAssertEqual(events.map(\.feature), [.polish, .polish])
+ XCTAssertEqual(events.map(\.executionMode), [.managed, .managed])
+ XCTAssertNil(events[0].durationBucket)
+ XCTAssertEqual(events[1].durationBucket, .threeToTenSeconds)
+ XCTAssertNil(events[1].failureCategory)
+ }
+
+ func testConcurrentTerminalCallsPersistExactlyOneTerminalEvent() async throws {
+ let monotonicClock = AnalyticsTestMonotonicClock(10)
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: AnalyticsTestWallClock(),
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ let client = LiveAnalyticsClient(
+ repository: repository,
+ context: analyticsTestContext,
+ monotonicClock: monotonicClock
+ )
+ let operation = client.startAIFeature(.aiAssistant, executionMode: .local)
+ monotonicClock.set(2_000_000_010)
+
+ await withTaskGroup(of: Void.self) { group in
+ for index in 0..<60 {
+ group.addTask {
+ switch index % 3 {
+ case 0:
+ operation.succeed()
+ case 1:
+ operation.fail(category: .provider)
+ default:
+ operation.cancel()
+ }
+ }
+ }
+ }
+
+ _ = await analyticsWaitForPendingEventCount(2, repository: repository)
+ let events = try await analyticsDecodePendingEvents(repository: repository)
+ XCTAssertEqual(events.first?.eventType, .aiFeatureStarted)
+ XCTAssertEqual(events.count, 2)
+ let terminalEvents = events.filter {
+ [.aiFeatureSucceeded, .aiFeatureFailed].contains($0.eventType)
+ }
+ XCTAssertEqual(terminalEvents.count, 1)
+ XCTAssertEqual(terminalEvents.first?.feature, .aiAssistant)
+ XCTAssertEqual(terminalEvents.first?.executionMode, .local)
+ XCTAssertEqual(terminalEvents.first?.durationBucket, .oneToThreeSeconds)
+ }
+}
diff --git a/OSGKeyboardTests/AnalyticsModelTests.swift b/OSGKeyboardTests/AnalyticsModelTests.swift
new file mode 100644
index 0000000..13b02d8
--- /dev/null
+++ b/OSGKeyboardTests/AnalyticsModelTests.swift
@@ -0,0 +1,165 @@
+// AnalyticsModelTests.swift
+// OSGKeyboardTests
+//
+// Wire-contract and privacy invariants for the allowlisted analytics schema.
+
+import Foundation
+@testable import OSGKeyboardShared
+import XCTest
+
+final class AnalyticsModelTests: XCTestCase {
+ func testEventEncodingContainsOnlyAllowlistedKeysAndNoFreeTextContainer() throws {
+ let event = try AnalyticsEvent(
+ installationId: analyticsTestUUID(1),
+ clientEventId: analyticsTestUUID(2),
+ eventType: .aiFeatureFailed,
+ occurredAt: Date(timeIntervalSince1970: 1_700_000_000.125),
+ surface: .keyboard,
+ appVersion: "2.0.0",
+ osVersion: "26.0",
+ feature: .polish,
+ executionMode: .managed,
+ failureCategory: .network,
+ durationBucket: .oneToThreeSeconds
+ )
+
+ let data = try JSONEncoder().encode(event)
+ let object = try XCTUnwrap(
+ JSONSerialization.jsonObject(with: data) as? [String: Any]
+ )
+
+ XCTAssertEqual(
+ Set(object.keys),
+ [
+ "installationId",
+ "clientEventId",
+ "eventType",
+ "occurredAt",
+ "surface",
+ "appVersion",
+ "osVersion",
+ "feature",
+ "executionMode",
+ "failureCategory",
+ "durationBucket"
+ ]
+ )
+ XCTAssertFalse(object.keys.contains("properties"))
+ XCTAssertFalse(object.keys.contains("text"))
+ XCTAssertEqual(
+ Set(Mirror(reflecting: event).children.compactMap(\.label)),
+ Set(object.keys).union(["acquisitionChannel"])
+ )
+ }
+
+ func testUnknownFieldsAreRejectedAtEveryWireEnvelope() throws {
+ let event = try AnalyticsEvent(
+ installationId: analyticsTestUUID(1),
+ clientEventId: analyticsTestUUID(2),
+ eventType: .sessionStarted,
+ occurredAt: Date(timeIntervalSince1970: 1_700_000_000),
+ surface: .app,
+ appVersion: "2.0.0",
+ osVersion: "26.0"
+ )
+ var eventObject = try XCTUnwrap(
+ JSONSerialization.jsonObject(with: JSONEncoder().encode(event))
+ as? [String: Any]
+ )
+ eventObject["userText"] = "must be rejected"
+ assertUnknownField(
+ try JSONSerialization.data(withJSONObject: eventObject),
+ as: AnalyticsEvent.self,
+ expected: "userText"
+ )
+
+ let request = Data(#"{"events":[],"properties":{"secret":"value"}}"#.utf8)
+ assertUnknownField(
+ request,
+ as: AnalyticsUploadRequest.self,
+ expected: "properties"
+ )
+
+ let response = Data(#"{"accepted":1,"replayed":0,"debug":"secret"}"#.utf8)
+ assertUnknownField(
+ response,
+ as: AnalyticsUploadResponse.self,
+ expected: "debug"
+ )
+ }
+
+ func testEnvironmentFiltersAndTruncatesVersionsToSafeBound() {
+ let environment = AnalyticsEnvironment(
+ appVersion: String(repeating: "a", count: 40) + "/private",
+ osVersion: "26.0 (Build 23A)/用户"
+ )
+
+ XCTAssertEqual(environment.appVersion, String(repeating: "a", count: 32))
+ XCTAssertEqual(environment.appVersion.utf8.count, 32)
+ XCTAssertEqual(environment.osVersion, "26.0Build23A")
+
+ let empty = AnalyticsEnvironment(appVersion: "用户 /", osVersion: "")
+ XCTAssertEqual(empty.appVersion, "unknown")
+ XCTAssertEqual(empty.osVersion, "unknown")
+ }
+
+ func testPurchaseCancelledRequiresCancelledFailureCategory() throws {
+ XCTAssertNoThrow(
+ try AnalyticsEvent(
+ installationId: analyticsTestUUID(1),
+ clientEventId: analyticsTestUUID(2),
+ eventType: .purchaseCancelled,
+ occurredAt: Date(timeIntervalSince1970: 1_700_000_000),
+ surface: .app,
+ appVersion: "2.0.0",
+ osVersion: "26.0",
+ failureCategory: .cancelled
+ )
+ )
+
+ XCTAssertThrowsError(
+ try AnalyticsEvent(
+ installationId: analyticsTestUUID(1),
+ clientEventId: analyticsTestUUID(3),
+ eventType: .purchaseCancelled,
+ occurredAt: Date(timeIntervalSince1970: 1_700_000_000),
+ surface: .app,
+ appVersion: "2.0.0",
+ osVersion: "26.0",
+ failureCategory: .network
+ )
+ ) { error in
+ guard case AnalyticsModelError.invalidDimensions(.purchaseCancelled) = error else {
+ return XCTFail("Unexpected error: \(error)")
+ }
+ }
+ }
+
+ func testDurationBucketBoundariesAreStable() {
+ XCTAssertEqual(AnalyticsDurationBucket(elapsedNanoseconds: 999_999_999), .lessThanOneSecond)
+ XCTAssertEqual(AnalyticsDurationBucket(elapsedNanoseconds: 1_000_000_000), .oneToThreeSeconds)
+ XCTAssertEqual(AnalyticsDurationBucket(elapsedNanoseconds: 2_999_999_999), .oneToThreeSeconds)
+ XCTAssertEqual(AnalyticsDurationBucket(elapsedNanoseconds: 3_000_000_000), .threeToTenSeconds)
+ XCTAssertEqual(AnalyticsDurationBucket(elapsedNanoseconds: 10_000_000_000), .tenToThirtySeconds)
+ XCTAssertEqual(AnalyticsDurationBucket(elapsedNanoseconds: 30_000_000_000), .thirtySecondsOrMore)
+ }
+
+ private func assertUnknownField(
+ _ data: Data,
+ as type: T.Type,
+ expected: String,
+ file: StaticString = #filePath,
+ line: UInt = #line
+ ) {
+ XCTAssertThrowsError(
+ try JSONDecoder().decode(type, from: data),
+ file: file,
+ line: line
+ ) { error in
+ guard case AnalyticsModelError.unknownField(let field) = error else {
+ return XCTFail("Unexpected error: \(error)", file: file, line: line)
+ }
+ XCTAssertEqual(field, expected, file: file, line: line)
+ }
+ }
+}
diff --git a/OSGKeyboardTests/AnalyticsRepositoryTests.swift b/OSGKeyboardTests/AnalyticsRepositoryTests.swift
new file mode 100644
index 0000000..e24ba00
--- /dev/null
+++ b/OSGKeyboardTests/AnalyticsRepositoryTests.swift
@@ -0,0 +1,461 @@
+// AnalyticsRepositoryTests.swift
+// OSGKeyboardTests
+//
+// Durable identity, queue policy, retention, and cross-process lease coverage.
+
+import Foundation
+@testable import OSGKeyboardShared
+import XCTest
+
+final class AnalyticsRepositoryTests: XCTestCase {
+ func testFirstOpenMarkerAndEventAreCreatedExactlyOnceAcrossRestart() async throws {
+ let url = try analyticsTemporaryDatabaseURL()
+ let clock = AnalyticsTestWallClock()
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(databaseURL: url),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+
+ await repository.prepare(
+ using: analyticsTestContext,
+ firstOpenAcquisitionChannel: .referral
+ )
+ await repository.prepare(
+ using: analyticsTestContext,
+ firstOpenAcquisitionChannel: .socialContent
+ )
+
+ let firstSnapshot = await repository.debugSnapshot()
+ XCTAssertTrue(firstSnapshot.firstOpenRecorded)
+ XCTAssertEqual(firstSnapshot.pendingEvents.map(\.eventType), [.firstOpen])
+ let decodedEvents = try await analyticsDecodePendingEvents(repository: repository)
+ let event = try XCTUnwrap(decodedEvents.first)
+ XCTAssertEqual(event.installationId, analyticsTestUUID(1))
+ XCTAssertEqual(event.clientEventId, analyticsTestUUID(2))
+ XCTAssertEqual(event.acquisitionChannel, .referral)
+
+ let restarted = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(databaseURL: url),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: 100)
+ )
+ await restarted.prepare(
+ using: analyticsTestContext,
+ firstOpenAcquisitionChannel: .appStoreOrganic
+ )
+
+ let restartedSnapshot = await restarted.debugSnapshot()
+ XCTAssertEqual(restartedSnapshot.installationID, analyticsTestUUID(1))
+ XCTAssertEqual(restartedSnapshot.pendingEvents.map(\.eventType), [.firstOpen])
+ }
+
+ func testSessionWindowTracksThirtyMinutesOfInactivityPerSurface() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+
+ await repository.recordSessionIfNeeded(context: analyticsTestContext)
+ clock.advance(by: 29 * 60)
+ await repository.recordSessionIfNeeded(context: analyticsTestContext)
+ clock.advance(by: 29 * 60)
+ await repository.recordSessionIfNeeded(context: analyticsTestContext)
+
+ var snapshot = await repository.debugSnapshot()
+ XCTAssertEqual(snapshot.pendingEvents.map(\.eventType), [.sessionStarted])
+
+ clock.advance(by: 30 * 60)
+ await repository.recordSessionIfNeeded(context: analyticsTestContext)
+ snapshot = await repository.debugSnapshot()
+ XCTAssertEqual(
+ snapshot.pendingEvents.compactMap(\.eventType),
+ [.sessionStarted, .sessionStarted]
+ )
+ }
+
+ func testDisableClearsQueuePersistsAcrossRestartAndReenableRotatesIdentity() async throws {
+ let url = try analyticsTemporaryDatabaseURL()
+ let clock = AnalyticsTestWallClock()
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(databaseURL: url),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ await repository.prepare(
+ using: analyticsTestContext,
+ firstOpenAcquisitionChannel: .unknown
+ )
+ let originalID = await repository.debugSnapshot().installationID
+
+ await repository.setEnabled(false)
+ var snapshot = await repository.debugSnapshot()
+ XCTAssertFalse(snapshot.enabled)
+ XCTAssertTrue(snapshot.pendingEvents.isEmpty)
+
+ let restarted = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(databaseURL: url),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: 100)
+ )
+ let remainsDisabled = await restarted.isEnabled()
+ XCTAssertFalse(remainsDisabled)
+ await restarted.record(
+ eventType: .keyboardActivated,
+ context: analyticsTestContext
+ )
+ let disabledSnapshot = await restarted.debugSnapshot()
+ XCTAssertTrue(disabledSnapshot.pendingEvents.isEmpty)
+
+ await restarted.setEnabled(true)
+ await restarted.prepare(
+ using: analyticsTestContext,
+ firstOpenAcquisitionChannel: .referral
+ )
+ await restarted.record(
+ eventType: .keyboardActivated,
+ context: analyticsTestContext
+ )
+ snapshot = await restarted.debugSnapshot()
+ XCTAssertTrue(snapshot.enabled)
+ XCTAssertNotEqual(snapshot.installationID, originalID)
+ XCTAssertTrue(snapshot.firstOpenRecorded)
+ XCTAssertEqual(snapshot.pendingEvents.map(\.eventType), [.keyboardActivated])
+ }
+
+ func testAccountObservationSwitchAndDeletionRotateWithoutRepeatingFirstOpen() async throws {
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: AnalyticsTestWallClock(),
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ await repository.prepare(
+ using: analyticsTestContext,
+ firstOpenAcquisitionChannel: .appStoreOrganic
+ )
+ let installationBeforeAccount = await repository.debugSnapshot().installationID
+
+ let first = await repository.observeAccount(stableIdentifier: "account-a")
+ guard case .firstAccount = first else {
+ return XCTFail("Expected firstAccount, got \(first)")
+ }
+ let installationAfterFirstAccount = await repository.debugSnapshot().installationID
+ XCTAssertEqual(installationAfterFirstAccount, installationBeforeAccount)
+
+ let unchanged = await repository.observeAccount(stableIdentifier: "account-a")
+ guard case .unchanged = unchanged else {
+ return XCTFail("Expected unchanged, got \(unchanged)")
+ }
+
+ await repository.record(
+ eventType: .keyboardActivated,
+ context: analyticsTestContext
+ )
+ let switched = await repository.observeAccount(stableIdentifier: "account-b")
+ guard case .switchedAccount = switched else {
+ return XCTFail("Expected switchedAccount, got \(switched)")
+ }
+ let afterSwitch = await repository.debugSnapshot()
+ XCTAssertNotEqual(afterSwitch.installationID, installationBeforeAccount)
+ XCTAssertTrue(afterSwitch.pendingEvents.isEmpty)
+ XCTAssertTrue(afterSwitch.firstOpenRecorded)
+
+ await repository.record(
+ eventType: .purchaseViewed,
+ context: analyticsTestContext
+ )
+ let switchedID = afterSwitch.installationID
+ await repository.handleAccountDeletion()
+ let afterDeletion = await repository.debugSnapshot()
+ XCTAssertNotEqual(afterDeletion.installationID, switchedID)
+ XCTAssertTrue(afterDeletion.pendingEvents.isEmpty)
+ XCTAssertTrue(afterDeletion.firstOpenRecorded)
+
+ let firstAfterDeletion = await repository.observeAccount(stableIdentifier: "account-b")
+ guard case .firstAccount = firstAfterDeletion else {
+ return XCTFail("Expected firstAccount after deletion, got \(firstAfterDeletion)")
+ }
+ }
+
+ func testRetryPreservesCanonicalPayloadAndClientEventID() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ await analyticsRecordKeyboardEvents(count: 1, repository: repository)
+ let snapshot = await repository.debugSnapshot()
+ let rowID = try XCTUnwrap(snapshot.pendingEvents.first?.rowID)
+ let storedOriginalPayload = await repository.debugPayloadBytes(rowID: rowID)
+ let originalPayload = try XCTUnwrap(storedOriginalPayload)
+ let originalEvent = try JSONDecoder().decode(
+ AnalyticsEvent.self,
+ from: originalPayload
+ )
+ let upload = AnalyticsUploadConfiguration(
+ endpoint: URL(string: "https://analytics.test/events")!
+ )
+ let leasedFirstBatch = await repository.leaseBatch(
+ ownerID: "owner",
+ configuration: upload
+ )
+ let firstLease = try XCTUnwrap(leasedFirstBatch)
+
+ await repository.scheduleRetry(
+ events: firstLease.events,
+ leaseID: firstLease.leaseID,
+ delay: 10
+ )
+ let storedRetriedPayload = await repository.debugPayloadBytes(rowID: rowID)
+ let retriedPayload = try XCTUnwrap(storedRetriedPayload)
+ XCTAssertEqual(retriedPayload, originalPayload)
+ let retrySnapshot = await repository.debugSnapshot()
+ let retryDiagnostic = try XCTUnwrap(retrySnapshot.pendingEvents.first)
+ XCTAssertEqual(retryDiagnostic.attemptCount, 1)
+ XCTAssertEqual(retryDiagnostic.nextAttemptAt, clock.now().addingTimeInterval(10))
+
+ clock.advance(by: 10)
+ let leasedSecondBatch = await repository.leaseBatch(
+ ownerID: "owner",
+ configuration: upload
+ )
+ let secondLease = try XCTUnwrap(leasedSecondBatch)
+ XCTAssertEqual(secondLease.events.first?.payload, originalPayload)
+ let retriedEvent = try JSONDecoder().decode(
+ AnalyticsEvent.self,
+ from: try XCTUnwrap(secondLease.events.first?.payload)
+ )
+ XCTAssertEqual(retriedEvent.clientEventId, originalEvent.clientEventId)
+ }
+
+ func testConcurrentRepositoriesEnforceGlobalLeaseAndRecoverExpiredEventLease() async throws {
+ let url = try analyticsTemporaryDatabaseURL()
+ let clock = AnalyticsTestWallClock()
+ let firstRepository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(databaseURL: url),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ let secondRepository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(databaseURL: url),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: 100)
+ )
+ await analyticsRecordKeyboardEvents(count: 1, repository: firstRepository)
+ let upload = AnalyticsUploadConfiguration(
+ endpoint: URL(string: "https://analytics.test/events")!,
+ globalLeaseDuration: 60,
+ eventLeaseDuration: 60
+ )
+
+ async let first = firstRepository.leaseBatch(
+ ownerID: "first-owner",
+ configuration: upload
+ )
+ async let second = secondRepository.leaseBatch(
+ ownerID: "second-owner",
+ configuration: upload
+ )
+ let simultaneous = await (first, second)
+ XCTAssertEqual([simultaneous.0, simultaneous.1].compactMap { $0 }.count, 1)
+
+ clock.advance(by: 61)
+ let recovered = await secondRepository.leaseBatch(
+ ownerID: "recovery-owner",
+ configuration: upload
+ )
+ XCTAssertEqual(recovered?.events.count, 1)
+ }
+
+ func testCrashAfterServerAcceptanceBeforeDeleteReplaysOriginalBytes() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ await analyticsRecordKeyboardEvents(count: 1, repository: repository)
+ let configuration = AnalyticsUploadConfiguration(
+ endpoint: URL(string: "https://analytics.test/events")!,
+ globalLeaseDuration: 60,
+ eventLeaseDuration: 60
+ )
+ let crashedLease = await repository.leaseBatch(
+ ownerID: "crashed-owner",
+ configuration: configuration
+ )
+ let acceptedButNotDeleted = try XCTUnwrap(crashedLease)
+
+ clock.advance(by: 61)
+ let network = AnalyticsQueueNetwork([
+ .response(analyticsSuccessResponse(accepted: 0, replayed: 1))
+ ])
+ let coordinator = AnalyticsUploadCoordinator(
+ repository: repository,
+ configuration: configuration,
+ network: network,
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: 500),
+ random: AnalyticsTestRandomGenerator()
+ )
+ await coordinator.uploadAvailableEvents()
+
+ let requests = await network.requests()
+ XCTAssertEqual(requests.single?.body, acceptedButNotDeleted.body)
+ let completedSnapshot = await repository.debugSnapshot()
+ XCTAssertTrue(completedSnapshot.pendingEvents.isEmpty)
+ }
+
+ func testBatchHonorsFiftyEventAndDynamicBodyByteLimits() async throws {
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: AnalyticsTestWallClock(),
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ await analyticsRecordKeyboardEvents(count: 55, repository: repository)
+ let defaultUpload = AnalyticsUploadConfiguration(
+ endpoint: URL(string: "https://analytics.test/events")!,
+ maximumBatchCount: 100,
+ maximumBodyBytes: 100_000
+ )
+ let countLease = await repository.leaseBatch(
+ ownerID: "count",
+ configuration: defaultUpload
+ )
+ let countLimited = try XCTUnwrap(countLease)
+ XCTAssertEqual(countLimited.events.count, 50)
+ XCTAssertLessThanOrEqual(countLimited.body.count, 60 * 1_024)
+
+ await repository.releaseEvents(
+ countLimited.events,
+ leaseID: countLimited.leaseID
+ )
+ await repository.releaseGlobalLease(ownerID: "count")
+
+ let byteUpload = AnalyticsUploadConfiguration(
+ endpoint: URL(string: "https://analytics.test/events")!,
+ maximumBatchCount: 50,
+ maximumBodyBytes: 1_024
+ )
+ let byteLease = await repository.leaseBatch(
+ ownerID: "bytes",
+ configuration: byteUpload
+ )
+ let byteLimited = try XCTUnwrap(byteLease)
+ XCTAssertFalse(byteLimited.events.isEmpty)
+ XCTAssertLessThan(byteLimited.events.count, 50)
+ XCTAssertLessThanOrEqual(byteLimited.body.count, 1_024)
+ let snapshot = await repository.debugSnapshot()
+ let selectedIDs = Set(byteLimited.events.map(\.rowID))
+ let nextDiagnostic = try XCTUnwrap(
+ snapshot.pendingEvents.first { !selectedIDs.contains($0.rowID) }
+ )
+ let storedNextPayload = await repository.debugPayloadBytes(
+ rowID: nextDiagnostic.rowID
+ )
+ let nextPayload = try XCTUnwrap(storedNextPayload)
+ XCTAssertGreaterThan(byteLimited.body.count + 1 + nextPayload.count, 1_024)
+ }
+
+ func testRetentionExpiresAfterThirtyFourDaysAndToleratesClockRollback() async throws {
+ let retention = 34 * 24 * 60 * 60.0
+ let clock = AnalyticsTestWallClock()
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL(),
+ eventRetention: retention
+ ),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ await repository.record(
+ eventType: .keyboardActivated,
+ context: analyticsTestContext
+ )
+
+ clock.advance(by: retention)
+ await repository.record(
+ eventType: .purchaseViewed,
+ context: analyticsTestContext
+ )
+ let boundarySnapshot = await repository.debugSnapshot()
+ XCTAssertEqual(boundarySnapshot.pendingEvents.count, 2)
+
+ clock.advance(by: 0.001)
+ await repository.record(
+ eventType: .purchaseStarted,
+ context: analyticsTestContext
+ )
+ var events = try await analyticsDecodePendingEvents(repository: repository)
+ XCTAssertEqual(Set(events.map(\.eventType)), [.purchaseViewed, .purchaseStarted])
+
+ let future = clock.now().addingTimeInterval(24 * 60 * 60)
+ clock.set(future)
+ await repository.record(
+ eventType: .referralShared,
+ context: analyticsTestContext
+ )
+ clock.set(future.addingTimeInterval(-7 * 24 * 60 * 60))
+ let upload = AnalyticsUploadConfiguration(
+ endpoint: URL(string: "https://analytics.test/events")!
+ )
+ let batch = await repository.leaseBatch(ownerID: "rollback", configuration: upload)
+ events = try batch?.events.map {
+ try JSONDecoder().decode(AnalyticsEvent.self, from: $0.payload)
+ } ?? []
+ XCTAssertTrue(events.contains(where: { $0.eventType == .referralShared }))
+ }
+
+ func testCapacityEvictsSessionAndKeyboardBeforeHighValueEvents() async throws {
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL(),
+ maximumEventCount: 2
+ ),
+ clock: AnalyticsTestWallClock(),
+ uuidGenerator: AnalyticsTestUUIDGenerator()
+ )
+ await repository.prepare(
+ using: analyticsTestContext,
+ firstOpenAcquisitionChannel: .unknown
+ )
+ await repository.recordSessionIfNeeded(context: analyticsTestContext)
+ await repository.record(
+ eventType: .keyboardActivated,
+ context: analyticsTestContext
+ )
+ var eventTypes = await repository.debugSnapshot().pendingEvents.compactMap(\.eventType)
+ XCTAssertEqual(Set(eventTypes), [.firstOpen, .keyboardActivated])
+
+ await repository.record(
+ eventType: .aiFeatureSucceeded,
+ context: analyticsTestContext,
+ dimensions: AnalyticsEventDimensions(
+ feature: .polish,
+ executionMode: .managed,
+ durationBucket: .oneToThreeSeconds
+ )
+ )
+ eventTypes = await repository.debugSnapshot().pendingEvents.compactMap(\.eventType)
+ XCTAssertEqual(Set(eventTypes), [.firstOpen, .aiFeatureSucceeded])
+ }
+}
+
+private extension Array {
+ var single: Element? {
+ count == 1 ? first : nil
+ }
+}
diff --git a/OSGKeyboardTests/AnalyticsTestSupport.swift b/OSGKeyboardTests/AnalyticsTestSupport.swift
new file mode 100644
index 0000000..00732c4
--- /dev/null
+++ b/OSGKeyboardTests/AnalyticsTestSupport.swift
@@ -0,0 +1,267 @@
+// AnalyticsTestSupport.swift
+// OSGKeyboardTests
+//
+// Deterministic analytics clocks, identifiers, transport doubles, and fixtures.
+
+import Foundation
+@testable import OSGKeyboardShared
+import XCTest
+
+let analyticsTestContext = AnalyticsBootstrapContext(
+ surface: .app,
+ environment: AnalyticsEnvironment(appVersion: "2.0.0", osVersion: "26.0")
+)
+
+func analyticsTestUUID(_ value: Int) -> UUID {
+ UUID(uuidString: String(format: "00000000-0000-0000-0000-%012x", value))!
+}
+
+func analyticsTemporaryDatabaseURL() throws -> URL {
+ let directory = FileManager.default.temporaryDirectory
+ .appendingPathComponent("OSGKeyboardAnalyticsTests", isDirectory: true)
+ .appendingPathComponent(UUID().uuidString, isDirectory: true)
+ try FileManager.default.createDirectory(
+ at: directory,
+ withIntermediateDirectories: true
+ )
+ return directory.appendingPathComponent("analytics.sqlite3")
+}
+
+final class AnalyticsTestWallClock: AnalyticsWallClock, @unchecked Sendable {
+ private let lock = NSLock()
+ private var value: Date
+
+ init(_ value: Date = Date(timeIntervalSince1970: 1_700_000_000)) {
+ self.value = value
+ }
+
+ func now() -> Date {
+ lock.withLock { value }
+ }
+
+ func set(_ value: Date) {
+ lock.withLock { self.value = value }
+ }
+
+ func advance(by interval: TimeInterval) {
+ lock.withLock { value = value.addingTimeInterval(interval) }
+ }
+}
+
+final class AnalyticsTestMonotonicClock: AnalyticsMonotonicClock, @unchecked Sendable {
+ private let lock = NSLock()
+ private var value: UInt64
+
+ init(_ value: UInt64 = 0) {
+ self.value = value
+ }
+
+ func nowNanoseconds() -> UInt64 {
+ lock.withLock { value }
+ }
+
+ func set(_ value: UInt64) {
+ lock.withLock { self.value = value }
+ }
+}
+
+final class AnalyticsTestUUIDGenerator: AnalyticsUUIDGenerating, @unchecked Sendable {
+ private let lock = NSLock()
+ private var nextValue: Int
+
+ init(startingAt value: Int = 1) {
+ nextValue = value
+ }
+
+ func makeUUID() -> UUID {
+ lock.withLock {
+ defer { nextValue += 1 }
+ return analyticsTestUUID(nextValue)
+ }
+ }
+}
+
+final class AnalyticsTestRandomGenerator: AnalyticsRandomGenerating, @unchecked Sendable {
+ enum Value {
+ case zero
+ case upperBound
+ case fixed(UInt64)
+ }
+
+ private let value: Value
+
+ init(_ value: Value = .zero) {
+ self.value = value
+ }
+
+ func next(upperBound: UInt64) -> UInt64 {
+ switch value {
+ case .zero:
+ return 0
+ case .upperBound:
+ return upperBound
+ case .fixed(let fixed):
+ return min(fixed, upperBound)
+ }
+ }
+}
+
+actor AnalyticsQueueNetwork: AnalyticsNetworking {
+ enum Outcome: Sendable {
+ case response(AnalyticsHTTPResponse)
+ case urlError(URLError.Code)
+ }
+
+ private var outcomes: [Outcome]
+ private var capturedRequests: [AnalyticsHTTPRequest] = []
+
+ init(_ outcomes: [Outcome]) {
+ self.outcomes = outcomes
+ }
+
+ func send(_ request: AnalyticsHTTPRequest) async throws -> AnalyticsHTTPResponse {
+ capturedRequests.append(request)
+ guard !outcomes.isEmpty else {
+ return AnalyticsHTTPResponse(statusCode: 500, headers: [:], body: Data())
+ }
+ switch outcomes.removeFirst() {
+ case .response(let response):
+ return response
+ case .urlError(let code):
+ throw URLError(code)
+ }
+ }
+
+ func requests() -> [AnalyticsHTTPRequest] {
+ capturedRequests
+ }
+}
+
+actor AnalyticsPoisonNetwork: AnalyticsNetworking {
+ private let statusCode: Int
+ private let poisonID: UUID
+ private var capturedRequests: [AnalyticsHTTPRequest] = []
+
+ init(statusCode: Int, poisonID: UUID) {
+ self.statusCode = statusCode
+ self.poisonID = poisonID
+ }
+
+ func send(_ request: AnalyticsHTTPRequest) async throws -> AnalyticsHTTPResponse {
+ capturedRequests.append(request)
+ let upload = try JSONDecoder().decode(AnalyticsUploadRequest.self, from: request.body)
+ if upload.events.contains(where: { $0.clientEventId == poisonID }) {
+ return AnalyticsHTTPResponse(statusCode: statusCode, headers: [:], body: Data())
+ }
+ return analyticsSuccessResponse(accepted: upload.events.count)
+ }
+
+ func requests() -> [AnalyticsHTTPRequest] {
+ capturedRequests
+ }
+}
+
+actor AnalyticsTestBearerProvider: AnalyticsBearerProviding {
+ private let initialToken: String?
+ private let refreshedToken: String?
+ private var refreshInputs: [String?] = []
+
+ init(initialToken: String?, refreshedToken: String?) {
+ self.initialToken = initialToken
+ self.refreshedToken = refreshedToken
+ }
+
+ func bearerToken() async throws -> String? {
+ initialToken
+ }
+
+ func refreshBearerToken(
+ afterUnauthorizedAccessToken failedToken: String?
+ ) async throws -> String? {
+ refreshInputs.append(failedToken)
+ return refreshedToken
+ }
+
+ func recordedRefreshInputs() -> [String?] {
+ refreshInputs
+ }
+}
+
+func analyticsSuccessResponse(
+ accepted: Int,
+ replayed: Int = 0
+) -> AnalyticsHTTPResponse {
+ AnalyticsHTTPResponse(
+ statusCode: 200,
+ headers: [:],
+ body: Data(#"{"accepted":\#(accepted),"replayed":\#(replayed)}"#.utf8)
+ )
+}
+
+func analyticsHTTPResponse(
+ statusCode: Int,
+ headers: [String: String] = [:],
+ body: Data = Data()
+) -> AnalyticsHTTPResponse {
+ AnalyticsHTTPResponse(statusCode: statusCode, headers: headers, body: body)
+}
+
+func analyticsRecordKeyboardEvents(
+ count: Int,
+ repository: AnalyticsRepository,
+ context: AnalyticsBootstrapContext = analyticsTestContext
+) async {
+ for _ in 0.. [Data] {
+ let snapshot = await repository.debugSnapshot()
+ var payloads: [Data] = []
+ for diagnostic in snapshot.pendingEvents {
+ let payload = await repository.debugPayloadBytes(rowID: diagnostic.rowID)
+ payloads.append(try XCTUnwrap(payload))
+ }
+ return payloads
+}
+
+func analyticsDecodePendingEvents(
+ repository: AnalyticsRepository
+) async throws -> [AnalyticsEvent] {
+ let payloads = try await analyticsPendingPayloads(repository: repository)
+ return try payloads.map { try JSONDecoder().decode(AnalyticsEvent.self, from: $0) }
+}
+
+func analyticsRequestBody(payloads: [Data]) -> Data {
+ var body = Data(#"{"events":["#.utf8)
+ for index in payloads.indices {
+ if index > 0 {
+ body.append(UInt8(ascii: ","))
+ }
+ body.append(payloads[index])
+ }
+ body.append(Data("]}".utf8))
+ return body
+}
+
+func analyticsWaitForPendingEventCount(
+ _ count: Int,
+ repository: AnalyticsRepository,
+ timeoutIterations: Int = 200
+) async -> AnalyticsRepositoryDebugSnapshot {
+ for _ in 0..= count {
+ return snapshot
+ }
+ try? await Task.sleep(for: .milliseconds(10))
+ }
+ XCTFail("Timed out waiting for \(count) analytics events")
+ return await repository.debugSnapshot()
+}
diff --git a/OSGKeyboardTests/AnalyticsUploadCoordinatorTests.swift b/OSGKeyboardTests/AnalyticsUploadCoordinatorTests.swift
new file mode 100644
index 0000000..240a840
--- /dev/null
+++ b/OSGKeyboardTests/AnalyticsUploadCoordinatorTests.swift
@@ -0,0 +1,308 @@
+// AnalyticsUploadCoordinatorTests.swift
+// OSGKeyboardTests
+//
+// HTTP outcome, authentication, retry, and poison-event isolation coverage.
+
+import Foundation
+@testable import OSGKeyboardShared
+import XCTest
+
+final class AnalyticsUploadCoordinatorTests: XCTestCase {
+ private let endpoint = URL(string: "https://analytics.test/v1/events")!
+
+ func testExactAcceptedAndReplayedCountDeletesUsingOriginalPayloadBytes() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = try await makeRepository(clock: clock, eventCount: 2)
+ let payloads = try await analyticsPendingPayloads(repository: repository)
+ let expectedBody = analyticsRequestBody(payloads: payloads)
+ let network = AnalyticsQueueNetwork([
+ .response(analyticsSuccessResponse(accepted: 1, replayed: 1))
+ ])
+ let coordinator = makeCoordinator(
+ repository: repository,
+ network: network,
+ clock: clock
+ )
+
+ await coordinator.uploadAvailableEvents()
+
+ let snapshot = await repository.debugSnapshot()
+ XCTAssertTrue(snapshot.pendingEvents.isEmpty)
+ let requests = await network.requests()
+ let request = try XCTUnwrap(requests.first)
+ XCTAssertEqual(requests.count, 1)
+ XCTAssertEqual(request.body, expectedBody)
+ XCTAssertEqual(request.url, endpoint)
+ XCTAssertEqual(request.headers["Content-Type"], "application/json")
+ XCTAssertNil(request.headers["Authorization"])
+ let topLevel = try XCTUnwrap(
+ JSONSerialization.jsonObject(with: request.body) as? [String: Any]
+ )
+ XCTAssertEqual(Set(topLevel.keys), ["events"])
+ XCTAssertEqual((topLevel["events"] as? [Any])?.count, 2)
+ }
+
+ func testCountMismatchRetriesWithoutMutatingPayloadOrEventID() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = try await makeRepository(clock: clock, eventCount: 2)
+ let originalPayloads = try await analyticsPendingPayloads(repository: repository)
+ let originalIDs = try originalPayloads.map {
+ try JSONDecoder().decode(AnalyticsEvent.self, from: $0).clientEventId
+ }
+ let network = AnalyticsQueueNetwork([
+ .response(analyticsSuccessResponse(accepted: 1, replayed: 0))
+ ])
+ let coordinator = makeCoordinator(
+ repository: repository,
+ network: network,
+ clock: clock,
+ random: AnalyticsTestRandomGenerator(.upperBound)
+ )
+
+ await coordinator.uploadAvailableEvents()
+
+ let snapshot = await repository.debugSnapshot()
+ XCTAssertEqual(snapshot.pendingEvents.map(\.attemptCount), [1, 1])
+ XCTAssertEqual(
+ snapshot.pendingEvents.map(\.nextAttemptAt),
+ [clock.now().addingTimeInterval(1), clock.now().addingTimeInterval(1)]
+ )
+ let retriedPayloads = try await analyticsPendingPayloads(repository: repository)
+ XCTAssertEqual(retriedPayloads, originalPayloads)
+ let retriedIDs = try retriedPayloads.map {
+ try JSONDecoder().decode(AnalyticsEvent.self, from: $0).clientEventId
+ }
+ XCTAssertEqual(retriedIDs, originalIDs)
+ }
+
+ func testNetwork408429And5xxScheduleBoundedBackoff() async throws {
+ let cases: [(AnalyticsQueueNetwork.Outcome, TimeInterval)] = [
+ (.urlError(.notConnectedToInternet), 1),
+ (.response(analyticsHTTPResponse(statusCode: 408)), 1),
+ (
+ .response(
+ analyticsHTTPResponse(
+ statusCode: 429,
+ headers: ["rEtRy-AfTeR": "120"]
+ )
+ ),
+ 120
+ ),
+ (.response(analyticsHTTPResponse(statusCode: 503)), 1)
+ ]
+
+ for (index, testCase) in cases.enumerated() {
+ let clock = AnalyticsTestWallClock()
+ let repository = try await makeRepository(
+ clock: clock,
+ eventCount: 1,
+ uuidStart: 100 * (index + 1)
+ )
+ let originalPayloads = try await analyticsPendingPayloads(
+ repository: repository
+ )
+ let originalPayload = try XCTUnwrap(originalPayloads.first)
+ let network = AnalyticsQueueNetwork([testCase.0])
+ let coordinator = makeCoordinator(
+ repository: repository,
+ network: network,
+ clock: clock,
+ random: AnalyticsTestRandomGenerator(.upperBound)
+ )
+
+ await coordinator.uploadAvailableEvents()
+
+ let snapshot = await repository.debugSnapshot()
+ let diagnostic = try XCTUnwrap(snapshot.pendingEvents.first)
+ XCTAssertEqual(diagnostic.attemptCount, 1, "case \(index)")
+ XCTAssertEqual(
+ diagnostic.nextAttemptAt,
+ clock.now().addingTimeInterval(testCase.1),
+ "case \(index)"
+ )
+ let storedPayload = await repository.debugPayloadBytes(rowID: diagnostic.rowID)
+ XCTAssertEqual(storedPayload, originalPayload, "case \(index)")
+ }
+ }
+
+ func testUnauthorizedRefreshesOnceAndRetriesWithNewAuthorization() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = try await makeRepository(clock: clock, eventCount: 1)
+ let network = AnalyticsQueueNetwork([
+ .response(analyticsHTTPResponse(statusCode: 401)),
+ .response(analyticsSuccessResponse(accepted: 1))
+ ])
+ let bearer = AnalyticsTestBearerProvider(
+ initialToken: "old-token",
+ refreshedToken: "new-token"
+ )
+ let coordinator = AnalyticsUploadCoordinator(
+ repository: repository,
+ configuration: uploadConfiguration(),
+ network: network,
+ bearerProvider: bearer,
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: 5_000),
+ random: AnalyticsTestRandomGenerator()
+ )
+
+ await coordinator.uploadAvailableEvents()
+
+ let requests = await network.requests()
+ XCTAssertEqual(requests.count, 2)
+ XCTAssertEqual(requests[0].headers["Authorization"], "Bearer old-token")
+ XCTAssertEqual(requests[1].headers["Authorization"], "Bearer new-token")
+ XCTAssertEqual(requests[0].body, requests[1].body)
+ let refreshInputs = await bearer.recordedRefreshInputs()
+ XCTAssertEqual(refreshInputs.count, 1)
+ XCTAssertEqual(refreshInputs[0], "old-token")
+ let snapshot = await repository.debugSnapshot()
+ XCTAssertTrue(snapshot.pendingEvents.isEmpty)
+ }
+
+ func testSecondUnauthorizedDoesNotRefreshAgainAndSchedulesLongRetry() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = try await makeRepository(clock: clock, eventCount: 1)
+ let network = AnalyticsQueueNetwork([
+ .response(analyticsHTTPResponse(statusCode: 401)),
+ .response(analyticsHTTPResponse(statusCode: 401))
+ ])
+ let bearer = AnalyticsTestBearerProvider(
+ initialToken: "old-token",
+ refreshedToken: "new-token"
+ )
+ let configuration = uploadConfiguration(maximumBackoff: 600)
+ let coordinator = AnalyticsUploadCoordinator(
+ repository: repository,
+ configuration: configuration,
+ network: network,
+ bearerProvider: bearer,
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: 5_000),
+ random: AnalyticsTestRandomGenerator(.upperBound)
+ )
+
+ await coordinator.uploadAvailableEvents()
+
+ let refreshInputs = await bearer.recordedRefreshInputs()
+ XCTAssertEqual(refreshInputs.count, 1)
+ let snapshot = await repository.debugSnapshot()
+ XCTAssertEqual(snapshot.pendingEvents.first?.attemptCount, 1)
+ XCTAssertEqual(
+ snapshot.pendingEvents.first?.nextAttemptAt,
+ clock.now().addingTimeInterval(600)
+ )
+ }
+
+ func testValidationStatusesRecursivelyIsolateOnlyPoisonEvent() async throws {
+ for statusCode in [400, 409, 422] {
+ let clock = AnalyticsTestWallClock()
+ let repository = try await makeRepository(
+ clock: clock,
+ eventCount: 4,
+ uuidStart: statusCode
+ )
+ let events = try await analyticsDecodePendingEvents(repository: repository)
+ let poisonID = try XCTUnwrap(events.dropFirst().first?.clientEventId)
+ let network = AnalyticsPoisonNetwork(
+ statusCode: statusCode,
+ poisonID: poisonID
+ )
+ let coordinator = makeCoordinator(
+ repository: repository,
+ network: network,
+ clock: clock
+ )
+
+ await coordinator.uploadAvailableEvents()
+
+ let snapshot = await repository.debugSnapshot()
+ XCTAssertTrue(snapshot.pendingEvents.isEmpty, "HTTP \(statusCode)")
+ XCTAssertEqual(snapshot.quarantinedEvents.count, 1, "HTTP \(statusCode)")
+ XCTAssertEqual(
+ snapshot.quarantinedEvents.first?.reason,
+ "http\(statusCode)"
+ )
+ let quarantinedRowID = try XCTUnwrap(
+ snapshot.quarantinedEvents.first?.rowID
+ )
+ let quarantinedPayload = await repository.debugPayloadBytes(
+ rowID: quarantinedRowID,
+ quarantined: true
+ )
+ let quarantinedEvent = try JSONDecoder().decode(
+ AnalyticsEvent.self,
+ from: try XCTUnwrap(quarantinedPayload)
+ )
+ XCTAssertEqual(quarantinedEvent.clientEventId, poisonID)
+ let requests = await network.requests()
+ XCTAssertGreaterThan(requests.count, 1)
+ }
+ }
+
+ func testOtherPermanent4xxQuarantinesWholeBatchWithoutRetry() async throws {
+ let clock = AnalyticsTestWallClock()
+ let repository = try await makeRepository(clock: clock, eventCount: 3)
+ let network = AnalyticsQueueNetwork([
+ .response(analyticsHTTPResponse(statusCode: 403))
+ ])
+ let coordinator = makeCoordinator(
+ repository: repository,
+ network: network,
+ clock: clock
+ )
+
+ await coordinator.uploadAvailableEvents()
+
+ let snapshot = await repository.debugSnapshot()
+ XCTAssertTrue(snapshot.pendingEvents.isEmpty)
+ XCTAssertEqual(snapshot.quarantinedEvents.count, 3)
+ XCTAssertEqual(Set(snapshot.quarantinedEvents.map(\.reason)), ["http403"])
+ let requests = await network.requests()
+ XCTAssertEqual(requests.count, 1)
+ }
+
+ private func makeRepository(
+ clock: AnalyticsTestWallClock,
+ eventCount: Int,
+ uuidStart: Int = 1
+ ) async throws -> AnalyticsRepository {
+ let repository = AnalyticsRepository(
+ configuration: AnalyticsRepositoryConfiguration(
+ databaseURL: try analyticsTemporaryDatabaseURL()
+ ),
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: uuidStart)
+ )
+ await analyticsRecordKeyboardEvents(
+ count: eventCount,
+ repository: repository
+ )
+ return repository
+ }
+
+ private func uploadConfiguration(
+ maximumBackoff: TimeInterval = 600
+ ) -> AnalyticsUploadConfiguration {
+ AnalyticsUploadConfiguration(
+ endpoint: endpoint,
+ maximumBackoff: maximumBackoff
+ )
+ }
+
+ private func makeCoordinator(
+ repository: AnalyticsRepository,
+ network: some AnalyticsNetworking,
+ clock: AnalyticsTestWallClock,
+ random: AnalyticsTestRandomGenerator = AnalyticsTestRandomGenerator()
+ ) -> AnalyticsUploadCoordinator {
+ AnalyticsUploadCoordinator(
+ repository: repository,
+ configuration: uploadConfiguration(),
+ network: network,
+ clock: clock,
+ uuidGenerator: AnalyticsTestUUIDGenerator(startingAt: 5_000),
+ random: random
+ )
+ }
+}
diff --git a/OSGKeyboardTests/AppGroupOnboardingStoreTests.swift b/OSGKeyboardTests/AppGroupOnboardingStoreTests.swift
index 78db976..1b04726 100644
--- a/OSGKeyboardTests/AppGroupOnboardingStoreTests.swift
+++ b/OSGKeyboardTests/AppGroupOnboardingStoreTests.swift
@@ -62,6 +62,50 @@ final class AppGroupOnboardingStoreTests: XCTestCase {
XCTAssertEqual(store3.onboardingPage, 0)
}
+ func testOnboardingPracticeWindowExpires() {
+ let now = Date(timeIntervalSince1970: 1_000)
+ KeyboardSetupBridge.setOnboardingPracticeActive(
+ true,
+ duration: 30,
+ defaults: defaults,
+ now: now
+ )
+
+ XCTAssertTrue(
+ KeyboardSetupBridge.onboardingPracticeIsActive(
+ defaults: defaults,
+ now: now.addingTimeInterval(29)
+ )
+ )
+ XCTAssertFalse(
+ KeyboardSetupBridge.onboardingPracticeIsActive(
+ defaults: defaults,
+ now: now.addingTimeInterval(31)
+ )
+ )
+ }
+
+ func testDisablingOnboardingPracticeClearsWindow() {
+ let now = Date(timeIntervalSince1970: 1_000)
+ KeyboardSetupBridge.setOnboardingPracticeActive(
+ true,
+ defaults: defaults,
+ now: now
+ )
+ KeyboardSetupBridge.setOnboardingPracticeActive(
+ false,
+ defaults: defaults,
+ now: now
+ )
+
+ XCTAssertFalse(
+ KeyboardSetupBridge.onboardingPracticeIsActive(
+ defaults: defaults,
+ now: now
+ )
+ )
+ }
+
// MARK: - App context detection round-trip
func testDetectedAppContextRoundTrip() throws {
diff --git a/OSGKeyboardTests/FlowHomePiPStatusPolicyTests.swift b/OSGKeyboardTests/FlowHomePiPStatusPolicyTests.swift
new file mode 100644
index 0000000..783e49b
--- /dev/null
+++ b/OSGKeyboardTests/FlowHomePiPStatusPolicyTests.swift
@@ -0,0 +1,97 @@
+// FlowHomePiPStatusPolicyTests.swift
+// OSGKeyboardTests
+
+@testable import OSGKeyboard
+import XCTest
+
+final class FlowHomePiPStatusPolicyTests: XCTestCase {
+
+ func testPreparingAndRecoveringExposeAttemptProgress() {
+ XCTAssertEqual(
+ descriptor(for: .preparing(attempt: 1, total: 3)),
+ .progress(
+ localizationKey: "home.flow.preparingProgress",
+ attempt: 1,
+ total: 3
+ )
+ )
+ XCTAssertEqual(
+ descriptor(for: .recovering(attempt: 2, total: 3)),
+ .progress(
+ localizationKey: "home.flow.recoveringProgress",
+ attempt: 2,
+ total: 3
+ )
+ )
+ }
+
+ func testTakeoverAndFailureUseActionableStatuses() {
+ XCTAssertEqual(
+ descriptor(for: .waitingForForeground),
+ .text(localizationKey: "home.flow.waitingForForeground")
+ )
+ XCTAssertEqual(
+ descriptor(for: .failed(.systemRejected)),
+ .text(localizationKey: "home.flow.recoveryFailed")
+ )
+ }
+
+ func testActiveSessionDoesNotClaimReadyWithoutReadyContract() {
+ XCTAssertEqual(
+ FlowHomePiPStatusPolicy.descriptor(
+ lifecycle: .active,
+ isStarting: false,
+ isRecording: false,
+ isProcessing: false,
+ isActive: true,
+ isHostReady: false
+ ),
+ .text(localizationKey: "home.flow.notReady")
+ )
+ XCTAssertEqual(
+ FlowHomePiPStatusPolicy.descriptor(
+ lifecycle: .active,
+ isStarting: false,
+ isRecording: false,
+ isProcessing: false,
+ isActive: true,
+ isHostReady: true
+ ),
+ .text(localizationKey: "home.flow.label")
+ )
+ }
+
+ func testRetryAppearsOnlyForRecoverableFailureWithPermissions() {
+ XCTAssertTrue(
+ FlowHomePiPStatusPolicy.canRetry(
+ lifecycle: .failed(.timedOut),
+ needsPermissionSetup: false
+ )
+ )
+ XCTAssertFalse(
+ FlowHomePiPStatusPolicy.canRetry(
+ lifecycle: .failed(.timedOut),
+ needsPermissionSetup: true
+ )
+ )
+ XCTAssertFalse(
+ FlowHomePiPStatusPolicy.canRetry(
+ lifecycle: .recovering(attempt: 1, total: 3),
+ needsPermissionSetup: false
+ )
+ )
+ }
+
+ private func descriptor(
+ for lifecycle: FlowPiPLifecycleState
+ ) -> FlowHomePiPStatusDescriptor {
+ FlowHomePiPStatusPolicy.descriptor(
+ lifecycle: lifecycle,
+ isStarting: false,
+ isRecording: false,
+ isProcessing: false,
+ isActive: false,
+ isHostReady: false
+ )
+ }
+}
diff --git a/OSGKeyboardTests/FlowPiPRecoveryPolicyTests.swift b/OSGKeyboardTests/FlowPiPRecoveryPolicyTests.swift
new file mode 100644
index 0000000..dd0b2d1
--- /dev/null
+++ b/OSGKeyboardTests/FlowPiPRecoveryPolicyTests.swift
@@ -0,0 +1,149 @@
+// FlowPiPRecoveryPolicyTests.swift
+// OSGKeyboardTests
+
+@testable import OSGKeyboard
+import XCTest
+
+final class FlowPiPRecoveryPolicyTests: XCTestCase {
+
+ // MARK: - Reconciliation
+
+ func testNoSessionIntentNeverStartsRecovery() {
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.reconciliationDecision(
+ wantsActiveSession: false,
+ isAppForeground: true,
+ isPictureInPictureActive: false
+ ),
+ .noSessionIntent
+ )
+ }
+
+ func testActivePiPIsIdempotent() {
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.reconciliationDecision(
+ wantsActiveSession: true,
+ isAppForeground: true,
+ isPictureInPictureActive: true
+ ),
+ .alreadyActive
+ )
+ }
+
+ func testTakeoverWaitsWhileAppIsInBackground() {
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.reconciliationDecision(
+ wantsActiveSession: true,
+ isAppForeground: false,
+ isPictureInPictureActive: false
+ ),
+ .waitForForeground
+ )
+ }
+
+ func testReturningToForegroundStartsRecovery() {
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.reconciliationDecision(
+ wantsActiveSession: true,
+ isAppForeground: true,
+ isPictureInPictureActive: false
+ ),
+ .startRecovery
+ )
+ }
+
+ // MARK: - Bounded retry
+
+ func testRetryPolicyUsesThreeIncreasingBoundedAttempts() {
+ XCTAssertEqual(FlowPiPRecoveryPolicy.maxAttempts, 3)
+ XCTAssertEqual(
+ (1...FlowPiPRecoveryPolicy.maxAttempts).map {
+ FlowPiPRecoveryPolicy.retryDelay(beforeAttempt: $0)
+ },
+ [0, 0.25, 0.6]
+ )
+ XCTAssertEqual(FlowPiPRecoveryPolicy.totalBudget, 5)
+ }
+
+ func testRetryTimeoutsNeverExceedRemainingBudget() {
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.hostTimeout(attempt: 1, remainingBudget: 0.4),
+ 0.4
+ )
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.hostTimeout(attempt: 2, remainingBudget: 4),
+ 0.25
+ )
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.activeTimeout(remainingBudget: 0.3),
+ 0.3
+ )
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.activeTimeout(remainingBudget: 4),
+ 1.4
+ )
+ XCTAssertEqual(
+ FlowPiPRecoveryPolicy.activeTimeout(remainingBudget: 0.01),
+ 0.01
+ )
+ }
+
+ // MARK: - Late completion safety
+
+ func testCurrentForegroundOperationCanContinue() {
+ XCTAssertTrue(
+ FlowPiPRecoveryPolicy.canContinue(
+ operation: 7,
+ currentOperation: 7,
+ wantsActiveSession: true,
+ isAppForeground: true,
+ taskIsCancelled: false
+ )
+ )
+ }
+
+ func testOldGenerationCannotOverwriteNewRecovery() {
+ XCTAssertFalse(
+ FlowPiPRecoveryPolicy.canContinue(
+ operation: 6,
+ currentOperation: 7,
+ wantsActiveSession: true,
+ isAppForeground: true,
+ taskIsCancelled: false
+ )
+ )
+ }
+
+ func testExplicitEndPreventsLateRecovery() {
+ XCTAssertFalse(
+ FlowPiPRecoveryPolicy.canContinue(
+ operation: 7,
+ currentOperation: 8,
+ wantsActiveSession: false,
+ isAppForeground: true,
+ taskIsCancelled: true
+ )
+ )
+ }
+
+ func testBackgroundAndCancellationBothStopRecovery() {
+ XCTAssertFalse(
+ FlowPiPRecoveryPolicy.canContinue(
+ operation: 7,
+ currentOperation: 7,
+ wantsActiveSession: true,
+ isAppForeground: false,
+ taskIsCancelled: false
+ )
+ )
+ XCTAssertFalse(
+ FlowPiPRecoveryPolicy.canContinue(
+ operation: 7,
+ currentOperation: 7,
+ wantsActiveSession: true,
+ isAppForeground: true,
+ taskIsCancelled: true
+ )
+ )
+ }
+}
diff --git a/OSGKeyboardTests/FlowSessionBridgeTests.swift b/OSGKeyboardTests/FlowSessionBridgeTests.swift
index 1a907b2..d5a440f 100644
--- a/OSGKeyboardTests/FlowSessionBridgeTests.swift
+++ b/OSGKeyboardTests/FlowSessionBridgeTests.swift
@@ -1342,7 +1342,7 @@ final class FlowSessionBridgeTests: XCTestCase {
startDeadlineAt: 1_700_000_008.25,
processingDeadlineAt: 1_700_000_045.25
)
- let expected = #"{"action":"startRecording","aiConversationID":"33333333-4444-5555-6666-777777777777","commandSeq":42,"createdAt":1700000000.25,"editSourceText":"draft","fieldContext":{"followingText":"after","isContextAvailable":true,"isEmptyField":false,"isSecureEntry":false,"keyboardType":"default","precedingText":"before","returnKeyType":"send"},"localeId":"en-US","processingDeadlineAt":1700000045.25,"protocolVersion":6,"sessionId":"00112233-4455-6677-8899-AABBCCDDEEFF","sourceHistoryEntryID":"22222222-3333-4444-5555-666666666666","sourceHistoryEntryRevision":7,"startDeadlineAt":1700000008.25,"utteranceId":"11111111-2222-3333-4444-555555555555","utteranceMode":"editLastInput"}"#
+ let expected = #"{"action":"startRecording","aiConversationID":"33333333-4444-5555-6666-777777777777","commandSeq":42,"createdAt":1700000000.25,"editSourceText":"draft","fieldContext":{"followingText":"after","isContextAvailable":true,"isEmptyField":false,"isSecureEntry":false,"keyboardType":"default","precedingText":"before","returnKeyType":"send"},"localeId":"en-US","processingDeadlineAt":1700000045.25,"protocolVersion":7,"sessionId":"00112233-4455-6677-8899-AABBCCDDEEFF","sourceHistoryEntryID":"22222222-3333-4444-5555-666666666666","sourceHistoryEntryRevision":7,"startDeadlineAt":1700000008.25,"utteranceId":"11111111-2222-3333-4444-555555555555","utteranceMode":"editLastInput"}"#
XCTAssertEqual(try sortedJSONString(command), expected)
}
@@ -1378,7 +1378,7 @@ final class FlowSessionBridgeTests: XCTestCase {
historyEntryRevision: 9,
aiConversationID: conversationID
)
- let expected = #"{"aiConversationID":"33333333-4444-5555-6666-777777777777","commandSeq":42,"createdAt":1700000050.5,"errorKind":"asrFailed","fieldFingerprint":"default|send|before|after","historyEntryID":"22222222-3333-4444-5555-666666666666","historyEntryRevision":9,"hostGeneration":"generation-1","protocolVersion":6,"rawText":"raw","revision":8,"sessionId":"00112233-4455-6677-8899-AABBCCDDEEFF","status":"final","text":"polished","utteranceId":"11111111-2222-3333-4444-555555555555","utteranceMode":"aiQuestion","warning":"fallback"}"#
+ let expected = #"{"aiConversationID":"33333333-4444-5555-6666-777777777777","commandSeq":42,"createdAt":1700000050.5,"errorKind":"asrFailed","fieldFingerprint":"default|send|before|after","historyEntryID":"22222222-3333-4444-5555-666666666666","historyEntryRevision":9,"hostGeneration":"generation-1","protocolVersion":7,"rawText":"raw","revision":8,"sessionId":"00112233-4455-6677-8899-AABBCCDDEEFF","status":"final","text":"polished","utteranceId":"11111111-2222-3333-4444-555555555555","utteranceMode":"aiQuestion","warning":"fallback"}"#
XCTAssertEqual(try sortedJSONString(result), expected)
}
diff --git a/README.md b/README.md
index dcc0fae..ec607ad 100644
--- a/README.md
+++ b/README.md
@@ -108,7 +108,7 @@ iOS / iPadOS 账号中心支持：
- **击键不上传**：中文候选学习与英文建议偏好保存在本机，密码框不学习
- **剪贴板可控**：历史默认关闭、最多 15 条、仅本机保存，不会自行发送给 AI
- **凭证隔离**：用户 API Key 保存在 Keychain；账号会话令牌只在主 App 私有 Keychain
-- **无广告追踪**：不集成广告、分析或追踪 SDK，不出售个人数据
+- **无广告追踪**：不集成第三方分析、广告或追踪 SDK；可退出的第一方产品分析不采集输入内容，不出售个人数据
完整数据类型、保留策略、账号删除与第三方服务说明见[隐私政策](https://hkgood.github.io/OSGKeyboard/privacy/)。
diff --git a/Scripts/device-pip-stress.sh b/Scripts/device-pip-stress.sh
index 26559f3..b9760d5 100755
--- a/Scripts/device-pip-stress.sh
+++ b/Scripts/device-pip-stress.sh
@@ -2,12 +2,13 @@
# Physical-device PiP / host-wake stress using `devicectl --console` logs.
#
# Usage:
-# ./Scripts/device-pip-stress.sh [UDID] [COUNT=50] [SUITES=cold,bgfg,hold]
+# ./Scripts/device-pip-stress.sh [UDID] [COUNT=50] [SUITES=cold,bgfg,hold,reclaim]
#
# Suites:
# cold — terminate-existing launch (force-quit / cold start)
# bgfg — open Safari (background) then relaunch OSG (foreground restore)
# hold — start PiP, wait 20s in session, relaunch to verify still recoverable
+# reclaim — foreground another PiP-capable app, then reopen OSG to reclaim
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
@@ -15,9 +16,11 @@ cd "$ROOT"
UDID="${1:-00008130-001C249C0E52001C}"
COUNT="${2:-50}"
-SUITES="${3:-cold,bgfg,hold}"
+SUITES="${3:-cold,bgfg,hold,reclaim}"
BUNDLE="com.osgkeyboard.ios"
SAFARI="com.apple.mobilesafari"
+TAKEOVER_BUNDLE="${PIP_TAKEOVER_BUNDLE:-$SAFARI}"
+TAKEOVER_SETTLE_SECONDS="${PIP_TAKEOVER_SETTLE_SECONDS:-5}"
OUT_DIR="${ROOT}/.tmp/device-pip-stress-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$OUT_DIR"
REPORT="$OUT_DIR/report.jsonl"
@@ -48,9 +51,18 @@ console_launch() {
"$BUNDLE" >"$outfile" 2>&1 || true
}
+# Launch without attaching a console. Killing a timed `--console` command also
+# terminates the app, so preparation phases must use a detached launch.
+plain_launch() {
+ xcrun devicectl device process launch \
+ --device "$UDID" \
+ --terminate-existing \
+ "$BUNDLE" >/dev/null 2>&1
+}
+
classify_file() {
local f="$1"
- local host="unknown" pip="unknown" mic="unknown"
+ local host="unknown" pip="unknown" mic="unknown" recovery="none"
if rg -q "OSGKeyboardApp\.init|MainAppRoot\.onAppear|activateOnForeground" "$f"; then
host="success"
@@ -93,12 +105,23 @@ classify_file() {
fi
fi
- echo "$host|$pip|$mic"
+ if rg -q "pip\.unexpectedStop" "$f" \
+ && rg -q "startSessionAsync\.ready.*trigger=(foreground|healthCheck|existingSession)" "$f"; then
+ recovery="reclaimed"
+ elif rg -q "startSessionAsync\.ready.*trigger=(foreground|healthCheck|existingSession|manualRetry)" "$f"; then
+ recovery="reconciled"
+ elif rg -q "failed after bounded recovery|pipState=failed" "$f"; then
+ recovery="exhausted"
+ elif rg -q "pipRecovery\.attempt" "$f"; then
+ recovery="attempted"
+ fi
+
+ echo "$host|$pip|$mic|$recovery"
}
run_suite() {
local suite="$1"
- local i outfile result host pip mic start_ts elapsed flags
+ local i outfile result host pip mic recovery start_ts elapsed flags
echo "==> Suite: $suite × $COUNT"
for i in $(seq 1 "$COUNT"); do
outfile="$OUT_DIR/${suite}-$i.console.log"
@@ -112,7 +135,8 @@ run_suite() {
;;
bgfg)
# Ensure app running with PiP first
- console_launch "$OUT_DIR/${suite}-$i.prep.log" 12 "--terminate-existing" >/dev/null || true
+ plain_launch
+ sleep 7
# Background by opening Safari
xcrun devicectl device process launch --device "$UDID" "$SAFARI" >/dev/null 2>&1 || true
sleep 3
@@ -120,7 +144,8 @@ run_suite() {
console_launch "$outfile" 12 ""
;;
hold)
- console_launch "$OUT_DIR/${suite}-$i.prep.log" 12 "--terminate-existing" >/dev/null || true
+ plain_launch
+ sleep 7
# Leave session alive ~20s (PiP should keep host)
sleep 20
# Background briefly then resume
@@ -128,6 +153,15 @@ run_suite() {
sleep 2
console_launch "$outfile" 12 ""
;;
+ reclaim)
+ plain_launch
+ sleep 7
+ # The target app must already be configured to enter PiP when launched.
+ # Safari is only a foreground/background fallback unless media is playing.
+ xcrun devicectl device process launch --device "$UDID" "$TAKEOVER_BUNDLE" >/dev/null 2>&1 || true
+ sleep "$TAKEOVER_SETTLE_SECONDS"
+ console_launch "$outfile" 14 ""
+ ;;
esac
elapsed=$(( $(date +%s) - start_ts ))
@@ -135,12 +169,14 @@ run_suite() {
host="${result%%|*}"
rest="${result#*|}"
pip="${rest%%|*}"
- mic="${rest##*|}"
+ rest="${rest#*|}"
+ mic="${rest%%|*}"
+ recovery="${rest##*|}"
- printf '{"suite":"%s","i":%d,"host":"%s","pip":"%s","mic":"%s","elapsed_s":%d}\n' \
- "$suite" "$i" "$host" "$pip" "$mic" "$elapsed" >>"$REPORT"
- printf "[%s %3d/%d] host=%-11s pip=%-12s mic=%-12s %2ds\n" \
- "$suite" "$i" "$COUNT" "$host" "$pip" "$mic" "$elapsed"
+ printf '{"suite":"%s","i":%d,"host":"%s","pip":"%s","mic":"%s","recovery":"%s","elapsed_s":%d}\n' \
+ "$suite" "$i" "$host" "$pip" "$mic" "$recovery" "$elapsed" >>"$REPORT"
+ printf "[%s %3d/%d] host=%-11s pip=%-12s mic=%-12s recovery=%-10s %2ds\n" \
+ "$suite" "$i" "$COUNT" "$host" "$pip" "$mic" "$recovery" "$elapsed"
done
}
@@ -148,7 +184,7 @@ run_suite() {
IFS=',' read -r -a selected_suites <<<"$SUITES"
for selected_suite in "${selected_suites[@]}"; do
case "$selected_suite" in
- cold|bgfg|hold) run_suite "$selected_suite" ;;
+ cold|bgfg|hold|reclaim) run_suite "$selected_suite" ;;
*)
echo "error: unknown suite '$selected_suite'" >&2
exit 1
@@ -165,7 +201,7 @@ by = collections.defaultdict(list)
for r in rows:
by[r["suite"]].append(r)
-selected = [name for name in ("cold", "bgfg", "hold") if by.get(name)]
+selected = [name for name in ("cold", "bgfg", "hold", "reclaim") if by.get(name)]
lines = [
"Device PiP / mic keep-alive stress summary",
f"device=Rocky 15 PM udid={udid} count_per_suite={count}",
@@ -178,12 +214,14 @@ for suite in selected:
host_ok = sum(1 for r in rs if r["host"] in ("success", "launch_only"))
pip_c = collections.Counter(r["pip"] for r in rs)
mic_c = collections.Counter(r["mic"] for r in rs)
+ recovery_c = collections.Counter(r["recovery"] for r in rs)
pip_ok = pip_c.get("success", 0)
lines += [
f"[{suite}]",
f" host_ok={host_ok}/{len(rs)} ({host_ok/n*100:.1f}%)",
f" pip_success={pip_ok}/{len(rs)} ({pip_ok/n*100:.1f}%) breakdown={dict(pip_c)}",
f" mic={dict(mic_c)}",
+ f" recovery={dict(recovery_c)}",
"",
]
lines += [
@@ -192,6 +230,7 @@ lines += [
" - cold uses --terminate-existing (force-quit recovery).",
" - bgfg backgrounds via Safari then resumes.",
" - hold keeps session ~20s then Safari background + resume.",
+ " - reclaim launches PIP_TAKEOVER_BUNDLE, then verifies OSG foreground reconciliation.",
" - Keyboard-extension mic tap is not automated.",
]
text = "\n".join(lines) + "\n"
diff --git a/Tests/suite-manifest.json b/Tests/suite-manifest.json
index ebf80f5..a34567c 100644
--- a/Tests/suite-manifest.json
+++ b/Tests/suite-manifest.json
@@ -40,6 +40,17 @@
"OSGKeyboardExtTests/ManagedGatewayTests"
]
},
+ "analytics": {
+ "description": "Privacy-safe analytics schema, durable queue, uploader, identity lifecycle, and anonymous extension runtime",
+ "platform": "ios",
+ "tests": [
+ "OSGKeyboardTests/AnalyticsModelTests",
+ "OSGKeyboardTests/AnalyticsRepositoryTests",
+ "OSGKeyboardTests/AnalyticsUploadCoordinatorTests",
+ "OSGKeyboardTests/AnalyticsAIOperationTests",
+ "OSGKeyboardExtTests/AnalyticsExtensionPrivacyTests"
+ ]
+ },
"sync": {
"description": "iCloud KVS merge/sync for settings, local-only clipboard consent, dictionary, speech history, usage stats",
"platform": "ios",
@@ -123,6 +134,8 @@
"platform": "ios",
"tests": [
"OSGKeyboardTests/FlowHandoffPolicyTests",
+ "OSGKeyboardTests/FlowHomePiPStatusPolicyTests",
+ "OSGKeyboardTests/FlowPiPRecoveryPolicyTests",
"OSGKeyboardTests/FlowSessionBridgeTests",
"OSGKeyboardTests/FlowSessionPolicyTests",
"OSGKeyboardTests/FlowBudgetAndMergeTests",
@@ -207,6 +220,7 @@
"config",
"account",
"managed_gateway",
+ "analytics",
"sync",
"polish",
"edit_last_input",
@@ -225,6 +239,7 @@
"config",
"account",
"managed_gateway",
+ "analytics",
"sync",
"polish",
"edit_last_input",
diff --git a/docs/APPSTORE_METADATA.md b/docs/APPSTORE_METADATA.md
index 5553fed..4452850 100644
--- a/docs/APPSTORE_METADATA.md
+++ b/docs/APPSTORE_METADATA.md
@@ -71,7 +71,11 @@ TYPING
PRIVACY
-• No advertising, analytics, or tracking SDKs.
+• Limited first-party product analytics; no third-party analytics,
+ advertising, tracking SDKs, ATT, or IDFA.
+• Product analytics never includes keyboard input, audio, transcripts,
+ prompts, model output, credentials, or personal identifiers. It can be
+ disabled in Settings, which deletes queued events.
• Local recognition does not upload audio.
• User-configured cloud requests go directly to that provider. Managed-credit
requests go through OSGKeyboard's managed gateway to the managed provider.
@@ -157,6 +161,9 @@ OSGKeyboard is a custom keyboard for iOS/iPadOS 26.
Clipboard, then return to the keyboard. Secure fields hide the clipboard
entry point. Turning History off preserves saved items; use the separate
confirmed clear action to delete them.
+10. First-party Product Analytics is enabled by default under Settings →
+ About → Privacy. Turning it off deletes queued events. It does not collect
+ keyboard input, audio, transcripts, prompts, model output, or credentials.
Privacy policy:
https://hkgood.github.io/OSGKeyboard/privacy/
@@ -230,9 +237,41 @@ This covers the pseudonymous OSGKeyboard account identifier and scoped
managed-service grant identifiers. Core use remains available without an
OSGKeyboard account.
+### Identifiers → Device ID
+
+- Collected: Yes
+- Purpose: Analytics
+- Linked to the user: Yes
+- Used for tracking: No
+
+This is an app-scoped random installation identifier. It rotates when analytics
+is re-enabled, after account deletion, or when a different account signs in. It
+is not IDFA and is not used across apps.
+
+### Usage Data → Product Interaction
+
+- Collected: Yes
+- Purpose: Analytics
+- Linked to the user: Yes
+- Used for tracking: No
+
+This covers fixed event names for app and keyboard sessions, purchase-page
+interactions, and invitation actions. It contains no free-form properties.
+
+### Usage Data → Other Usage Data
+
+- Collected: Yes
+- Purpose: Analytics
+- Linked to the user: Yes
+- Used for tracking: No
+
+This covers fixed AI feature categories, execution modes, outcome categories,
+and coarse duration buckets. It does not include prompts, transcripts, model
+output, audio, or keyboard content.
+
### Do not select
-- Advertising, marketing, analytics, product personalization, or tracking
+- Advertising, marketing, product personalization, or tracking
- Email address, phone number, physical address, location, contacts, photos,
browsing history, or search history
- Usage data or diagnostics stored only locally or in the user's private iCloud
@@ -249,6 +288,8 @@ standard HTTPS. Re-evaluate this answer if non-exempt cryptography is added.
- [ ] Run the release build and test suites on macOS with Xcode 26
- [ ] Replace screenshots with captures from the submitted build
- [ ] Verify the privacy answers against the submitted provider features
+- [ ] In App Store Connect, add Device ID, Product Interaction, and Other
+ Usage Data for Analytics; linked to the user, not used for tracking
- [ ] Confirm `500tks`, `1500tks`, and `3000tks` are approved, consumable,
and mapped to the server credit catalog
- [ ] Confirm `ByRockyACoffee` remains an optional consumable tip and unlocks
diff --git a/docs/assets/site.css b/docs/assets/site.css
index b0ea726..ae3e389 100644
--- a/docs/assets/site.css
+++ b/docs/assets/site.css
@@ -6,7 +6,7 @@
--surface-strong: #e5eaf0;
--ink: #111416;
--ink-secondary: #5f676e;
- --ink-tertiary: #8b949c;
+ --ink-tertiary: #626c74;
--line: rgba(17, 20, 22, 0.1);
--line-strong: rgba(17, 20, 22, 0.18);
--accent: #2d8a57;
@@ -28,7 +28,7 @@ html[data-theme="dark"] {
--surface-strong: #2b3033;
--ink: #f2f4f3;
--ink-secondary: #aab0ac;
- --ink-tertiary: #737a75;
+ --ink-tertiary: #969e98;
--line: rgba(255, 255, 255, 0.09);
--line-strong: rgba(255, 255, 255, 0.16);
--accent: #6fbd8a;
@@ -97,6 +97,13 @@ h3 {
text-wrap: balance;
}
+html[data-lang="zh"] h1,
+html[data-lang="zh"] h2,
+html[data-lang="zh"] h3 {
+ overflow-wrap: normal;
+ word-break: keep-all;
+}
+
.skip-link {
position: fixed;
z-index: 100;
@@ -300,27 +307,6 @@ html[data-theme="dark"] #themeToggle::before {
height: 22px;
}
-.assistant-tabs > .material-symbols-rounded::before {
- content: "•••";
- font-size: 0.72rem;
- letter-spacing: 0.08em;
-}
-
-.round-control:first-child .material-symbols-rounded::before {
- content: "↶";
- font-size: 1.15rem;
-}
-
-.round-control:last-child .material-symbols-rounded::before {
- content: "↑";
- font-size: 1.05rem;
-}
-
-.mic-control .material-symbols-rounded::before {
- content: "●";
- font-size: 0.72rem;
-}
-
.gesture-grid .material-symbols-rounded,
.skill-actions .material-symbols-rounded {
display: none;
@@ -341,16 +327,6 @@ html[data-theme="dark"] #themeToggle::before {
font-size: 1.55rem;
}
-.ios-symbol .material-symbols-rounded::before {
- content: "⌨";
- font-size: 2.25rem;
-}
-
-.ios-symbol .material-symbols-rounded {
- width: 46px;
- height: 46px;
-}
-
.outline-action .material-symbols-rounded::before {
content: "⌘";
font-size: 1rem;
@@ -467,6 +443,14 @@ html[data-lang="zh"] .hero h1 {
height: 48px;
}
+html[data-theme="light"] .store-badge img {
+ filter: invert(1);
+}
+
+html[data-theme="dark"] .store-badge img {
+ filter: none;
+}
+
.store-badge:hover,
.store-badge:focus-visible {
opacity: 0.86;
@@ -718,103 +702,37 @@ html[data-theme="dark"] .message-bubble {
bottom: 24px;
}
-.keyboard-demo {
- display: flex;
+.keyboard-capture {
+ position: relative;
+ align-self: center;
min-width: 0;
+ aspect-ratio: 1.18;
+ margin: 0;
+ overflow: hidden;
background: var(--surface-strong);
- flex-direction: column;
}
-.assistant-tabs {
- display: grid;
- grid-template-columns: 46px repeat(3, auto) 1fr;
- gap: 8px;
- align-items: center;
- padding: 16px 18px;
- border-bottom: 1px solid var(--line);
+.keyboard-capture img {
+ display: block;
+ width: 100%;
+ height: 100%;
+ object-fit: cover;
+ object-position: center bottom;
}
-.assistant-logo {
- display: grid;
- width: 36px;
- height: 36px;
- border-radius: 11px;
- background: var(--accent);
- color: #fff;
- font-size: 0.66rem;
- font-weight: 800;
- place-items: center;
-}
-
-.assistant-tab {
- padding: 6px 9px;
+.keyboard-capture figcaption {
+ position: absolute;
+ top: 16px;
+ left: 16px;
+ padding: 7px 10px;
+ border: 1px solid rgba(255, 255, 255, 0.22);
border-radius: 999px;
- color: var(--ink-tertiary);
- font-size: 0.72rem;
+ background: rgba(17, 20, 22, 0.68);
+ color: #ffffff;
+ font-size: 0.68rem;
font-weight: 650;
-}
-
-.assistant-tab.active {
- background: var(--surface);
- color: var(--ink);
-}
-
-.assistant-tabs > .material-symbols-rounded {
- justify-self: end;
- color: var(--ink-tertiary);
-}
-
-.keyboard-keys {
- display: grid;
- grid-template-columns: repeat(10, 1fr);
- gap: 7px;
- padding: clamp(42px, 6vw, 80px) 18px 20px;
-}
-
-.keyboard-keys span {
- display: grid;
- min-width: 0;
- height: 42px;
- border-bottom: 2px solid var(--line-strong);
- color: var(--ink-secondary);
- font-size: 0.75rem;
- place-items: center;
-}
-
-.keyboard-keys span:nth-child(n + 11) {
- transform: translateX(50%);
-}
-
-.assistant-controls {
- display: grid;
- grid-template-columns: 1fr auto 1fr;
- align-items: center;
- margin-top: auto;
- padding: 22px 24px 26px;
- border-top: 1px solid var(--line);
-}
-
-.round-control,
-.mic-control {
- display: grid;
- width: 44px;
- height: 44px;
- border-radius: 50%;
- background: var(--surface);
- color: var(--ink-secondary);
- place-items: center;
-}
-
-.round-control:last-child {
- justify-self: end;
-}
-
-.mic-control {
- width: 58px;
- height: 58px;
- background: var(--accent);
- color: #fff;
- box-shadow: 0 10px 24px color-mix(in srgb, var(--accent) 26%, transparent);
+ backdrop-filter: blur(12px);
+ -webkit-backdrop-filter: blur(12px);
}
.gesture-grid {
@@ -1417,29 +1335,28 @@ html[data-theme="dark"] .privacy-section {
.platform-symbol {
display: grid;
- width: 110px;
- height: 150px;
+ width: 104px;
+ height: 104px;
align-self: start;
border: 1px solid var(--line);
- border-radius: 28px;
+ border-radius: 24px;
background: var(--surface-soft);
color: var(--ink-secondary);
place-items: center;
}
-.platform-symbol .material-symbols-rounded {
- font-size: 42px;
+.platform-symbol svg {
+ width: 48px;
+ height: 48px;
+ fill: none;
+ stroke: currentColor;
+ stroke-linecap: round;
+ stroke-linejoin: round;
+ stroke-width: 2.6;
}
.mac-symbol {
- width: 116px;
- height: 96px;
- border-radius: 18px;
-}
-
-.option-key {
- font-size: 2.4rem;
- font-weight: 500;
+ border-radius: 24px;
}
.platform-stories h3 {
@@ -1795,10 +1712,6 @@ html[data-lang="zh"] .download-panel h2 {
border-bottom: 1px solid var(--line);
}
- .keyboard-demo {
- min-height: 430px;
- }
-
.scene-copy {
max-width: 690px;
}
@@ -1926,7 +1839,7 @@ html[data-lang="zh"] .download-panel h2 {
font-size: clamp(2rem, 9vw, 2.2rem);
}
- .hero h1 > span {
+ html[data-lang="zh"] .hero h1 > span {
white-space: nowrap;
}
@@ -1987,30 +1900,6 @@ html[data-lang="zh"] .download-panel h2 {
padding: 18px;
}
- .keyboard-demo {
- min-height: 360px;
- }
-
- .assistant-tabs {
- grid-template-columns: 42px repeat(3, auto) 1fr;
- gap: 3px;
- padding: 13px 10px;
- }
-
- .assistant-tab {
- padding: 6px;
- }
-
- .keyboard-keys {
- gap: 4px;
- padding: 45px 10px 16px;
- }
-
- .keyboard-keys span {
- height: 36px;
- font-size: 0.65rem;
- }
-
.gesture-grid {
grid-template-columns: 1fr;
}
@@ -2094,14 +1983,18 @@ html[data-lang="zh"] .download-panel h2 {
}
.platform-symbol {
- width: 92px;
- height: 122px;
- border-radius: 23px;
+ width: 88px;
+ height: 88px;
+ border-radius: 21px;
}
.mac-symbol {
- height: 76px;
- border-radius: 16px;
+ border-radius: 21px;
+ }
+
+ .platform-symbol svg {
+ width: 42px;
+ height: 42px;
}
.setup-steps {
diff --git a/docs/assets/site.js b/docs/assets/site.js
index d0cee4e..6348f17 100644
--- a/docs/assets/site.js
+++ b/docs/assets/site.js
@@ -58,15 +58,20 @@
element.setAttribute("content", element.dataset[`${lang}Content`] || "");
});
+ document.querySelectorAll("[data-shot]").forEach((image) => {
+ const theme = root.dataset.theme || "light";
+ image.src = `assets/screenshots/${lang}/${theme}/${image.dataset.shot}`;
+ });
+
document.title = lang === "zh"
- ? "OSGKeyboard — 语音、打字与 AI 助手键盘"
- : "OSGKeyboard — Voice, typing, and an AI assistant keyboard";
+ ? "OSGKeyboard — 语音输入、中英打字与 AI 助手"
+ : "OSGKeyboard — Voice input, bilingual typing, and an AI assistant";
if (languageButton) {
languageButton.textContent = lang === "zh" ? "EN" : "中文";
languageButton.setAttribute(
"aria-label",
- lang === "zh" ? "Switch to English" : "切换到中文"
+ lang === "zh" ? "切换到英文" : "Switch to Chinese"
);
}
@@ -131,6 +136,11 @@
themeColor?.setAttribute("content", resolved === "dark" ? "#0c0e0f" : "#eef2f6");
+ document.querySelectorAll("[data-shot]").forEach((image) => {
+ const lang = root.dataset.lang || "zh";
+ image.src = `assets/screenshots/${lang}/${resolved}/${image.dataset.shot}`;
+ });
+
if (persist) localStorage.setItem("osg-site-theme", resolved);
}
diff --git a/docs/assets/whats-new/osg-credits-en.png b/docs/assets/whats-new/osg-credits-en.png
new file mode 100644
index 0000000000000000000000000000000000000000..5754d2d097432fe51b84aec3ed91352b720e49b7
GIT binary patch
literal 75502
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