Skip to content

Skill references guides sdk mini program api

AKStream documentation edited this page Nov 12, 2026 · 1 revision

微信小程序 SDK 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 是不同层级,应按接入指南分别排查。

Clone this wiki locally