怎么安装 iOS SDK？

简短回答

在 应用统计 › 配置 › SDK 代码 登记 Bundle ID，用 Swift Package Manager（或从 git 源用 CocoaPods）添加 TapCub 包，在 application(_:didFinishLaunchingWithOptions:) 里调用 TapCub.preInit(TapCubConfig(siteKey: "YOUR_SITE_KEY"))，用户同意隐私政策后调用 TapCub.initialize()。之后启动、UIKit 页面、点按、崩溃和主线程卡顿会自动采集。到 应用统计 › 概览 › 实时 看头一条启动事件。

SDK 支持 iOS 13+ 和 tvOS 13+，需要 Swift 5.9；Objective-C 项目用 TapCubSDK。不使用 IDFA，也不会弹出应用跟踪透明度（ATT）授权。

1. 登记 Bundle ID

打开 应用统计 › 配置 › SDK 代码，点「添加应用标识」，填入 Bundle ID，比如 com.example.shop。未登记的 Bundle ID 发来的数据会被采集端丢弃，不会有任何可见报错。这个页面也会给出带站点 Key 的安装代码。

2. 添加依赖包

Swift Package Manager： 在 Xcode 里选 File › Add Package Dependencies，输入控制台安装代码里给出的仓库地址（https://github.com/tapcub/tapcub-ios），把 TapCub 加到 App target。

CocoaPods： 这个 pod 从 git 源安装，不在 CocoaPods trunk 上：

pod 'TapCub', :git => 'https://github.com/tapcub/tapcub-ios', :tag => '0.1.0'

3. 初始化

import TapCub

func application(_ app: UIApplication,
                 didFinishLaunchingWithOptions opts: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    TapCub.preInit(TapCubConfig(siteKey: "YOUR_SITE_KEY"))
    return true
}

// 用户同意隐私政策之后
TapCub.initialize()

• preInit 只保存配置、绑定生命周期：不采集、不读设备信息、不联网。在启动时于主线程调用。
• initialize 开始采集。如果你的 App 不需要同意这一步，紧接着 preInit 调用即可。
• appId、appVersion、appBuild 默认取 Info.plist 里的值。appId 必须和登记的 Bundle ID 一致。
• 国内模式传 region: "cn"，同意后调用 initialize，再调用 TapCub.grantConsent(["analytics"])。

Objective-C：

[TapCubSDK preInitWithSiteKey:@"YOUR_SITE_KEY" endpoint:nil appId:nil];
[TapCubSDK start];

4. 自动采集的内容

SwiftUI 视图不会自动采集：加 .wcScreen("Checkout") 修饰符，或调用 TapCub.trackScreen("Checkout")。见追踪屏幕浏览。

5. 发送事件和识别用户

TapCub.track("purchase", props: ["revenue": 19.9, "currency": "CNY"])

TapCub.login("USER_ID")          // 登录后
TapCub.setProps(["plan": "pro"])
TapCub.logout()                  // 退出登录时

项目不是实名模式时 login 会被忽略，事件照常上报。见识别用户。

6. 验证

在模拟器或真机上运行 App，打开 应用统计 › 概览 › 实时，几秒内应能看到启动事件。

隐私和 App Store

包里自带 PrivacyInfo.xcprivacy 隐私清单，声明设备 ID、产品交互、崩溃数据和性能数据，NSPrivacyTracking = false。如果调用了 login，要在你自己 App 的隐私清单和 App Store 隐私问卷里加上 User ID。设备 ID 基于 IDFV，并在钥匙串里留一份副本。事件队列存在 Application Support 下，不参与 iCloud 备份（默认 8 MB、1 万条或 7 天）。

崩溃堆栈记录为镜像名加偏移量，符号化需要对应的 dSYM 文件，请妥善保留。

排查

• 没有数据： Bundle ID 没登记，或者从没调用 initialize。
• 缺 SwiftUI 页面： 加 .wcScreen 或调用 trackScreen。
• 启动时 precondition 失败： 站点 Key 为空。
• 对某个用户停止采集： TapCub.optOut()，optIn() 恢复。

相关

• 无崩溃率
• 追踪 App 版本
• 识别用户
• SDK 是什么？含义、SDK 和 API 的区别，以及统计 SDK 怎么工作
• 安装 Android SDK
• 在 Flutter 上安装
• 在 React Native 上安装