# UniApp 与 uni-app x 接入 RTC

UniApp 使用同批 `uni_modules/akstream-rtc` 插件：Android/iOS App 通过 UTS 连接配套原生 SDK，Web 目标复用 Web SDK，小程序目标使用其平台适配。业务页面接收事件并布置视图，不自己处理 SDP、WebSocket 重连或原生媒体线程。

```mermaid
sequenceDiagram
    participant Page as UniApp 页面
    participant Bridge as UTS 桥接
    participant SDK as 原生或 Web SDK
    Page->>Bridge: roomAction + requestId
    Bridge-->>Page: accepted：命令已收到
    Bridge->>SDK: 执行会议动作
    SDK-->>Page: roomActionResult：真实结果
```

## 先准备运行环境

1. 复制同批 UTS 源、Android AAR、iOS XCFramework、Web/小程序核心代码和离线白板资源，保留原有目录结构。
2. 使用你自己的 DCloud AppID、包名、签名和业务 HTTPS 地址。测试工程的身份、CA 与服务器地址不能用于正式包。
3. 原生依赖变更后制作自定义基座或新的完整安装包。普通页面热更新不会替换 AAR 或 Framework；标准基座提示插件不可用时，不能据此判断 SDK 功能失败。
4. 分别编译 Android 与 iOS，并检查完整日志。只看到 HBuilderX 最后的“编译成功”，不代表此前没有 UTS/Swift 错误。

普通 uni-app 的原生视频页使用 nvue，uni-app x 使用 uvue；Web 页面走对应 Web 渲染。每个远端视图绑定真实 `publicationId`，摄像头和屏幕共享是两路内容。SDK 事件中的 `accepted` 只说明命令已接收；入会、发布和录制结果还要等待后续事件或查询。

业务页先创建句柄并订阅事件，再调用入会；下例的 `serverUrl/roomId/accessTicket` 来自业务后端，代码运行在集成了同批插件的 UniApp 页面中：

```js
import { createRtcClient, invokeRtcClient, disposeRtcClient } from '@/uni_modules/akstream-rtc'

const rtcId = createRtcClient({
  serverUrl,
  onEvent(event) {
    const detail = JSON.parse(event.payloadJson || 'null')
    console.log('RTC 事件', event.type, detail)
  }
})

invokeRtcClient(rtcId, 'join', JSON.stringify({
  roomId, accessTicket, microphone: false, camera: false
}), result => {
  if (!result.accepted) console.error(result.message)
})

// 页面最终销毁时调用：disposeRtcClient(rtcId)
```

`result.accepted` 不等于已经入会。页面要等入会事件，若处于等候室则先显示等候状态；不要立即发布摄像头。离会后需要业务后端新签一次性票据，不能把旧票重放。

## 把媒体放到页面上

原生页面用插件组件承载本地与远端视频，远端卡片的 key 使用真实 `publicationId`；当 SDK 报告发布移除时，只移除对应卡片：

```html
<akstream-rtc :clientId="rtcId" :localPreview="true" />
<akstream-rtc :clientId="rtcId" :publicationId="remotePublicationId" />
```

普通 uni-app App 的视频页应使用 nvue，uni-app x 使用 uvue；Web 目标按 Web SDK 的 DOM/媒体路径。两个远端摄像头加一条共享屏幕就是三张独立媒体视图。音频由 SDK 管理，不必再为每张视频卡片额外创建同路音频播放器。

功能按事件与能力展示：`getRtcFeatures(id)` 返回 `supported`、`unsupported`、`configurationRequired` 或 `notImplemented`。前两者分别表示可用与当前端不支持；`configurationRequired` 需要宿主配置，例如 iOS ReplayKit 扩展；`notImplemented` 表示当前适配还没实现。麦克风被主持禁止不是“设备不存在”，应显示主持限制的原因。

匹配目标版本 的 `AkRtcUniClient` 提供 `startContinuousRecording()`、`stopContinuousRecording(recordingId)`、`getContinuousRecording()`；原生桥接事件 `recordingState` 报告当前状态。录制和回放界面由宿主编写。`roomAction` 等待与 `requestId` 对应的真实结果，不能把桥接 ACK 当作操作成功。档案查询使用 `createUniArchiveClient` 或同批原生 UTS 档案接口，业务后端仍须签独立短时档案票据。全部门面函数与状态见[UniApp 函数参考](uniapp-api.md)。

离会调用 `leave`，页面或模块最终销毁调用 `disposeRtcClient`。Android 编译、iOS 编译与原生桥测试不能代替自定义基座和两台真机的完整会议验收；现有验收边界见[端侧验收清单](acceptance.md)。

验收时分别记录：HBuilderX UTS 编译日志、自定义基座所含 AAR/XCFramework 版本、Android/iOS 实际安装包、两端相互接收的画面和声音。标准基座提示原生插件不可用时先重建基座；iOS 编译成功却启动失败时先排查开发者信任和描述文件，再查 RTC。录制命令收到 ACK 之后继续等待对应 `roomActionResult`，并确认另一端也收到了 `recordingState`，不能把按钮变色当作服务器已经落盘。