Repository navigation
Skill references guides sdk mini program api
权威入口是交付的 miniprogram/sdk/index.js 与 index.d.ts,导出 AkRtcMiniClient。本文描述 SDK 方法,不要求第三方自行拼接媒体票据或维护信令协议。先读小程序接入指南,会议动作的 payload 继续查会议动作参考。
const { AkRtcMiniClient } = require('../../sdk')
const client = new AkRtcMiniClient(events)HTTP/媒体初始化等异步操作返回 Promise;组件回调和视图设置方法通常同步。Promise 错误由调用处捕获,异步信令/计时器错误由 onError 反馈。index.d.ts 提供参数、返回和事件形状;扩展模型仍以同版公开 API 契约为准。
| 方法 | 参数与结果 | 使用与失败边界 |
|---|---|---|
normalizeBaseUrl(value)(静态) |
字符串 → HTTPS origin,非法值返回空字符串 | 不允许 HTTP 或携带 userinfo 的服务地址,不替用户建立证书信任 |
join(options) |
baseUrl/roomId/accessTicket 必填;可选 passcode/audio/video/mediaTransport;返回 participant、capabilities、expiresAt、admissionStatus |
audio/video 默认开启意图;只看须都设 false。Waiting 不代表已获准读媒体。初始化失败会收尾本次已创建会话 |
leave(callServer=true) |
Promise | 停止组件、计时器和信令,释放发布及成员;停止发布失败仍尝试离会。false 只用于服务端已结束或明确本地收尾 |
setForeground(foreground) |
布尔值 → Promise | 页面 onHide/onShow 必须转交;后台暂停采集,前台恢复仍受本人意图和主持限制。Waiting 不请求媒体 |
setMediaTransport(mode='auto') |
auto/udp/tcp → void | 本端仅 auto,其他值抛 UNSUPPORTED_MEDIA_TRANSPORT,不是静默降级 |
getPlatformCapabilities() |
{screenCapture:false, independentPublications:false, numericRemoteVolume:false} |
运行前识别当前适配范围;不能据其他端能力推定本端支持 |
join 的示例参数:
await client.join({ baseUrl: meeting.baseUrl, roomId: meeting.roomId,
accessTicket: meeting.accessTicket, passcode: meeting.passcode,
audio: false, video: false, mediaTransport: 'auto' })createMeeting(settings, creator) 由业务回调负责后端建会授权,Promise 返回房间和主持票据。createDemoMeeting(baseUrl, settings)、listDemoRooms(baseUrl)、issueDemoAccessTicket({baseUrl,roomId,displayName,role}) 是 Development 测试入口;role 为 viewer/speaker,不能代替正式业务签票。不要把 API Token 放入 creator 的客户端实现。
| 方法 | 输入 / 返回 | 说明 |
|---|---|---|
bindPusherContext(context) |
live-pusher context / 返回 client | 组件渲染后绑定;SDK 使用它停止和切换摄像头 |
setMicrophoneEnabled(enabled)、setCameraEnabled(enabled)
|
布尔值 / Promise | SDK 处理授权和发布;需同时具有组合发布能力。主持限制可能阻止开启 |
getLocalMediaState() |
{micEnabled,cameraEnabled} |
实际状态,真实推流开始前为 false;页面意图不等于媒体已连通 |
switchCamera() |
返回组件设置 | 前/后摄像头切换,需要已绑定 context;不提供任意摄像头硬件枚举 |
setLocalMirror(mode) |
auto/enable/disable / 设置 | 本地预览镜像 |
setPublishedMirror(enabled) |
布尔值 / 设置 | 绑定推流组件 remote-mirror,实际效果需真机验证 |
setRemoteVideoTransform(value) |
publicationId/mirror/flipVertical/rotation / 设置 |
publicationId 可为 *;旋转按 90° 归一化。未给目标默认全体远端,组件渲染效果按真机能力 |
getRemoteVideoTransform(publicationId) |
目标 ID / 变换 | 查询每路设置;不代表实际像素已处理 |
setRemoteAudioVolume(value) |
0–1 / 设置 | 近零(≤0.01)静音,其余恢复;返回 scalarVolumeUnsupported,细调使用设备音量 |
getAudioOutputCapabilities() |
selectable、actualRouteObservable、reason | 可请求路由,不能读回物理路由 |
getAudioOutputDevices()、setAudioOutput(id)
|
speaker/ear 目录 / 设置 | Demo 绑定 sound-mode;实际路由由微信/系统决定 |
toggleFullscreen(publicationId='')、exitFullscreen()
|
{active,publicationId,mode} / void |
空 ID 为本地,#whiteboard 为白板;这是页面最大化,不是系统全屏 |
getVideoTileHeight(width,maximum,aspect) |
数值 / 像素高度 | 页面布局辅助,不改变上行视频编码 |
| 方法 | 参数 | 作用 |
|---|---|---|
onPusherState(code,generation,publicationId) |
statechange 的 code 与组件 data-* | 识别推流开始、断网、设备失败;旧发布回调不会开启新会话媒体 |
onPusherError(detail,generation,publicationId) |
error 的 errCode/errMsg | 报告失败并收敛实际媒体状态;错误提示不回显可能带签名的原始 URL |
onPusherNetStatus(info,generation,publicationId) |
netstatus 的 detail 或 info | 采集尺寸/FPS 和可观测发布端统计;不捏造未知指标 |
onPlayerState(publicationId,code,generation) |
播放 statechange | 通过 onPlaybackState 报告 connecting/playing/failed;原生错误码可用于排障 |
onPlayerError(publicationId,detail,generation) |
播放 error | 报告渲染/组件错误 |
onPlayerNetStatus(publicationId,info,generation) |
播放 netstatus | 实际画面尺寸;拒绝旧会话、已移除媒体和离会后的回调 |
onAudioVolume(publicationId,volume,generation,local) |
音量 0–100,local 布尔值 | 校验来源后驱动发言高亮;不会把屏幕音频当作本人发言 |
retryPlayback() |
无 / Promise | 前台且获准入会后刷新播放票据及列表;并发去重。由用户触发,不循环入会 |
Demo 的绑定方式如下;sessionGeneration/publicationId/pusherUrl/players 来自 SDK 回调:
<live-pusher id="pusher" url="{{pusherUrl}}" autopush="{{pusherUrl !== ''}}"
mode="RTC" data-generation="{{sessionGeneration}}" data-publication="{{publicationId}}"
bindstatechange="pushState" binderror="pushError" />
<live-player wx:for="{{players}}" wx:key="publicationId" src="{{item.url}}" mode="live" autoplay
data-generation="{{sessionGeneration}}" data-publication="{{item.publicationId}}"
bindstatechange="playerState" binderror="playerError" />pushState(e) { this.rtc.onPusherState(e.detail.code, e.currentTarget.dataset.generation, e.currentTarget.dataset.publication) }
pushError(e) { this.rtc.onPusherError(e.detail, e.currentTarget.dataset.generation, e.currentTarget.dataset.publication) }
playerState(e) { this.rtc.onPlayerState(e.currentTarget.dataset.publication, e.detail.code, e.currentTarget.dataset.generation) }
playerError(e) { this.rtc.onPlayerError(e.currentTarget.dataset.publication, e.detail, e.currentTarget.dataset.generation) }上面四个函数分别作为 Page 对象的方法,实际工程还需绑定 SDK 输出的 muted、enable-camera、enable-mic、镜像和 sound-mode。完整可导入工程以配套 Demo 为准。
| 方法 | 参数与结果 | 注意 |
|---|---|---|
sendChatMessage(text,options) |
非空文字;可选 targetParticipantId/payload | 同步发送信令,未连接会抛错;通过 onChatMessage 接收服务端事件 |
listChatHistory(afterSequence=0,pageSize=100) |
游标、1–200 / 带 rows 的页 | 使用服务端序列;SDK 对实时/重放聊天去重 |
uploadAttachment(file,options) |
路径或 path/tempFilePath;purpose/caption/targetParticipantId / 附件结果 | 配套 uploadFile 合法域名,后端仍校验权限及文件 |
downloadAttachment(value) |
附件 ID 对象或同服务 URL / 临时路径 | 拒绝跨来源地址,避免向外域发送 RTC 令牌 |
bindWhiteboard(context,width,height) |
Canvas context、布局尺寸 | 先渲染并测量 canvas,再绑定 |
requestWhiteboardAccess(requestAccess=true) |
布尔值 / 结果 | 申请或撤销申请,最终权限以服务端为准 |
sendWhiteboard(operation,payload,objectId) |
操作、图形数据、可选 ID | 需书写权限;通常交给 client.whiteboard 编辑器使用 |
sendSignal(type,payload) |
如 hand-raise/reaction / void | 通用互动入口,服务端验证角色和 payload |
client.whiteboard 提供 point、setTool、setStyle、begin/move/end、text、image、undo/redo、rotate/resize、zoomBy/fit 和 clear。页面只传触点及布局,不自己维护一套白板协议。
| 方法 | 参数与结果 | 边界 |
|---|---|---|
performRoomAction(action,payload={}) |
业务动作 / 公开 API 结果 | snapshot、连续录制、成员/主持治理等;动作表见会议动作参考 |
moderateParticipant(id,request) |
成员 ID、动作字符串或请求对象 | kick、force-mute、allow-unmute、force-camera-off、allow-camera 等;组合流限制不能被页面绕过 |
reviewAdmission(id,admit) |
成员 ID、布尔值 | 主持审核等候成员 |
setRecording(enabled) |
布尔值 / 结果 | 服务端录制启停;返回成功不等于录像已完整产出 |
extendMeeting(minutes) |
分钟 / 结果 | 服务端校验权限与可延长范围 |
updateAccessPolicy(policy) |
策略 / 结果 | 锁定、邀请制、等候等;以公开契约字段为准 |
issueInvitation(options) |
受邀方资料 / 结果 | 不能把邀请响应当管理 Token 或无限有效的入会票据 |
downloadPlaybackPackage() |
无 / ZIP 临时路径 | 会内授权下载;离会后的档案访问使用独立业务授权,不复用失效 RTC Token |
getVideoModes() |
当前采集信息 | 不是完整硬件格式列表,精确 FPS 调整能力不能捏造 |
getAvailableVideoModes(target='*') |
成员或全体 / 可选模式数组 | 只来自终端实际报告 |
getEndpointInfo()、getPublicationStats()
|
终端信息 / 发布统计数组 | 数据缺失保持未知/null;不是所有端都能报告 WebRTC 的 RTT/丢包 |
getActiveSpeakerSupport() |
local/remote/reason | 按微信 canIUse 检查音量通知;不支持时明确提示 |
onSession(patch) 更新 joined/waiting、成员、capabilities、发布 URL 和 generation;onTopology(state) 更新 players、participants、roomPolicy、roomCapacity、录制和主持状态。onMediaSettings(settings) 是组件绑定配置,onLocalMediaState(state) 才是实际本地媒体状态。
还包括 onAdmitted、onAdmissionDenied、onLeft、onRoomClosed、onKicked、onSessionExpired、onState、onError、onCaptureUnavailable、onPlaybackState、onSignal、onChatMessage、onAttachmentUploaded、onModeration、onActiveSpeakersChanged、onVideoGeometry 和 onWhiteboardEvent。页面卸载后应抑制迟到的 setData,仍须完成 SDK leave。
SDK 不把第三方 Token 或完整签名 URL 写入错误日志。HTTP 失败可带 statusCode/body;身份失效会本地离会并触发 onSessionExpired。组件渲染问题、网络/编码失败与服务端 401/403 是不同层级,应按接入指南分别排查。