iOS SDK 文档

iOS SDK（Swift，iOS 13 起，Objective-C 也可调用）的下载、Swift Package / CocoaPods 接入、初始化、配置项、隐私合规、自动采集事件与指标口径。

概述

iOS SDK 与 Android SDK 功能对齐，数据进同一个 App 控制台，报表按平台区分。SDK 以二进制 xcframework 发布，崩溃捕获 KSCrash 已打包在内，自动采集会话、页面、启动耗时、崩溃与主线程卡死。

创建 App在控制台「我的 App」添加应用，得到 APP_KEY。

添加依赖通过 Swift Package Manager 或 CocoaPods 添加 FmengSDK，也可以下载 xcframework 手动集成。

配置与初始化在 Info.plist 中配置 FMENG_APPKEY，在 App 启动时调用 Fmeng.start()。

查看报表启动一次 App，接入检测通过后即可查看概览、崩溃与启动性能。

添加依赖

推荐用 Swift Package Manager 引入，也可以用 CocoaPods。SDK 是二进制 xcframework，不会再拉取其他依赖：

Swift Package Manager

CocoaPods

swift

// Package.swift (or Xcode → File → Add Package Dependencies… → http://a.t3j.com/ios-sdk/FmengSDK.git)
dependencies: [
    .package(url: "http://a.t3j.com/ios-sdk/FmengSDK.git", from: "1.0.1"),
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "FmengSDK", package: "FmengSDK"),
    ]),
]

Xcode 中选 File → Add Package Dependencies…，输入下面的地址，规则选 Up to Next Major Version：http://a.t3j.com/ios-sdk/FmengSDK.git

不用包管理器时，下载 xcframework 压缩包，解压后拖进工程，在 Target → General → Frameworks, Libraries, and Embedded Content 中设为 Embed & Sign。

下载 FmengSDK.xcframework（zip）

初始化

App Key 与渠道写在 Info.plist（与 Android 的 FMENG_APPKEY / FMENG_CHANNEL 用法相同）。FMENG_APPKEY 在控制台「App 设置 - 基本信息」中查看；FMENG_CHANNEL 可选，不写时自动判断：模拟器为 simulator，TestFlight 与 Xcode 直装为 testflight，App Store 为 appstore。

xml

<!-- Info.plist -->
<key>FMENG_APPKEY</key>
<string>APP_KEY</string>
<!-- optional: distribution channel; auto-detected (appstore / testflight / simulator) when omitted -->
<key>FMENG_CHANNEL</key>
<string>appstore</string>

然后在 App 启动时尽早调用 Fmeng.start()，崩溃捕获与冷启动计时从这里开始：

Swift · UIKit

SwiftUI

Objective-C

swift

// AppDelegate.swift
import FmengSDK
 
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // App Key / channel come from Info.plist (FMENG_APPKEY / FMENG_CHANNEL).
    Fmeng.start()
    return true
}

也可以不写 Info.plist，直接在代码里传配置（代码里的值优先于 Info.plist）：

swift

let config = FmengConfig(appKey: "APP_KEY")
config.channel = "appstore"
config.debug = true          // system log, subsystem com.fmeng.analytics
config.hangThreshold = 3     // seconds; default 2
Fmeng.start(config: config)

start 在主线程只做轻量工作（读开关、注册生命周期通知、安装崩溃捕获）；设备 ID、设备信息与离线队列在 SDK 的工作队列加载，start 之后立刻调用的 track 也不会丢失或乱序。

配置项

FmengConfig 的属性（App Key 与渠道也可以写在 Info.plist 里，代码里的值优先）：

属性	默认值	说明
`appKey`	必填	控制台创建 App 时生成的 APP_KEY，代码或 Info.plist 的 FMENG_APPKEY 二选一。
`channel`	自动判断	分发渠道，用于「版本与渠道」报表；未设置时取 FMENG_CHANNEL，都没有时按安装来源判断。
`region`	国外节点	采集节点："cn" 为国内节点，适合主要用户在中国大陆的 App（1.1.0 起）；未设置时取 Info.plist 的 FMENG_REGION。两个节点的数据进同一个控制台。
`debug`	false	打印调试日志（Xcode 控制台 / Console.app，subsystem 为 com.fmeng.analytics）。
`crashReport`	true	捕获崩溃（NSException、C++ 异常、Mach 异常与信号），下次启动时上报。
`hangReport`	true	捕获主线程卡死，在控制台「ANR」页查看。
`hangThreshold`	2（秒）	主线程卡住多久算一次卡死；卡死中被系统杀掉的一律上报。
`autoTrackScreens`	true	UIViewController 出现时自动记录页面，页面名为类名；SwiftUI 页面用 .fmengScreen 手动标记。
`sessionTimeout`	30（秒）	App 在后台超过该时长后回到前台，算一次新的启动（会话）。

接口

自定义事件、手动页面与登录用户。事件名不超过 64 个字符；属性最多 30 个，键不超过 64 个字符、字符串值不超过 256 个字符，值可以是字符串、数字或布尔：

Swift

Objective-C

Swift

Fmeng.track("purchase", properties: ["sku": "A100", "price": 199]) // custom event
 
Fmeng.trackScreen("Cart")          // manual screen
Text("Home").fmengScreen("Home")   // SwiftUI screen
Fmeng.setUserId("u_123")           // after sign-in; nil on sign-out
Fmeng.flush()                      // send queued events now
Fmeng.setEnabled(false)            // stop collecting (e.g. before privacy consent)

所有方法线程安全；start 之前调用是空操作（setEnabled 除外）；SDK 内部错误不会抛给 App。App Key 无效时 start 只在日志里报错，SDK 保持未初始化。

HTTP 采集地址

iOS 默认只允许 https（ATS）。采集地址是 http 时，需要在 Info.plist 里为采集域名放行明文流量；采集地址是 https 时跳过这一步。

xml

<!-- Info.plist -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>a.t3j.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

隐私合规

在用户同意隐私政策之前先关闭统计。关闭状态下 SDK 不生成设备 ID、不读取设备与网络信息、不安装崩溃捕获、不采集任何事件；开关会持久化，下次启动沿用。

swift

if !PrivacyStore.agreed { Fmeng.setEnabled(false) }   // must be called before start
Fmeng.start()
 
// after the user accepts the privacy policy
Fmeng.setEnabled(true)   // persisted; enabled on later launches

SDK 自带隐私清单 PrivacyInfo.xcprivacy（App Store 要求），声明了采集的数据类型（设备 ID、用户 ID、产品交互、崩溃、性能、粗略位置）与 Required Reason API（UserDefaults、systemUptime）。SDK 不用于跟踪、不采集 IDFA，不需要 ATT 弹窗；在 App Store Connect 填写「App 隐私」时按这些类型勾选。

自动采集

SDK 自动采集以下事件。事件先写入本地，按会话成批 gzip 上报，断网会自动重试；崩溃与卡死在下次启动时上报。

事件	触发时机	关键字段
`launch`	冷启动、温启动、热启动（超过 60 秒的丢弃）	launch_type、耗时（毫秒）
`foreground`	App 回到前台	会话 ID
`background`	App 退到后台（申请一小段后台时间把数据发完）	本次前台时长
`screen_view`	UIViewController 出现；或 trackScreen / .fmengScreen	页面名
`crash (native)`	NSException、C++ 异常、Mach 异常与信号	异常名或信号名、消息、堆栈
`crash (anr)`	主线程卡住达到 hangThreshold 后恢复，或卡死中被系统杀掉	主线程堆栈

每次上报都带设备上下文：Bundle ID、版本号与构建号、渠道、系统版本、机型、分辨率、语言地区与网络类型。不采集 IDFA、IDFV、运营商与位置；地域由服务端按 IP 解析，访问者 IP 保存在服务端，只能通过开放接口（MCP）查询，控制台不展示。设备 ID 是 SDK 生成的随机 UUID，卸载重装后会变。

注意事项

测试崩溃时不要挂着 Xcode 调试器：调试器会先截获崩溃信号。先在 Xcode 里停止运行，再从桌面图标打开 App 触发崩溃，重新打开 App 后数据即上报。
已集成其他崩溃采集（Firebase Crashlytics、Bugly、Sentry 等）时通常可以共存，但只有一个库能拿到完整的 Mach 异常；只需要一个时可设置 crashReport = false，卡死捕获仍可保留。
只支持 App 主程序，不要在 App Extension（小组件、通知扩展等）里调用 start。
崩溃栈在设备上符号化：系统库的栈帧带符号名，App 自身代码在 Release 包里显示为「镜像名 + 偏移」，需要用 App 的 dSYM 符号化；栈末尾附 App 镜像的 UUID 与加载地址。

指标口径

iOS 与 Android 共用 App 统计的指标口径（活跃用户、启动次数、使用时长、页面停留、留存等），完整说明见Android SDK 文档的「指标口径」。iOS 上的差异：

崩溃包括 NSException、C++ 异常、Mach 异常与信号（含 Swift 运行时错误，如强制解包 nil、数组越界），类型为 native，与 Android 的 Java + Native 崩溃一起计入崩溃率；同一构建里同一位置的崩溃归为一个问题。
iOS 没有 ANR，主线程卡死按同样的「ANR」口径统计，在控制台「ANR」页查看，不计入崩溃率。
启动耗时：冷启动为进程创建到首次激活后的首帧；温启动为 iOS 15 预热进程从 start 算起，或后台启动后第一次打开；热启动为从后台回来到首帧。
会话：冷启动即新会话；在后台超过 sessionTimeout（默认 30 秒）后回到前台为新会话。

上一篇 Android SDK 文档

没有找到答案？登录控制台后可在右上角铃铛查看系统公告，也可以在关于页找到联系方式。

关于我们进入控制台