# 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 中添加：
```xml
<key>NSCameraUsageDescription</key>
<string>需要摄像头权限以支持屏幕录制功能</string>
<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限以支持音频录制功能</string>
```

## 📱 使用说明

### Flutter 调用方式

```dart
// 启动悬浮窗（会弹出系统录屏选择界面）
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](https://developer.apple.com/documentation/replaykit)
- [Broadcast Upload Extension Guide](https://developer.apple.com/documentation/replaykit/rpbroadcastsamplehandler)
- [App Groups Documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_application-groups)