分类： 音视频通话+摄像头（for 硬件）

1. 后台返回错误码

2. 插件内部错误码

以插件最新版本支持为准

3. Error 类

需要插件 2.4.0 版本开始支持

3.1 VoipError

插件抛出异常的基类，继承自 Error，并增加下列属性：

3.2 VoipCgiError

后台请求失败错误，继承自 VoipError，仅作类型区分，没有新增属性。

3.3 VoipJoinError

加入房间失败相关错误，继承自 VoipError，并增加下列属性：

这两个属性开发者一般不需要关注，仅微信侧排查问题需要

3.4 VoipPluginError

插件内其他类型的错误，继承自 VoipError，仅作类型区分，没有新增属性。

对于部分存量的支付刷脸设备，我们额外支持通过微信支付人脸识别的用户身份来发起通话。

支付刷脸设备的通话存在以下限制：

• 只支持微信支付刷脸设备使用，具体的开通方式请参考微信支付的相关文档；
• 只支持安卓设备，WMPF <= 2.0 版本；
• 只支持设备发起呼叫，不支持手机微信呼叫设备。

1. 发起通话

支付刷脸设备也是通过 initByCaller 接口发起通话，但是在参数上有一些区别。支付刷脸设备请使用下列 businessType：

• 使用前，需要在微信小程序中提前通过 wx.authorize 让 openId 对应的用户授权 scope.voip，否则会返回 errCode: 8，具体流程请参见第 2 节；
• listener 必须为 caller 联系人。否则会返回 errCode: 9。

2. 联系人管理

2.1 联系人绑定

校园场景下，开发者需要接入插件「联系人绑定关系」功能，只有在家长完成关系绑定操作后，孩子才可以给家长拨打音视频电话。

联系人绑定是 userId（孩子）和 openId（家长）的映射关系，开发者还能够通过相关接口实现联系人管理功能。

管理员绑定

第一个联系人为管理员，需要 wx.authorize 授权 voip.scope，再调用插件接口 wmpfVoip.bindVoipAdminContact 完成绑定。

// 绑定成为管理员
try {
  await wx.authorize({
    scope: 'scope.voip',
  })
  const res = await wmpfVoip.bindVoipAdminContact({
    userId: 'xxxxxx', // 传入微信支付刷脸返回的 user_id
  })
  console.log(`bindVoipAdminContact`, res)
} catch (error) {
  console.error('authorize scope voip', error)
  wx.showToast({
    title: '请前往设置页授权通话提醒',
    icon: 'none',
  })
}

其他联系人绑定

其他联系人由管理员分享页面进行绑定。即管理员在微信小程序中点击「分享」按钮, 并通过 wmpfVoip.getBindContactPath 获取插件分享页面链接，并在页面的 onShareAppMessage 中设置。

绑定完成后，会跳转到 setVoipEndPagePath 设置的页面。

// 获取插件联系人绑定关系页面路径，用户会在该页面进行关系绑定操作。
// 分享绑定页面：在学生管理员进入页面时，提前获取分享链接
wmpfVoip
  .getBindContactPath({
    userId: 'xxxx', // 学生 id
    userName: 'xxxx', // 学生名字
    userAvatar: 'xxxx', // 学生头像
  })
  .then(path => {
    // 在 onShareAppMessage 中使用 path
    // 可在 path 后拼上参数, 如'&xxx=yyy', <a href="https://weixin-xiaochengxu-kaifa.yuannext.com">微信小程序</a>中通过 getPluginEnterOptions 获取
  })

// Page 中
Page({
  onShareAppMessage() {
    return {
      title: `邀请你成为「${userName}」的联系人`,
      path: 'xxxx', // getBindContactPath 获取的 path
    }
  },
})

// app.js
App({
  onLoad() {
    // 设置联系人绑定关系页面操作完成后要跳转的页面路径。
    wmpfVoip.setVoipEndPagePath({
      key: 'BindContact',
      url: 'xxxxxx',
      options: 'param1=xxx&param2=xxx',
    })
  },
})

注意

• userName 和 userId（微信支付刷脸返回的 user_id）应与拨打方（学生）信息录入时保持一致；
• 拨打方应能获取接听方联系人的 openId、名字, 用于显示在联系人列表页面；
• 在完成绑定过程中，会触发相应事件。可通过 onVoipEvent 进行监听。具体参考 bindContact 的 type。

2.2 查询联系人列表

插件接口

wmpfVoip.getVoipBindContactList({ userId: '学生userId' }).then(list => {
  /**
      [{
        user_id: 'xxx',
        is_ad: 0, // 0 普通联系人，1 管理员
        openid_list: [], // 管理员可以获取孩子（user_id）下绑定的所有联系人（openid）列表，包括自己。
      }]
    */
})

后台接口

请求地址

POST https://api.weixin.qq.com/wxa/business/getvoipcontactlist?access_token=ACCESS_TOKEN

请求参数

返回值

Object

返回的 JSON 数据包

ContactInfo

errCode 合法值

2.3 删除联系人

只有管理员才能删除学生（user_id）的联系人（openid），管理员不能删除自己。

wmpfVoip.deleteVoipBindContact({
  userId: 'xxx',
  openidList: ['openId1', 'openId2'],
})

2.4 转移管理员

只有管理员才能调用转移接口。

wmpfVoip.transerAdmin({
  userId: 'xxx',
  newAdminOpenid: '新管理员的openid',
})

2.5 监听事件

在绑定联系人的过程中，onVoipEvent 会收到 bindContact 事件，获取分享绑定联系人状态：

data 参数

type 取值

本插件主要用于提供「微信小程序摄像头」的部分基础能力和统一的界面。

插件接入可参考：微信小程序示例代码

设备侧 SDK 的接入与微信小程序 Voip 的纯云接入完全一致，请参考相关文档。

1. 微信小程序引入插件

关于微信小程序插件详细说明请参考微信小程序使用插件文档

在「微信小程序管理后台」添加插件后，使用者还需要要在微信小程序的 app.json 中声明本插件。可以在主包引入，也可以在分包引入。

// 主包引入
{
  "plugins": {
    "wmpf-voip": {
      "version": "latest", // latest 表示自动使用最新版本。也可使用具体版本，如 2.3.8
      "provider": "wxf830863afde621eb"
    }
  }
}

// 分包引入
{
  "subpackages": [
    {
      "root": "xxxx",
      "pages": [],
      "plugins": {
        "wmpf-voip": {
          "version": "latest", // latest 表示自动使用最新版本。也可使用具体版本，如 2.3.8
          "provider": "wxf830863afde621eb"
        }
      }
    }
  ]
}

完成声明后，可以在微信小程序中来确认是否引入成功

const wmpfVoip = requirePlugin('wmpf-voip').default
console.log(wmpfVoip) // 有结果即表示引入插件成功

2. 引入摄像头组件

插件引入成功后，需引入摄像头组件。

页面或者组件的 json 文件中声明：

"usingComponents": {
    "camera-device": "plugin-private://wxf830863afde621eb/publicComponents/camera-device/camera-device"
  },

wxml 中使用组件：传入sn、model-id，device-name

// page.wxml
<camera-device sn="{{sn}}" device-name="{{deviceName}}" model-id="{{modelId}}" class="camera-deivce" bind:changeQuality="changeQuality"></camera-device>

wxss 中自定义 camera-deivce.

// page.wxss
.camera-deivce {
  width: 100vw;
  height: 300px;
}

预期：

3. 组件属性

事件：切换清晰度 changeQuality

示例：

<camera-device 
    sn="{{sn}}" 
    device-name="{{deviceName}}" 
    model-id="{{modelId}}" 
    class="camera-deivce" 
    bind:changeQuality="changeQuality"
>
</camera-device>

Page({
    changeQuality(res) {
        console.log(res)
    }
})

4. 更新日志

请参考《微信小程序音视频通话插件更新日志》

在安卓设备端，开发者需要运行一个安卓应用（文档中也称为微信小程序 Launcher），用来进行设备注册、运行微信小程序进行 VOIP 通话等操作。

1. 接入 WMPF 并运行微信小程序

在安卓平台上，微信小程序视频通话能力是在微信小程序中实现的。需要由设备端运行的安卓应用拉起开发者开发的微信小程序来发起和接听音视频通话。

在完成开发前准备「3.1 接入微信硬件平台」，并进行设备注册后，可以获得 WMPF 运行所需的 productId 、keyVersion、deviceId、signature 等硬件信息。

请参考WMPF 文档中的说明，完成下列操作：

• 部署 WMPF Service APK；
• 参考 WMPF 提供的示例代码在应用中集成 WMPF Client；
• 调用 activateDevice 完成设备激活；

2. 设备注册

在发起通话前，需要先完成设备注册。请参考设备认证文档完成 RPMBD 服务的部署、SDK 接入和设备注册的步骤。

完成设备注册后，可以在发起通话前通过 SDK 的 getDeviceToken 接口获取设备票据，传递到微信小程序内做为调用 VOIP 插件发起通话的 voipToken 使用。

注意：

• 此处使用的 SN，必须经过 WMPF 的 addDevice 接口作为 deviceId 注册，并与 WMPF 设备激活 使用的 deviceId 一致。 否则后续无法正常发起通话。
• 使用设备认证 SDK 时需要保证 rpmbd 服务已经成功运行。

3. 运行微信小程序

完成 WMPF 安装和设备激活后，便可以调用 launchMiniProgram 启动指定的微信小程序。

3.1 安卓应用与微信小程序通信

微信小程序启动后，应用可以通过下列方式和微信小程序内进行通信

• 简单的「安卓应用 -> 微信小程序」单向单次传递参数的场景，可以直接在启动微信小程序的 path 中拼接 query。
• 如果安卓应用要接收微信小程序发来的事件、需要双向通信或者数据量大时可以通过 WMPF 提供的通信通道(Invoke Channel)

3.2 运行开发版/体验版微信小程序

在使用开发版/体验版微信小程序进行调试时，请参照下列步骤。

注意：必须扫码登录后才能正常下载开发版/体验版。开发版/体验版更新后，建议重启 WMPF 以更新到最新。

1. 开发者在开发者工具点击「预览」，将开发版微信小程序代码包上传到后台。也可提交成体验版；
2. 在 WMPF 上调用 login 弹出扫码登录界面，由在开发者工具上登录的同个微信号扫码登录；
3. WMPF launchMiniProgram 时指定 appType 为开发版或体验版；
4. 开发版有有效期，过期后需要重新进行上述步骤