# Web/H5 RTC SDK 函数参考

适用 `匹配目标版本` 同批交付的 `@akstream/rtc-web-sdk`。H5 的 `AkRtcH5Client` 是 `AkRtcWebClient` 的别名；Android WebView 和 iOS WKWebView 也使用这套浏览器接口，但媒体权限、证书和前后台由原生宿主处理。这里列 SDK **公开方法**，页面布局不属于 SDK。先按[Web 接入步骤](web.md)完成只看入会，再查本页。

```js
import { AkRtcWebClient } from '@akstream/rtc-web-sdk'
const client = new AkRtcWebClient(serverUrl, { onState: (state, detail) => console.log(state, detail) })
const joined = await client.join(roomId, accessTicket, { platform: 'pc-web' })
if (joined.admissionStatus === 'Admitted') await client.startCameraAndMicrophone({ audio: true, video: true })
```

`serverUrl` 是该设备可访问、可信的 AKStream.Next HTTPS 根地址；`accessTicket` 是业务后端为此人、此会议签的一次性票据。除特别注明外，异步方法失败会拒绝 Promise。401 应重新向业务后端取票或登录，403 表示当前角色/设备/权限不允许，不能无限重试；`retryable` 缺失表示未知，不等于允许重试。

## 会话与身份

| 函数 | 入参 | 返回 | 用途与特殊情况 |
|---|---|---|---|
| `new AkRtcWebClient(serverUrl, events?)` | HTTPS 服务地址；可选事件回调对象 | 客户端实例 | 每个会议会话创建一份；不要把平台 API Token 放进浏览器。 |
| `join(roomId, accessTicket, options?)` | 房间 ID、一次性票据；`options` 可设 `autoSubscribe`、`passcode`、`platform`、`clientVersion` | `RtcJoinResult`：成员、`participantToken`、到期时间、最终能力、`admissionStatus` | 票据消费后不能重放；`Waiting` 只表示进入等候室，尚不能采集/发布。SDK负责设备令牌续签。 |
| `createMeeting(settings, creator)` | 房间设置；由**业务后端**实现的 `creator(settings)` 回调 | `{roomId, accessTicket, ...}` | SDK传递幂等请求标识并校验结果；回调不得把管理令牌交给终端。创建失败重试使用相同业务参数。 |
| `listDemoRooms()`、`createDemoMeeting(settings)`、`issueDemoAccessTicket(options)` | Demo 房间/票据参数 | Demo 房间列表、建会结果或测试票据 | 只用于独立测试环境，正式业务用业务后端签票。 |
| `listMembers()` | 无 | 成员 ID、名称、角色、状态列表 | 房间快照；人员离会、换机和主持移交后重新取或监听事件。 |
| `refreshMedia()` | 无 | `Promise<void>` | 重新核对当前发布/订阅；网络恢复时 SDK 已自动重连，页面无需循环调用。 |
| `leave(options?)` | 可选离会参数 | `Promise<void>` | 当前设备离会并释放媒体、信令与订阅；路由切换/页面销毁只走一条清理路径。 |

`RtcJoinResult.capabilities` 是服务端最终授予的能力，不等于客户端请求的能力；`participantToken` 由 SDK 管理，不要持久化或打印。`admissionStatus` 为 `Admitted`、`Waiting` 或拒绝状态时，宿主以回调/结果更新页面。

## 本机采集、设备与共享

| 函数 | 入参 | 返回 | 用途与特殊情况 |
|---|---|---|---|
| `startCameraAndMicrophone(options?)` | `audio/video` 开关、设备 ID、前/后摄像头、宽高和帧率期望 | `MediaStream` | 用户手势后申请权限并尝试发布。返回本机流不代表对方已收到，须核对发布和远端帧。 |
| `getLocalMediaState()` | 无 | `micEnabled/cameraEnabled/screenSharing` 及允许状态 | 读取当前实际状态，按钮不要在点击时自行翻转。 |
| `setTrackEnabled(kind, enabled)` | `MicrophoneAudio` 或 `CameraVideo`；布尔值 | `Promise<void>` | 本机静音/关相机；主持人收权或系统拒绝时不能靠再次设为 `true` 绕过。 |
| `recoverLocalMedia()` | 无 | `Promise<void>` | 显式尝试恢复本机采集；设备被占用、系统授权或主持收权仍可能阻止恢复。 |
| `listMicrophones()`、`listCameras()` | 无 | 设备 ID、组 ID、名称列表 | 未授权前设备名称可能为空；设备拔插后重新查询。 |
| `setMicrophoneDevice(deviceId)`、`setCameraDevice(deviceId)` | 浏览器返回的设备 ID | 新 `MediaStreamTrack` 或 `null` | 切换实际输入；旧设备失效或权限取消时处理拒绝。 |
| `getInputDeviceState()` | 无 | 当前麦克风与摄像头设备 ID | 用于同步设备选择控件，不把 ID 当成跨会稳定硬件身份。 |
| `switchCamera(deviceIdOrOptions?)` | 摄像头 ID 或采集选项 | 新视频轨 | 移动端常用于前后摄切换；结果以新轨道和状态回调为准。 |
| `getVideoModes()`、`setCameraQuality(quality)` | 质量含目标宽、高、帧率 | 可用模式；质量结果或 `pending` | 目标模式受设备与主持策略限制；`pending` 不是实际已达到。 |
| `startScreenShare()`、`stopScreenShare()` | 开始需浏览器用户手势和系统选择器；停止无参 | `MediaStream` / `void` | 屏幕是独立发布；用户在系统界面停止时监听 `onScreenShareEnded`。 |
| `getScreenShareSupport()` | 无 | `{available, reason}` | 先判断当前浏览器/宿主是否具备共享能力。 |
| `getCameraOverlaySupport()`、`startCameraOverlay(element)` | 视频元素 | 支持状态 / `void` | 画中画能力受浏览器与宿主限制；不改变服务端发布。 |

## 远端媒体与画面

| 函数 | 入参 | 返回 | 用途与特殊情况 |
|---|---|---|---|
| `listPublications()` | 无 | `RtcPublication[]` | 一位成员可以有摄像头、麦克风和屏幕等多路；以 `publicationId` 区分。 |
| `syncSubscriptions(publications)` | 当前可见发布列表 | 每项 `PromiseSettledResult<void>` | 为列表核对订阅；逐项失败不会让其他订阅全部丢失。 |
| `attachRemoteMedia(subscriptionId, element, options?)` | 订阅 ID、`audio/video` 元素、可选音量/旋转 | `Promise<void>` | 把已收到的轨道绑定到宿主元素；浏览器自动播放限制仍需用户点击。 |
| `detachRemoteMedia(subscriptionId, element)` | 同一订阅 ID 与元素 | `void` | 移除视图时解除绑定；远端离开时也监听 `onRemoteTrackRemoved`。 |
| `attachLocalPreview(element, stream)` | 本机 `video`、本机流或 `null` | `{hasVideo}` | 本机预览应静音，避免扬声器回授。 |
| `setRemoteAudioVolume(subscriptionId, volume)` | 订阅 ID、0～1 音量 | 实际音量数字 | 仅改变本机播放，不对远端执行静音治理。 |
| `setRemoteVideoTransform(subscriptionId, transform?)`、`setRemotePresentation(publicationId, transform?)` | 镜像、翻转、旋转 | 标准化变换 | 本地显示变换不改录制原轨；订阅与发布 ID 不可混用。 |
| `getRemotePresentation(publicationId)`、`setLocalVideoTransform(element, transform?)` | 发布 ID 或本机视频元素 | 当前/标准化变换 | 用于页面显示；不要把变换误当摄像头真实方向。 |
| `getActiveSpeakers()`、`getActiveSpeakerSupport()` | 无 | 发言成员与电平 / 支持状态 | 反映媒体检测，不是语音识别或用户身份鉴定。 |
| `setRemoteVolume(volume)` | 0～1 | `void` | 所有远端音频的本地总音量；不发送主持控制。 |

## 协作、治理、录制和诊断

| 函数 | 入参 | 返回 | 用途与特殊情况 |
|---|---|---|---|
| `sendChatMessage(text, options?)` | 文本；可选 `targetParticipantId`、结构化 payload | 本地请求 ID | 私发只对目标及发送者可见；最终结果以聊天/事件回调为准。 |
| `listChatHistory(afterSequence?, pageSize?)` | 事件序号、页大小 | `{rows, ...}` | 按序号续读，不能只读第一页就认为历史完整。 |
| `uploadAttachment(file, options?)` | `File/Blob`；目标成员、说明、`chat/whiteboard` 用途、文件名 | `RtcAttachmentIssue` | 提交前会重查设备和权限；白板图片需随后提交白板对象事件。 |
| `resolveAttachment(downloadUrl, metadata?)` | 服务端授权的下载地址；可选名称/类型 | 浏览器对象 URL | 只用于当前有权看的附件；不缓存成永久公开地址。 |
| `getWhiteboardEvents()`、`attachWhiteboard(container)` | 白板容器 | 当前对象事件 / 卸载函数 | 白板 UI 是可选宿主组件；退出时调用卸载函数。 |
| `sendSignal(type, payload?)` | SDK 支持的信令类型及数据 | 请求 ID | 高级接入用；普通治理应使用 `performRoomAction` 的白名单动作。 |
| `performRoomAction(action, payload?)` | [会议控制动作](room-actions.md)中的动作名与参数 | 该动作响应 | 服务端再次校验当前主持、设备和能力；通用入口不允许任意拼 URL。 |
| `startContinuousRecording()`、`stopContinuousRecording(recordingId)`、`getContinuousRecording()` | 停录需要本次 `recordingId` | 录制状态或无活动任务时 `null` | 启停仅当前主持人；`Stopping` 是收尾中，历史档案用独立[档案 SDK](archive-api.md)。 |
| `getPublicationStats()`、`getMediaDiagnostics()` | 无 | 发布统计 / 媒体诊断 | 统计值用于排障，不代表服务端已保存媒体。 |
| `reportEndpointInfo()`、`getEndpointInfo()` | 无 | 本机上报快照 / 在线终端参数列表 | 只上报可获得的参数，不收集硬件唯一标识；列表按服务端近 90 秒数据。 |
| `getAudioOutputState()`、`getAudioOutputCapabilities()`、`getAudioOutputDevices()`、`setAudioOutput(deviceId)` | 输出设备 ID | 当前状态/支持原因/列表/`void` | 选择输出设备依赖浏览器支持和用户授权；失败不影响入会。 |
| `getNativeScreenSession()`、`installNativeHostBridge(target?)` | 受信任原生宿主的 Window | 临时共享上下文 / 卸载函数 | **仅原生宿主桥接**；上下文含短时令牌，不写日志、不发给网页第三方。 |
| `attachMeetingControls(container)` | 宿主容器 | 卸载函数，可选择页签 | 可选示例控件；业务应用可自行实现 UI，协议仍由 SDK 执行。 |

## 事件回调与错误处理

构造函数的 `events` 中订阅事件；页面卸载时先 `leave()`，再移除自己创建的 DOM。所有事件可能在重连后补偿到达，按事件序号和当前会话处理，不能把旧会话的主持/踢出动作应用到新会话。

| 回调 | 主要数据 | 页面处理 |
|---|---|---|
| `onState(state, detail)`、`onAdmission()`、`onAdmissionDenied()` | 连接、准入状态与说明 | 等候室只显示等待；拒绝时向业务后端取新授权。 |
| `onRemoteTrack(remote)`、`onRemoteTrackRemoved(subscriptionId)`、`onTopologyChanged()` | `publicationId`、`subscriptionId`、`MediaStreamTrack` | 为每路创建/释放视图；屏幕与摄像头分开显示。 |
| `onLocalMediaState(state)`、`onCaptureUnavailable(kind, message)`、`onPublicationUnavailable(kind, message)` | 实际麦克风/相机/共享状态与失败原因 | 按实际状态更新按钮，不以本机预览判定发布成功。 |
| `onContinuousRecordingChanged(recording)` | `{recordingId,state,originAtUtc,...}` 或 `null` | 显示录制中/收尾中；`null` 仅表示当前无活动任务。 |
| `onRoomEvent(event)`、`onChatMessage(message)`、`onWhiteboardChanged(events)` | 带序号会议事件、聊天、白板对象 | 按可见范围和序号同步；私发不对其他成员展示。 |
| `onActiveSpeakersChanged(speakers)`、`onVideoGeometry(value)`、`onVideoQualityChanged(result)` | 发言电平、画面比例、质量实际值 | 发言绿框是设备活动检测，质量变化要区分目标与实际。 |
| `onInputDeviceChanged(state)`、`onAudioOutputChanged(state)`、`onLocalMicrophoneChanged(track,settings)`、`onLocalCameraChanged(track,settings)` | 设备 ID、轨道与实际采集设置 | 更新设备选择和本地预览，不把旧 `MediaStreamTrack` 留在新视图。 |
| `onModeration(notice)`、`onSignal(message)` | 主持治理通知、原始会议信令 | 先按当前设备会话核对事件，再更新权限与按钮；业务 UI 通常不需解析低层信令。 |
| `onKicked(reason)`、`onRoomClosed()`、`onLeft()`、`onScreenShareEnded()` | 生命周期通知 | 释放视图与媒体，踢出后不得沿用旧票据重连。 |

Web SDK 类型定义以同批交付的 `Clients/AKStream.Rtc.WebSDK/index.d.ts` 为准。档案客户端的全部函数见[档案函数参考](archive-api.md)，会议动作 payload 见[控制动作参考](room-actions.md)。