iOS SDK

AI 辅助接入 iOS

在 App 启动入口创建并复用 SDK 实例，记录并验证首个事件。

前置准备

• iOS 13 及以上；
• 获取事件接收地址 endpoint 和项目凭据 projectKey，详见环境与项目凭据；
• 准备 Xcode 和下载包中的 iOS 二进制 SDK，确认目标应用满足平台要求。

---

快速接入

步骤 1：引入依赖与模块引用

从 iOS SDK 下载页下载离线包。在 Xcode 的 Add Package Dependencies 中选择 Add Local，选中解压目录的 Package.swift，并将 TrackBusinessSDKKit 产品添加到宿主 target：

import TrackBusinessSDKKit

按需添加 SwiftUI、UIKit 或 Location 产品；这些产品会同时链接核心库。请保持解压目录位置稳定，避免重复手工链接同一份 XCFramework。

也可手工添加包内 frameworks/ 下的 XCFramework，并在 Xcode 中为所用框架选择 Embed & Sign，使框架中的隐私清单随 App 一同归档。SwiftUI 与 UIKit 扩展须与核心库使用同一 iOS 版本。归档后应核对 SDK 的 PrivacyInfo.xcprivacy 已进入最终 App；实际签名由宿主的发布配置负责。

步骤 2：创建进程级 SDK 实例

在应用启动任务中异步创建并复用一个 SDK 实例。界面可以先显示，在初始化成功后再启用埋点。

import Foundation
import TrackBusinessSDKKit

// SDK 默认 GRANTED + MINIMAL；宿主仍需按自身授权流程决定初始状态
let sdk = try await TrackBusinessSDK.createAsync(
    endpoint: URL(string: "https://collector.example.com/v1/events/batch")!,
    projectKey: "ios-public-project-key"
)

createAsync 会在后台准备存储并恢复身份。请处理初始化错误，并在成功后将实例交给业务使用。

TIP

需要事前授权时，创建实例时传入 initialConsent: .pending，并在宿主/CMP 确认授权后调用 sdk.grantConsent(level: "STANDARD")。完整示例见下方“授权后开始采集”。

步骤 3：记录首个事件

在业务代码中调用 track() 记录事件。SDK 异步入队并调度上传；调用返回不等于已落盘或已上传。使用内存队列时，未确认事件不能跨进程恢复：

// 记录事件；SDK 随后异步入队并按配置调度上传：
sdk.track(
    "quickstart_completed",
    properties: ["source": "ios-docs"]
)

---

验证交付结果

1. 使用测试环境的 endpoint 和 projectKey，记录上面的 quickstart_completed 事件。
2. 检查 ATS 配置、上传诊断和队列状态；联调时可调用 try await sdk.flush()。实体设备使用可达的局域网或部署服务地址，不能使用设备自身的 localhost。
3. 核对接收端的事件名、属性与接收记录，并确认响应符合整批 ACK 契约。

SDK 会自动合批；flush() 返回或队列为空不能单独证明事件已接收。详见数据校验。

可选：检查待发事件的确认结果

记录测试事件后，可用 verifyDelivery 检查当前待发范围。它不能代替接收端记录。

sdk.verifyDelivery(timeoutMs: 3000) { report in
    switch report.status {
    case "acknowledged": print("当前待发范围已确认")
    case "rejected": print("存在明确拒收，请排查配置或事件规则")
    case "empty": print("当前没有待验证事件，不作为接收证明")
    default: print("尚未完整确认：\(report.reason)")
    }
}

各状态含义见数据校验。

---

可选配置

登录后关联用户

登录系统确认用户后再关联业务身份；切换到另一个账号和安全退出应使用明确的边界操作：

try sdk.identify(userId: "user_10086")
sdk.track("account_page_viewed")
try sdk.switchUser(userId: "user_10087") // 已知切换到另一个账号
sdk.signOut() // 安全退出并建立新的匿名代际

identify 用于首次关联，不用于静默覆盖已登录用户。完整规则见身份与生命周期。

授权后开始采集

需要事前授权时以 PENDING 初始化，用户同意后再开启采集：

let sdk = try await TrackBusinessSDK.createAsync(
    endpoint: URL(string: "https://collector.example.com/v1/events/batch")!,
    projectKey: "ios-public-project-key",
    initialConsent: .pending
)

// 用户点击同意隐私协议后开启采集：
sdk.grantConsent(level: "STANDARD")

Objective-C 宿主接入

纯 Objective-C 宿主可链接 TrackBusinessSDKUIKit.xcframework 与核心库，使用轻量桥接器：

#import <WebKit/WebKit.h>
#import <TrackBusinessSDKUIKit/TrackBusinessSDKUIKit-Swift.h>

[TrackBusinessObjCBridge
    createAsyncWithEndpoint:@"https://collector.example.com/v1/events/batch"
    projectKey:@"ios-public-project-key"
    completion:^(TrackBusinessObjCBridge *tracker, NSError *error) {
        if (error != nil) {
            NSLog(@"Track Business SDK initialization failed");
            return;
        }
        self.tracker = tracker;
        [tracker trackWithEventName:@"quickstart_completed"];
        [tracker flush];
    }];

完成回调在主线程执行。示例由宿主通过 tracker 属性持有实例。Objective-C 桥接器支持无属性事件、交互记录、授权、opt-out、flush 和关闭。带属性的事件或 identify 可由混编项目通过宿主 Swift 封装调用。flush 仅触发异步发送。