4. iOS SDK 集成：Pod/CocoaPods 集成、初始化、项目配置、权限说明

在 iOS 项目中集成 Firebase Performance 监控，推荐使用 CocoaPods 作为依赖管理工具。本章将带你完成从 Podfile 配置到 SDK 初始化、项目参数设置以及权限说明的全流程，确保监控模块能够正确启动并在真机/模拟器上稳定运行。

4.1 集成流程概览

下表列出了 iOS SDK 集成的核心步骤、关键动作以及对应的配置文件/代码位置，便于你按序执行。

4.2 CocoaPods 集成

打开终端，进入项目根目录（包含 .xcodeproj 文件），执行以下命令创建 Podfile：

pod init

编辑生成的 Podfile，在 target 块内添加 Firebase Performance 依赖：

# Podfile
platform :ios, '13.0'          # 最低支持 iOS 13.0

target 'YourAppTargetName' do
  use_frameworks!

  # Firebase Performance 监控
  pod 'Firebase/Performance'
end

保存后执行安装命令：

pod install --repo-update

安装完成后，务必使用新生成的 .xcworkspace 文件打开项目，而不是原来的 .xcodeproj。

4.3 SDK 初始化

在 AppDelegate 的 application(_:didFinishLaunchingWithOptions:) 方法中导入 Firebase 并完成初始化：

// AppDelegate.swift
import UIKit
import FirebaseCore
import FirebasePerformance

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // 初始化 Firebase
        FirebaseApp.configure()

        // 可选：如果你需要自定义 Performance 配置，可以在初始化后立即设置
        // let perfConfig = PerformanceConfiguration()
        // Performance.sharedInstance().installationID = "your-instance-id"

        return true
    }
}

若使用 Objective-C，对应代码如下：

// AppDelegate.m
@import FirebaseCore;
@import FirebasePerformance;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [FIRApp configure];
    return YES;
}

Firebase Performance 在初始化后会自动开始收集卡顿、网络请求等性能数据，无需额外启动方法。

4.4 项目配置

4.4.1 添加 GoogleService-Info.plist

从 Firebase Console 下载你的 iOS 应用的 GoogleService-Info.plist 文件，将其拖入 Xcode 项目根目录（确保勾选 “Copy items if needed” 并添加至 Target）。该文件包含 Firebase 项目标识、、应用 ID 等关键信息，切勿将其提交到公开版本库。

4.4.2 Info.plist 权限与网络配置

为了使 Performance SDK 能够正常上报数据，需要在 Info.plist 中配置网络访问权限及应用传输安全（App Transport Security, ATS）例外。Firebase 默认使用 HTTPS 通信，但部分旧版 iOS 可能需要显式允许 HTTP 回退。

一种常见的安全配置示例（在 Info.plist 源文件中直接编辑）：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <false/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>firebaseinstallations.googleapis.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <false/>
        </dict>
    </dict>
</dict>

通常情况下，不修改 ATS 也可以正常工作，因为 Firebase SDK 统一使用 HTTPS。上述配置仅在遇到连接问题时需要微调。

4.5 权限说明

Firebase Performance 本身不需要用户显式授予位置、相机或麦克风等敏感权限。但其上报数据依赖于网络连接，因此应用必须具备 互联网访问权限。iOS 默认允许应用访问网络，无需额外 Privacy 描述。如果你的应用还需要在后台收集性能数据（例如后台检测卡顿），可能需要开启 Capabilities 中的 Background Modes → Background fetch 或 Remote notifications，但这不是 Performance 的必要条件。

4.6 集成流程图

下面这张内联 SVG 图直观展示了从 Pod 集成到初始化完成的完整链路，以及三个关键检查点。

4.7 调试与验证

集成完成后，在 Xcode 中 Run 你的项目，打开 Debug 控制台。搜索过滤 Firebase Performance 或 FIRPerformance，应看到类似下面的日志：

[Firebase/Performance][I] Firebase Performance Monitoring is enabled.
[Firebase/Performance][I] Performance SDK initialized successfully.

如果没有出现，请检查以下几点：

• Podfile 是否正确包含 pod 'Firebase/Performance'，并重新执行 pod install。
• Bundle ID 是否与 Firebase Console 中的 iOS 应用一致，否则 GoogleService-Info.plist 可能不匹配。
• 初始化顺序：确保 FirebaseApp.configure() 在任意 Performance API 调用之前执行。
• Minimum iOS Version：Firebase Performance 要求 iOS 13+，检查 Podfile 中 platform 是否为 13.0 或更高。

4.8 常见集成错误与解决方案