更新记录

1.0.0（2026-09-02）

支持平台：Android 7.0（API 24）及以上，不支持 iOS、H5 和各类小程序端。 正式提交前请在自己的 DCloud 开发者账号中确认该标识可用。若市场提示已占用，应使用发布者前缀，并同步修改 ZIP 一级目录、package.json.id、Android module 注册名和所有 requireNativePlugin 调用。如需帮助***：1057588825 微信：tyh998998

平台兼容性

uni-app(5.25)

其他

微信 WMPF VoIP UTS 插件

插件说明

本插件通过 UTS 原生混编封装腾讯微信硬件平台 WMPF Android SDK，支持：

• WMPF 初始化和运行状态查询；
• 小程序设备注册状态查询及不可逆注册；
• 通话小程序预加载、语音/视频通话启动；
• 正常挂断、强制关闭、当前通话查询；
• 通话状态、通话记录及小程序 Channel 事件回传。

插件 ID：wechat-voip-uts

版本：1.0.0

平台：Android 7.0（API 24）及以上；支持 uni-app 的 Vue 2/Vue 3 和 uni-app x 的 Android App，不支持 iOS、Web、nvue 和各类小程序端。

最低 HBuilderX：4.27。插件包含 Java 原生混编代码和本地 AAR，调试时必须重新制作自定义基座或云打包，普通热刷新不会集成原生依赖。

上架前必须确认

插件内的 wmpf-cli-2.2.0.aar 属于腾讯 WMPF SDK。发布者必须确认自己具有在 DCloud 插件市场中再分发该 SDK 的授权，并确认版本、来源、许可证及校验和。若没有再分发授权，请不要公开上传包含该 AAR 的 ZIP，应改为在文档中指导购买者自行取得 SDK。

正式发布前还应确认 wechat-voip-uts 在自己的 DCloud 账号下可用。若 ID 已占用，请改成带发布者前缀的唯一 ID，并同步修改插件目录名和示例工程中的导入路径。

安装

将插件目录放到项目：

uni_modules/wechat-voip-uts

然后在 HBuilderX 中重新制作 Android 自定义基座，或直接提交云打包。

页面中从插件根目录导入，不要直接导入 utssdk 内部文件：

import {
  initialize,
  getStatus,
  getDeviceRegistrationState,
  registerDevice,
  preloadMiniProgram,
  startCall,
  hangup,
  forceClose,
  getActiveCall,
  onEvent,
  offEvent
} from '@/uni_modules/wechat-voip-uts'

数据与密钥安全

插件不包含业务服务器地址、接口路径、产品密钥、签名私钥、真实设备标识和用户信息。

以下数据必须由已登录的宿主应用从自己的业务服务端动态取得：

• signature、snTicket；
• hostAppId、productId、keyVersion；
• 设备 ID/SN、小程序 AppID、modelId 和页面路径；
• voipOpenId、通话对象及其他个人信息。

不要在客户端保存 hostAppSecret 或实现产品密钥签名算法，也不要在日志中输出完整票据、设备标识或个人信息。

事件监听

onEvent 是持续回调，同一时刻只保留最后一次注册的监听器。不再使用时必须调用 offEvent()，避免页面销毁后仍持有回调。

onEvent(event => {
  console.log(event.type, event.data)
})

// 页面卸载
offEvent()

事件类型包括：runtimeState、runtimeError、deviceActivation、deviceRegistration、callState、callRecord、voipEvent、channelEventRegistered、channelEventUnregistered。

初始化

initialize({
  hostAppId: runtimeConfig.hostAppId,
  productId: Number(runtimeConfig.productId),
  keyVersion: Number(runtimeConfig.keyVersion),
  deviceId: runtimeConfig.deviceId,
  signature: runtimeConfig.signature,
  features: ['voip-device']
}, result => {
  console.log(result.code, result.message)
})

必填字段不能写死。同一进程内若更换启动参数会返回 RESTART_REQUIRED，需要完全结束并重启应用进程。

查询状态

getStatus(result => console.log(result))
getDeviceRegistrationState(result => console.log(result))
getActiveCall(result => console.log(result))

注册小程序设备

设备注册不可逆，必须先由用户核对参数并明确确认：

registerDevice({
  miniProgramAppId: registration.miniProgramAppId,
  modelId: registration.modelId,
  sn: registration.sn,
  snTicket: registration.snTicket,
  irreversibleConfirmed: true
}, result => {
  console.log(result.code, result.message)
})

预加载和发起通话

preloadMiniProgram({
  appId: callConfig.miniProgramAppId
}, result => console.log(result))

startCall({
  requestId: callConfig.requestId,
  requireRegistered: true,
  miniProgram: {
    appId: callConfig.miniProgramAppId,
    path: callConfig.miniProgramPath,
    appType: callConfig.appType,
    landscapeMode: callConfig.landscapeMode
  },
  dial: {
    sn: callConfig.deviceSn,
    callType: callConfig.callType,
    durationLimitSeconds: callConfig.durationLimitSeconds,
    callName: callConfig.callName,
    voipOpenId: callConfig.voipOpenId,
    studentUuid: callConfig.studentUuid,
    parentUuid: callConfig.parentUuid,
    businessData: callConfig.businessData
  },
  camera: callConfig.camera
}, result => {
  console.log(result.code, result.message)
})

必填项：miniProgram.appId、miniProgram.path、dial.sn、dial.voipOpenId。dial.callType 只能为 voice 或 video。

挂断与关闭

hangup(result => console.log(result))

forceClose({
  appId: currentMiniProgramAppId
}, result => console.log(result))

正常挂断依赖通话小程序注册 handleHungUp 事件。没有注册时会返回 HANGUP_EVENT_NOT_REGISTERED；forceClose 用于强制关闭小程序。

小程序 Channel 约定

权限说明

• INTERNET、ACCESS_NETWORK_STATE：WMPF 服务及通话小程序通信；
• CAMERA：视频通话；
• RECORD_AUDIO、MODIFY_AUDIO_SETTINGS：语音和视频通话；
• WAKE_LOCK：通话期间保持必要运行状态。

敏感权限应在用户主动使用对应功能时，由宿主应用按平台要求说明用途并请求授权。

常见错误

验收范围

源码编译和插件 ZIP 校验不能代替真实环境验收。发布前至少使用真实 WMPF 产品、已安装的 com.tencent.wmpf Service APK 和 Android 真机验证：初始化、激活、注册确认、语音、视频、挂断、强制关闭、通话记录及事件回传。