Skip to content

zh CN sdk mini program

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

微信小程序:从只看入会到真实音视频

微信小程序使用独立 CommonJS SDK AkRtcMiniClient,配套 Demo 在 Clients/AKStream.Rtc.WeChatMiniProgram。它接入 AKStream.Next 的会议、成员、权限、聊天和录制体系,但媒体组件使用 live-pusher 的 RTMP 上行及 live-player 的 HTTP-FLV 下行,不是浏览器 WebRTC/WHIP/WHEP。

新增组件错误回调、播放重试及本次生命周期修复须使用更新后的小程序 SDK/Demo,不能只替换页面或把新方法用于旧 SDK 目录。 SDK 已实现票据入会、等候室、组合流发布、独立播放票据、令牌续期、信令重连、成员与媒体同步、主持限制、聊天附件和白板。自动测试使用模拟微信运行时;真实推拉流、编码互通、组件变换、权限和前后台行为仍需用有资质 AppID 在微信真机验收。不要把导入工程或 Node 测试通过写成“小程序全功能已验收”。

先确认是否适合你的业务

能力 当前方式与边界
摄像头与麦克风 同一个 MiniProgramCombined 发布;页面可关闭其中一个输入,但服务端按组合发布授权
远端观看 每个活动 Publication 对应一个 HTTP-FLV 播放器;不另设 Demo 路数常量,稳定路数按设备实测
Web/原生互通 小程序上行标记 H264/AAC;下行还取决于实际编码和媒体节点输出。Web 的 Opus 音轨或任意视频编码不能仅靠换 URL 就保证可播放,必要的兼容编码路径须先验证
媒体 UDP/TCP 选择 只接受 mediaTransport: 'auto'。传 udp/tcp 返回 UNSUPPORTED_MEDIA_TRANSPORT,TURN 配置不能改写微信原生组件的底层协议
桌面共享、独立音轨发布、任意麦克风枚举 当前适配不提供;可以观看其他端已发布且编码兼容的屏幕视频
音频输出与音量 可选 speaker/ear,无法读回实际物理路由;数字音量只降级为静音/恢复,细调使用系统音量
镜像、旋转与最大化 SDK 输出视图设置,页面绑定;最大化是页面布局,不是系统全屏或系统画中画,原生组件变换需真机复核
主持管理与录制 按服务端 capability 调用会议动作;录制在服务端完成,不依赖小程序本地录音录像

mode="RTC" 是微信推流组件的工作模式名称,不表示存在 RTCPeerConnection,也不能据此宣称本端支持 TURN/TCP。传输指南说明与 Web/原生端的区别。

准备 AppID、组件与域名

  1. 在微信开发者工具导入 Demo 目录,设置自己的 AppID。工程中的 touristappid 只供查看工程结构,不能证明拥有音视频组件权限。当前 Demo 选择的基础库为 3.7.12,真机还要核对微信版本与组件能力。
  2. 按微信公众平台当前规则取得可用类目并开通 live-pusher/live-player。不要照抄固定类目名称或把 AKStream.Next 的产品授权当作微信组件权限。官方推流组件、官方播放组件列出当前申请范围。
  3. AKStream.Next API 使用真机信任的 HTTPS;将 API、WSS、上传、下载实际使用的域名分别纳入对应合法域名设置。媒体推拉流地址遵守微信组件本身的协议和域名要求;配置 request 域名不等于所有媒体地址都获准。域名规则见微信网络说明。
  4. 由管理员在产品配置界面确认对外 RTMP、HTTPS-FLV 入口、证书、端口映射和发布/播放鉴权回调已生效。第三方通过公开 API 接入,无须修改服务端数据库或获取服务端源码。
  5. 完成隐私保护指引,并按微信要求取得隐私、摄像头和麦克风授权。app.json.permission 的说明文字不能代替用户授权。可结合微信隐私授权机制安排自己的同意界面;SDK 不会替用户同意协议。

AKStream.Next 这条媒体路径不要求在客户端嵌入 TRTC SDK、SDKAppID 或媒体管理密钥。微信组件资质和实际运行条件仍须独立满足。

在业务中取得一次性票据

业务后端验证用户身份后调用公开的房间票据接口,把 baseUrl、roomId、accessTicket 和可选会议口令交给获准设备。平台管理 API Token 仅在业务后端保存,不写入 app.js、小程序存储或分享 URL。票据用过后不能重复入会,重入须向业务后端重新申请。

Demo 的“刷新房间 / 自动获取测试票据 / 发起会议”只在 Development 测试环境使用。正式服务不开放 Demo 自动签票时,展开手工输入或接上自己的业务签票接口;不要把这一失败当作 SDK 不能入会。新建会议得到的主持票据会受 Demo 保护,重新获取普通票据前需要明确确认。

最小只看页面

复制完整 miniprogram/sdk 目录,保留依赖文件。下面代码放在业务小程序页面;meeting 是你的业务后端返回的数据,setData 收到的状态只留在当前页面,不写入日志。完整属性和事件见小程序 SDK API。

const { AkRtcMiniClient } = require('../../sdk')

Page({
  data: { waiting: false, players: [], notice: '' },
  onLoad() {
    this.disposed = false
    const update = patch => { if (!this.disposed) this.setData(patch) }
    this.rtc = new AkRtcMiniClient({
      onSession: patch => update(patch),
      onTopology: state => update({ players: state.players }),
      onState: message => update({ notice: message }),
      onError: error => update({ notice: error.message }),
      onLeft: () => update({ players: [], waiting: false })
    })
  },
  async joinWithBusinessTicket(meeting) {
    await this.rtc.join({ baseUrl: meeting.baseUrl, roomId: meeting.roomId,
      accessTicket: meeting.accessTicket, passcode: meeting.passcode,
      audio: false, video: false })
  },
  onHide() { void this.rtc.setForeground(false) },
  onShow() { if (this.rtc) void this.rtc.setForeground(true) },
  onUnload() { this.disposed = true; void this.rtc.leave() }
})
<text wx:if="{{waiting}}">等待主持人准入</text>
<live-player wx:for="{{players}}" wx:key="publicationId"
  src="{{item.url}}" mode="live" autoplay object-fit="contain" />

这是最小示意,正式页面还要转交组件的 statechange/error/netstatus,处理音频输出、后台、页面卸载后迟到回调,参考配套 Demo。只看模式不会主动申请本机相机和麦克风;等候中也不会提前读取媒体或成员数据。

添加发布及组件事件

在用户明确开启输入后调用 setMicrophoneEnabled(true)、setCameraEnabled(true)。SDK 按权限创建组合发布并回调 pusherUrl/publicationId/sessionGeneration;页面绑定 url 与 autopush,在组件渲染后通过 wx.createLivePusherContext 和 bindPusherContext 交给 SDK。

必须把当前组件的 sessionGeneration 和 publicationId 绑定到 data-* 并原样传给 SDK:

微信事件 SDK 调用
推流 statechange onPusherState(code, generation, publicationId)
推流 error onPusherError(detail, generation, publicationId)
推流 netstatus onPusherNetStatus(detail, generation, publicationId)
播放 statechange/error onPlayerState(publicationId, code, generation) / onPlayerError(publicationId, detail, generation)
播放 netstatus onPlayerNetStatus(publicationId, detail, generation)
音量通知 onAudioVolume(publicationId, volume, generation, local)

本机预览和发出推流请求都不代表对方已收到媒体。SDK 在真实推流开始回调后才报告实际开麦/开摄像头;还需第二端确认收到音视频。播放器多次重连后终止时,Demo 显示错误和“重新连接播放”,由 retryPlayback() 获取新播放 URL 并刷新组件;不会无限自动创建会话。

主持人禁用组合发布中的任一输入时,整个小程序组合流会停止。解除限制后由用户自行重新开启,不会自动启动摄像头或绕过服务端限制。

聊天、白板与录制

SDK 封装 sendChatMessage、历史消息、附件上传下载及白板模型。文件上传与下载还需要配置对应合法域名;附件临时路径由微信管理,不能当作永久业务文件地址。白板页面只提供 Canvas context、尺寸和触点,通过 SDK 处理状态与书写权限。

主持功能统一使用 performRoomAction(action, payload),也有常用便捷方法。结束全体会议只能由当前主持人执行;普通离会用 leave()。录制、回放包、白板书写均受服务端权限约束,SDK 不会因为页面显示按钮就赋予权限。参见会议动作与录制和档案。

排障与上线验收

现象 排查顺序
开发者工具能打开但真机没有媒体 实际 AppID、组件开通、隐私授权、真机证书和合法域名
自动签票失败 是否为 Development;正式业务改用自己的后端签票
401、票据已消费或会话过期 不重复使用 accessTicket;业务后端重新签发,检查设备时间
等候室没有画面 等候状态本就不允许读媒体,先由主持人准入
有本机预览、对端无画面 真实推流 statechange、组件错误、RTMP 对外地址和服务端发布状态
远端黑屏或有图无声 实际视频/音频编码、HTTPS-FLV 输出、组件 error/statechange、系统静音与路由
-2301 或持续断流 原生播放器重连已耗尽;检查网络后用 retryPlayback(),不要反复消耗入会票据
拒绝设备权限后不能开启 引导用户在小程序设置中授权;不要循环弹窗或将按钮直接改成“已开启”
退后台或断网后状态不一致 是否转交 onHide/onShow、旧组件 generation、公用 SDK 版本及服务端会话状态

至少验收:只看与发言者、两台微信真机、Web/Android/iOS 互通的实际编码、等候准入/拒绝、网络恢复、前后台、主持禁用、长会续签、附件、白板、录制与离会清理。公开 Demo 源码和模拟测试覆盖的是接入逻辑,不能替代上述真实媒体验证。

Clone this wiki locally