126 lines
4.6 KiB
Markdown
126 lines
4.6 KiB
Markdown
# iOS 12/13 兼容性配置指南
|
||
|
||
## 问题说明
|
||
在 iOS 12/13 系统上，如果应用使用了 `AppTrackingTransparency` 框架（iOS 14+ 才有），即使代码中有 `@available(iOS 14, *)` 检查，应用启动时也会因为找不到该框架而直接崩溃。
|
||
|
||
## 已完成的代码修复
|
||
✅ 移除了所有 `Task { await ... }` 代码，改用 `DispatchQueue` 和回调
|
||
✅ 使用 `#if canImport(AppTrackingTransparency)` 条件编译
|
||
✅ 所有 async/await 代码都标记了 `@available(iOS 15.0, *)`
|
||
|
||
## 需要在 Xcode 中手动配置的步骤
|
||
|
||
### ⚠️ 重要：将 AppTrackingTransparency 设置为弱链接
|
||
|
||
1. **打开 Xcode 项目**
|
||
- 打开 `PlayBTopOn.xcworkspace`
|
||
|
||
2. **进入项目设置**
|
||
- 在左侧项目导航栏中，点击项目根节点 `PlayBTopOn`
|
||
- 选择 `TARGETS` -> `PlayBTopOn`
|
||
|
||
3. **配置弱链接**
|
||
- 选择 `Build Phases` 标签
|
||
- 展开 `Link Binary With Libraries`
|
||
- 找到或添加 `AppTrackingTransparency.framework`
|
||
- 将右侧的 `Status` 列从 `Required` 改为 `Optional`
|
||
|
||
**如果列表中没有 AppTrackingTransparency.framework：**
|
||
- 点击 `+` 按钮
|
||
- 搜索 `AppTrackingTransparency.framework`
|
||
- 添加后，将其状态设置为 `Optional`
|
||
|
||
4. **验证设置**
|
||
- 确保 `AppTrackingTransparency.framework` 的状态显示为 `Optional`
|
||
- 这样在 iOS 12/13 上，即使框架不存在，应用也不会崩溃
|
||
|
||
### 检查部署目标
|
||
|
||
1. **设置最低支持版本**
|
||
- 在 `TARGETS` -> `PlayBTopOn` -> `General` 标签
|
||
- 找到 `Deployment Info` 部分
|
||
- 将 `iOS Deployment Target` 设置为 `iOS 12.0`
|
||
|
||
2. **检查 Podfile**
|
||
- 打开项目根目录的 `Podfile`
|
||
- 确保第一行包含：`platform :ios, '12.0'`
|
||
- 如果修改了，运行 `pod install`
|
||
|
||
### 可选：添加 NSUserTrackingUsageDescription（如果需要在 iOS 14+ 上请求 IDFA）
|
||
|
||
如果你计划在 iOS 14+ 上请求用户授权追踪，需要在 `Info.plist` 中添加说明：
|
||
|
||
```xml
|
||
<key>NSUserTrackingUsageDescription</key>
|
||
<string>我们需要获取您的广告标识符以提供个性化广告体验</string>
|
||
```
|
||
|
||
## 测试验证
|
||
|
||
### 在 iOS 12/13 设备或模拟器上测试
|
||
1. 选择 iOS 12 或 iOS 13 的模拟器
|
||
2. 清理项目：`Product` -> `Clean Build Folder` (Cmd+Shift+K)
|
||
3. 编译运行：`Product` -> `Run` (Cmd+R)
|
||
4. 检查控制台日志，确保没有崩溃
|
||
|
||
### 在 iOS 14+ 设备上测试
|
||
1. 选择 iOS 14+ 的模拟器或真机
|
||
2. 运行应用，ATT 功能应该正常工作
|
||
3. 检查是否能正常请求广告追踪权限
|
||
|
||
## 代码修改总结
|
||
|
||
### 1. AppDelegate.swift
|
||
- ❌ 移除：`Task { await BbbAdManager.shared.initAd() }`
|
||
- ✅ 替换：`DispatchQueue.global(qos: .userInitiated).async { BbbAdManager.shared.initAd() }`
|
||
|
||
### 2. YL_PlayVC.swift
|
||
- ❌ 移除：`Task { await BbbAdManager.shared.waitForSDKInitialization() ... }`
|
||
- ✅ 替换：`BbbAdManager.shared.waitForSDKInitialization { ... }`
|
||
|
||
### 3. bbbAdManager.swift
|
||
- ✅ 添加：基于回调的 `initAd(completion:)` 方法
|
||
- ✅ 添加：基于回调的 `waitForSDKInitialization(completion:)` 方法
|
||
- ✅ 保留：async/await 版本（标记 `@available(iOS 15.0, *)`）
|
||
|
||
### 4. idfa.swift
|
||
- ✅ 使用：`#if canImport(AppTrackingTransparency)` 条件编译
|
||
- ✅ 移除：文件顶部的无条件 `import AppTrackingTransparency`
|
||
|
||
### 5. YL_NetWorkManager.swift
|
||
- ✅ 使用：`#if canImport(AppTrackingTransparency)` 条件编译
|
||
- ✅ 保护：所有使用 `ATTrackingManager` 的代码
|
||
|
||
## 兼容性保证
|
||
|
||
| iOS 版本 | 支持状态 | 说明 |
|
||
|---------|---------|------|
|
||
| iOS 12.x | ✅ 完全支持 | 使用旧版 IDFA API |
|
||
| iOS 13.x | ✅ 完全支持 | 使用旧版 IDFA API |
|
||
| iOS 14.x | ✅ 完全支持 | 使用 ATT 框架 |
|
||
| iOS 15+ | ✅ 完全支持 | 支持 async/await + ATT |
|
||
|
||
## 常见问题
|
||
|
||
### Q: 为什么需要设置为 Optional？
|
||
A: 因为 AppTrackingTransparency.framework 在 iOS 14 才引入，iOS 12/13 系统中不存在这个框架。设置为 Optional 后，系统会在运行时动态加载，如果不存在也不会崩溃。
|
||
|
||
### Q: 代码中的 `#if canImport()` 是什么？
|
||
A: 这是编译时检查，确保只在可以导入该框架的环境下才编译相关代码。
|
||
|
||
### Q: 如果忘记设置 Optional 会怎样？
|
||
A: 应用会在 iOS 12/13 启动时立即崩溃，错误信息类似于 "dyld: Library not loaded: /System/Library/Frameworks/AppTrackingTransparency.framework"
|
||
|
||
## 编译和发布
|
||
|
||
编译通过后，可以正常打包发布：
|
||
- Archive: `Product` -> `Archive`
|
||
- 导出 IPA 进行分发测试
|
||
- 确保在不同 iOS 版本上都进行了测试
|
||
|
||
---
|
||
|
||
**修复完成时间**: 2025-01-01
|
||
**最低支持版本**: iOS 12.0
|
||
**推荐测试版本**: iOS 12.5, iOS 13.7, iOS 14.8, iOS 15.0+
|