8b27430ed1
Some checks failed
iOS CI/CD / Build & Test (push) Has been cancelled
- rust-ffi-update.md: FFI binding update workflow - app-store-submission-checklist.md: 9-section App Store review - ios-ci.yml: GitHub Actions build + test on macos-15 - firebase-crashlytics-integration.md: Crashlytics setup guide Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
151 lines
3.5 KiB
Markdown
151 lines
3.5 KiB
Markdown
# 崩溃监控集成（Firebase Crashlytics）
|
||
|
||
## 1. 概述
|
||
|
||
Firebase Crashlytics 用于收集 iOS 应用崩溃日志，支持 Swift 层和 Rust FFI 层的崩溃追踪。
|
||
|
||
## 2. 集成步骤
|
||
|
||
### 2.1 添加依赖
|
||
|
||
```swift
|
||
// Package.swift 或 Xcode SPM
|
||
.package(url: "https://github.com/firebase/firebase-ios-sdk", from: "11.0.0")
|
||
|
||
// Target dependencies
|
||
.product(name: "FirebaseCrashlytics", package: "firebase-ios-sdk"),
|
||
```
|
||
|
||
### 2.2 初始化
|
||
|
||
```swift
|
||
// AppDelegate.swift 或 AIStudyApp.swift
|
||
import Firebase
|
||
|
||
func application(_ application: UIApplication,
|
||
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
|
||
FirebaseApp.configure()
|
||
return true
|
||
}
|
||
```
|
||
|
||
### 2.3 GoogleService-Info.plist
|
||
|
||
从 Firebase Console 下载 `GoogleService-Info.plist`，放入 Xcode 项目根目录（不要加入 git，加入 .gitignore）。
|
||
|
||
```bash
|
||
# .gitignore
|
||
GoogleService-Info.plist
|
||
```
|
||
|
||
### 2.4 dSYM 上传
|
||
|
||
```bash
|
||
# Build Phase: Run Script
|
||
"${BUILD_DIR%/Build/Products}/${CONFIGURATION}-${PLATFORM_NAME}/AIStudyApp.app/dSYMs"
|
||
${PODS_ROOT}/FirebaseCrashlytics/upload-symbols \
|
||
-gsp "${PROJECT_DIR}/GoogleService-Info.plist" \
|
||
-p ios "${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}"
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 自定义日志
|
||
|
||
### 3.1 Swift 层
|
||
|
||
```swift
|
||
import FirebaseCrashlytics
|
||
|
||
// 记录关键路径
|
||
Crashlytics.crashlytics().log("Reading session opened: \(materialId)")
|
||
|
||
// 设置用户标识
|
||
Crashlytics.crashlytics().setUserID(userId)
|
||
|
||
// 自定义 key
|
||
Crashlytics.crashlytics().setCustomValue(materialId, forKey: "last_material_id")
|
||
Crashlytics.crashlytics().setCustomValue(sessionState, forKey: "session_state")
|
||
```
|
||
|
||
### 3.2 Rust FFI 层
|
||
|
||
Rust panic 通过 `std::panic::catch_unwind` 捕获后，通过 FFI 回调通知 Swift：
|
||
|
||
```swift
|
||
// zx_document.swift (uniffi generated)
|
||
// Rust panics are caught and returned as errors;
|
||
// Swift layer logs them to Crashlytics
|
||
do {
|
||
try documentRuntime.openMaterial(materialId)
|
||
} catch {
|
||
Crashlytics.crashlytics().record(error: error)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 关键监控点
|
||
|
||
| 位置 | 监控内容 |
|
||
|------|----------|
|
||
| `AppDelegate.didFinishLaunching` | 启动崩溃 |
|
||
| `MaterialReaderView.onAppear` | 阅读器打开 |
|
||
| `UploadScheduler.flush()` | 批量上传 |
|
||
| `RuntimeRecoveryService.recover()` | 会话恢复 |
|
||
| `FFI 调用点` | Rust panic |
|
||
| `sceneDidEnterBackground` | 后台切换 |
|
||
|
||
---
|
||
|
||
## 5. 符号化
|
||
|
||
### 5.1 Swift 符号
|
||
|
||
Xcode Archive 自动包含 dSYM。Crashlytics 通过 upload-symbols 脚本自动符号化。
|
||
|
||
### 5.2 Rust 符号
|
||
|
||
Rust xcframework 的 dSYM 需手动生成：
|
||
|
||
```bash
|
||
# 构建带调试符号的 Rust 库
|
||
cargo build --release -p zx_document_ffi --target aarch64-apple-ios
|
||
|
||
# 提取 dSYM
|
||
dsymutil target/aarch64-apple-ios/release/libzx_document_ffi.a \
|
||
-o ZxDocumentRuntime.dSYM
|
||
|
||
# 上传到 Crashlytics
|
||
${PODS_ROOT}/FirebaseCrashlytics/upload-symbols \
|
||
-gsp GoogleService-Info.plist \
|
||
-p ios ZxDocumentRuntime.dSYM
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 告警阈值
|
||
|
||
| 指标 | 阈值 | 响应 |
|
||
|------|:--:|------|
|
||
| Crash-free rate | < 99% | 紧急修复 |
|
||
| Crash-free rate | < 99.5% | P1 调查 |
|
||
| 新 crash 类型 | ≥ 1 | 24h 内分类 |
|
||
| 回归 crash | ≥ 1 | 立即回滚 |
|
||
|
||
---
|
||
|
||
## 7. 隐私合规
|
||
|
||
- Crashlytics 不采集 PII（个人身份信息）
|
||
- 用户 ID 使用匿名化标识符（UUID），不关联登录邮箱
|
||
- 崩溃日志保留 90 天
|
||
- 在隐私政策中声明使用 Firebase Crashlytics
|
||
|
||
---
|
||
|
||
## 8. 相关文档
|
||
|
||
- [App Store 提审 Checklist](./app-store-submission-checklist.md)
|
||
- [iOS CI/CD](./ios-ci.yml) (.github/workflows/)
|