deepvoice_client/ios/ReplayKit_Integration_Guide.md

iOS ReplayKit 悬浮窗集成指南

📋 概述

本指南说明如何在 Xcode 中配置 ReplayKit Broadcast Upload Extension 以实现全局字幕悬浮窗功能。

🔧 Xcode 项目配置步骤

1. 添加 Broadcast Upload Extension Target

1. 在 Xcode 中打开 ios/Runner.xcworkspace
2. 选择项目根节点 → 点击 "+" 添加新 Target
3. 选择 "Broadcast Upload Extension"
4. 配置信息：
   • Product Name: BroadcastExtension
   • Bundle Identifier: com.saitong.voitrans.BroadcastExtension
   • Language: Swift
   • 确保 "Include UI Extension" 未选中

2. 配置 Extension Target

2.1 替换默认文件

• 删除自动生成的 SampleHandler.swift
• 将项目中的 ios/BroadcastExtension/SampleHandler.swift 复制到 Extension target
• 将项目中的 ios/BroadcastExtension/Info.plist 替换 Extension 的 Info.plist

2.2 添加 Entitlements

• 在 Extension target 的 Build Settings 中设置 Code Signing Entitlements
• 指向 ios/BroadcastExtension/BroadcastExtension.entitlements

2.3 配置 Build Settings

• iOS Deployment Target: 16.0 (与主应用保持一致)
• Swift Language Version: Swift 5
• Enable Bitcode: No

3. 配置 App Groups

3.1 在 Apple Developer Portal 中：

1. 创建 App Group: group.com.saitong.voitrans.shared
2. 将主应用和 Extension 都添加到此 App Group

3.2 在 Xcode 中：

1. 主应用 Target → Signing & Capabilities → 添加 "App Groups" capability
2. Extension Target → Signing & Capabilities → 添加 "App Groups" capability
3. 两个 target 都勾选 group.com.saitong.voitrans.shared

4. 更新主应用配置

4.1 添加 ReplayKit 框架

• 主应用 Target → Build Phases → Link Binary With Libraries
• 添加 ReplayKit.framework

4.2 更新 Info.plist

在主应用的 Info.plist 中添加：

<key>NSCameraUsageDescription</key>
<string>需要摄像头权限以支持屏幕录制功能</string>
<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限以支持音频录制功能</string>

📱 使用说明

Flutter 调用方式

// 启动悬浮窗（会弹出系统录屏选择界面）
await floatingWindowManager.enableFloatingWindow();

// 更新字幕内容
await floatingWindowManager.updateFloatingWindowContent(
  FloatingWindowData(
    sourceText: '你好',
    translatedText: 'Hello',
    sourceLanguage: '中文',
    targetLanguage: '英语',
    timestamp: DateTime.now(),
    isIntermediate: false,
  ),
);

// 停止悬浮窗
await floatingWindowManager.disableFloatingWindow();

用户操作流程

1. 用户点击"启用悬浮窗"按钮
2. 系统弹出"开始直播屏幕"选择界面
3. 用户选择 "Voitrans 字幕悬浮窗" 选项
4. 系统开始屏幕录制，悬浮窗显示在屏幕顶部
5. 应用实时更新字幕内容
6. 用户可以在任何应用中看到翻译字幕

⚠️ 注意事项

开发阶段

• 确保两个 target 使用相同的开发者账号签名
• App Groups 必须在 Apple Developer Portal 中正确配置
• Extension 的 Bundle ID 必须是主应用的子域名

发布阶段

• Extension 会随主应用一起打包发布
• 用户首次使用时需要授权屏幕录制权限
• 符合 App Store 审核规范，因为使用的是官方 ReplayKit API

用户体验

• 录制期间状态栏会显示红色录制指示器
• 悬浮窗位置固定在屏幕顶部中央
• 支持实时字幕更新和语言切换
• 可以通过停止录制来关闭悬浮窗

🔍 故障排除

常见问题

1. Extension 无法启动

   • 检查 Bundle ID 配置
   • 确认 App Groups 权限配置正确
   • 验证代码签名设置

2. 字幕不更新

   • 检查 App Groups 数据同步
   • 确认 UserDefaults 键名一致
   • 查看 Extension 日志输出

3. 编译错误

   • 确保 iOS Deployment Target 一致
   • 检查 Swift 版本设置
   • 验证框架依赖配置

调试方法

1. 使用 Xcode 的 Device Console 查看 Extension 日志
2. 在 SampleHandler 中添加 print 语句进行调试
3. 检查 App Groups 中的数据是否正确写入

📚 相关文档

• Apple ReplayKit Documentation
• Broadcast Upload Extension Guide
• App Groups Documentation