build-ipa/ironSource/PlayBTopOn/CHANGES_SUMMARY.md

iOS 12/13 兼容性修复总结

修复时间

2025-01-01

问题描述

应用在 iOS 12/13 系统上启动时崩溃，原因：

1. 使用了 Task { await ... } 等 Swift Concurrency API（需要 iOS 15+）
2. 无条件导入 AppTrackingTransparency 框架（仅 iOS 14+ 可用）

已修复的文件

1. PlayBTopOn/AppDelegate.swift

修改内容：

• ❌ 移除：Task { await BbbAdManager.shared.initAd() }
• ✅ 替换为：DispatchQueue.global(qos: .userInitiated).async { BbbAdManager.shared.initAd() }

影响： 兼容 iOS 12+，使用传统的 GCD 异步方式

2. PlayBTopOn/playB/YL_PlayVC.swift

修改内容：

• ❌ 移除：Task { await BbbAdManager.shared.waitForSDKInitialization() ... }
• ✅ 替换为：BbbAdManager.shared.waitForSDKInitialization { BbbAdManager.shared.loadAd(view: self) }

影响： 使用回调方式等待 SDK 初始化完成

3. PlayBTopOn/playB/bbbAdManager.swift

修改内容：

• ✅ 新增：initAd(completion:) - 基于回调的初始化方法（兼容所有版本）
• ✅ 新增：waitForSDKInitialization(completion:) - 基于回调的等待方法
• ✅ 重命名：原 initAd() async → initAdAsync() 并标记 @available(iOS 15.0, *)
• ✅ 重命名：原 waitForSDKInitialization() async → waitForSDKInitializationAsync() 并标记 @available(iOS 15.0, *)
• 🔴 关键修复： 移除 CheckedContinuation 类型，改用普通闭包数组
  • ❌ private var initializationContinuations: [CheckedContinuation<Void, Never>] = []
  • ✅ private var initializationCallbacks: [() -> Void] = []

影响： 提供双版本 API，默认使用回调方式，移除了导致 iOS 12 崩溃的 Swift Concurrency 类型

4. PlayBTopOn/playB/idfa.swift

修改内容：

• ❌ 移除：顶部的 import AppTrackingTransparency
• ✅ 添加：#if canImport(AppTrackingTransparency) import AppTrackingTransparency #endif
• ✅ 添加：所有 ATT 相关代码都用 #if canImport(AppTrackingTransparency) 包裹
• ✅ 修改：checkATT() 方法使用条件编译，低版本自动降级到旧 API

影响： 编译时只在支持的平台引入 ATT，运行时自动选择合适的 IDFA 获取方式

5. PlayBTopOn/playB/YL_NetWorkManager.swift

修改内容：

• ❌ 移除：顶部的 import AppTrackingTransparency
• ✅ 添加：#if canImport(AppTrackingTransparency) import AppTrackingTransparency #endif
• ✅ 修改：getAdvertisingTrackingStatus() 使用条件编译
• ✅ 修改：isAdvertisingTrackingEnabled() 使用条件编译

影响： ATT API 调用被条件编译保护，低版本使用 ASIdentifierManager 旧 API

新增文件

1. iOS12_COMPATIBILITY_GUIDE.md

详细的配置指南，包括：

• 问题说明
• Xcode 配置步骤
• 测试验证方法
• 常见问题解答

2. check_ios12_compatibility.sh

自动化检查脚本，检测：

• Task/async/await 未保护的使用
• AppTrackingTransparency 导入保护
• Podfile 和项目配置
• 其他潜在问题

3. CHANGES_SUMMARY.md

本文件，记录所有修改内容

验证结果

✅ 所有代码检查通过！

======================================
iOS 12/13 兼容性检查
======================================

✓ 未发现 Task 调用
✓ 所有 async 函数都已保护  
✓ AppTrackingTransparency 导入已正确保护
✓ Podfile 最低版本: iOS 12.0
✓ 找到 Info.plist

错误: 0
警告: 3

🔴 关键崩溃修复

问题： 应用在打印 "XS- 开始创建 BbbAdManager.shared 单例" 后崩溃

原因： CheckedContinuation 类型在 iOS 12 上不存在

解决： 已替换为普通闭包数组

详细信息请查看：CRITICAL_FIX.md

仍需手动操作的事项

⚠️ 重要：在 Xcode 中配置弱链接

1. 打开 Xcode 项目

   open PlayBTopOn.xcworkspace
   

2. 配置 AppTrackingTransparency 为 Optional

   • 选择项目 → TARGETS → PlayBTopOn
   • Build Phases → Link Binary With Libraries
   • 找到或添加 AppTrackingTransparency.framework
   • 将 Status 改为 Optional (不是 Required)

3. 验证 Deployment Target

   • General → Deployment Info
   • iOS Deployment Target 设置为 12.0

可选：添加 ATT 权限说明

如果需要在 iOS 14+ 上请求追踪权限，在 Info.plist 中添加：

<key>NSUserTrackingUsageDescription</key>
<string>我们需要获取您的广告标识符以提供个性化广告体验</string>

兼容性矩阵

iOS 版本	支持状态	IDFA 获取方式	异步调用方式
iOS 12.x	✅ 完全支持	ASIdentifierManager	DispatchQueue + 回调
iOS 13.x	✅ 完全支持	ASIdentifierManager	DispatchQueue + 回调
iOS 14.x	✅ 完全支持	ATTrackingManager	DispatchQueue + 回调
iOS 15+	✅ 完全支持	ATTrackingManager	async/await 或 回调

测试建议

1. 编译测试

# 清理构建
xcodebuild clean

# 构建项目
xcodebuild build -workspace PlayBTopOn.xcworkspace \
  -scheme PlayBTopOn \
  -destination 'platform=iOS Simulator,name=iPhone 8,OS=12.4'

2. 模拟器测试

• iOS 12.4 (iPhone 8)
• iOS 13.7 (iPhone 11)
• iOS 14.8 (iPhone 12)
• iOS 15.0+ (任意设备)

3. 真机测试

在实际设备上测试，特别是：

• 旧设备运行 iOS 12/13
• 新设备运行 iOS 14+

回滚方法

如果需要回滚这些更改：

git log --oneline  # 查看提交历史
git revert <commit-hash>  # 回滚指定提交

或者从备份恢复：

cp -r PlayBTopOn.backup/* PlayBTopOn/

技术要点总结

Swift Concurrency 兼容性

• Task / async / await 需要 iOS 15+
• 使用 @available(iOS 15.0, *) 标记
• 提供基于 DispatchQueue 和回调的替代方案

弱链接 (Weak Linking)

• 框架在 Build Phases 中设置为 Optional
• 运行时动态加载，不存在也不崩溃
• 代码中用 #if canImport() 条件编译

版本检查

• @available(iOS 14, *) - 运行时检查
• #if canImport() - 编译时检查
• 两者结合使用最安全

相关文档

• iOS12_COMPATIBILITY_GUIDE.md - 详细配置指南
• check_ios12_compatibility.sh - 自动检查脚本

联系支持

如遇问题，请：

1. 运行 ./check_ios12_compatibility.sh 检查配置
2. 查看 Xcode 控制台的崩溃日志
3. 确认 AppTrackingTransparency 已设置为 Optional

---

修复完成 ✅
最低支持版本：iOS 12.0
测试状态：代码验证通过，待真机测试