VoIP 插件接入

背景介绍

在微信强提醒方案中，微信端授权弹窗、通话提醒、通话界面为微信提供的统一界面。小程序开发者参考VoIP 插件开发文档 (opens new window)接入微信 VoIP 通话插件后，当设备呼叫手机端微信用户时，手机端用户不需要打开微信，即可收到音视频通话弹窗提醒，通过提醒直接进入小程序进行通话。

VoIP 插件引入

官方插件集成 Demo

微信小程序开发文档 (opens new window)

版本要求

微信 8.0.54 及以上版本

接入流程

1. 插件引入

「小程序管理后台 (opens new window)」——「设置」——「第三方设置」——「插件管理」，点击「添加插件」

2. 代码引入

app.json主包或者分包内引入

{
  "plugins": {·
    "wmpf-voip": {
      "version": "latest",
      "provider": "wxf830863afde621eb"
    }
  },
  ...
}

3. 初始化插件

在app.js初始化加载插件与插件设置

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

// 后面即可设置 VoIP 插件配置

VoIP 插件常见可选配置

设置呼叫后结束跳转页面

wmpfVoip.setVoipEndPagePath({
  url: '/pages/contactList/contactList',
  key: 'Call',
})

设置画面比例以及裁切模式

1. 常见参数说明

参数名	类型	说明
callerUI	object	主叫UI配置，详见下表
listenerUI	object	被叫UI配置，详见下表

callerUI / listenerUI 参数说明

参数名	类型	说明
aspectRatio	float	视频画面画面纵横比
objectFit	string	视频画面与容器比例不一致时的表现形式。支持 fill/contain

2. 官方代码参考

wmpfVoip.setUIConfig({
  callerUI: {
    aspectRatio: wx.getWindowInfo().screenHeight / wx.getWindowInfo().screenWidth, 
    objectFit: 'contain'
  },
  listenerUI: {
    aspectRatio: wx.getWindowInfo().screenHeight / wx.getWindowInfo().screenWidth,
    objectFit: 'contain'
  },
})

其他参数参考:微信小程序开发文档 (opens new window)

回调打印

wmpfVoip.onVoipEvent((event) => {
  console.log(`onVoipEvent`, event)
    })

授权以及发起呼叫

设备授权

设备呼叫微信用户时，微信用户需要对设备进行授权才可实现通话，用户授权设备微信官方文档：微信小程序开发文档 (opens new window)

参数、必填参数、其他参数见requestDeviceVoIP (opens new window)按需填写

参数名	类型	说明
sn	string	设备唯一序列号。设备唯一序列号。由厂商分配，长度不能超过128字节。字符只接受数字，大小写字母，下划线（_）和连字符（-）。
snTicket	string	设备票据，5分钟内有效 需要用户自己开发服务向微信后台获取
modelId	string	设备型号 id。通过微信公众平台注册设备获得。（仅单台设备时）
deviceName	string	设备名称，将显示在授权弹窗内（长度不超过13）。授权框中「设备名字」= 「deviceName」 + 「modelId 对应设备型号」

wx.requestDeviceVoIP({
      sn,
      snTicket,
      modelId,
      deviceName: sn,
      async success(res) {
        console.log(`requestDeviceVoIP`, res)
        await authorize({ sn, name })
        wx.showToast({
          title: '授权成功',
          icon: 'none',
        })
      },
      fail(err) {
        console.error(`requestDeviceVoIP fail`, err)
        wx.showToast({
          title: '授权失败, 请前往设置页开启',
          icon: 'none',
        })
      },
    })

设备授权查询

通过getDeviceVoIPList (opens new window)返回近期授权记录

授权记录在小程序被删除后清空

返回一个 Array<Object> 数组，包含以下字段：

参数名	类型	说明
sn	string	设备唯一序列号。（仅单台设备时）
model_id	string	设备型号 id。通过微信公众平台注册设备获得。（仅单台设备时）
group_id	string	设备组的唯一标识 id（仅设备组时）
status	number	设备（组）授权状态。0：未授权；1：已授权

微信小程序发起呼叫

开发者通过业务后台通知设备端，并在小程序端调用callDevice (opens new window)接口发起呼叫。以下参数为菊风与微信官方文档差异参数，其他参数按照微信官方文档按需填写,并跳转到微信插件页面拉起插件页面

接口：callDevice

参数名	类型	是否必填	说明
payload	string	是	JSON字符串,按照下表说明填写
isCloud	boolean	是	设置为true,将payload信息回调携带到菊风后台

payload 参数说明

参数名	类型	是否必填	说明
fromMiniApp	boolean	是	必须填true
juphoon	object	是	菊风相关配置，详见下表
wechat	object	是	微信相关配置，详见下表

juphoon 参数说明

参数名	类型	是否必填	说明
appKey	string	是	菊风appkey，点击查看如何获取 appkey
callId	string	是	唯一通话ID，需要和Rtos端Sdk填入的值相同

wechat 参数说明

参数名	类型	是否必填	说明
appId	string	是	微信小程序 AppId
deviceId	string	是	设备 SN
modelId	string	是	设备 Model ID
landscape	boolean	否	SDK 接收小程序推流是否为 4:3 的流。 true: SDK 收到流的宽高比 4:3 --- 320x240 480x352 640x480 1280x720 1920x1080 false: SDK 收到流的宽高比 3:4 --- 240x320 352x480 480x640 720x1080 1080x1920
subscribeVideoLength	int	否	设备 SDK 期望收到的流分辨率固定长边值 开发者可以用此配置来订阅一个分辨率的长边值。此功能主要是针对那些不希望收到可变分辨率视频流的设备，如果不使用此功能，SDK 收到的视频流在不同的网络环境下会有不同的分辨率。此功能需要同时向微信提交 appid，待开通订阅机制后才生效。 目前这个配置仅支持如下两个值： 320: video_landscape = true 时收到的是 320x240，video_landscape = fale 时收到的是 240x320 640: 不支持 video_landscape = true 模式，video_landscape = fale 时收到的是 480x640
subscribeVideoRotation	int	否	设备 SDK 期望收到的流方向 开发者可以用此配置来订阅自己收到的流的方向 SDK 默认收到的是逆时针旋转了 90 度的视频流，如果开发者的硬件没有旋转渲染能力，可以使用这个订阅。订阅 0 度流后，对端的微信客户端会对流进行前处理再发出。 此功能 Beta 中，需要微信客户端与插件均支持方可生效. 目前这个配置仅支持如下两个值： 1: 0 度流, 需要配合小程序端的 0 度流参数 即callDevice的encodeVideoRotation，两者一致后才能收到 0 度流。 其他：旋转流，默认也是旋转流。
subscribeVideoRatio	int	否	设备 SDK 期望收到的流比例 开发者可以用此配置来订阅自己收到的流的比例 此功能 Beta 中，需要微信客户端与插件均支持方可生效. 定义如下： 75: 宽/高 * 100 = 75, 例如 240x320 133: 宽/高 * 100 = 133, 例如 320x240 50: 宽/高 * 100 = 50, 例如 160x320 200: 宽/高 * 100 = 200, 例如 320x160 ...

interface CallDeviceParams {
  */** 房间类型 */*
  roomType: string;

  */** modelId */*
  modelId: string;

  */** 设备序列号 */*
  sn: string;

  */** PayLoad */*
  payload: string; *// JSON字符串，JSON字符串的PayloadData*
                                                          
  */** 是否为云端 */*
  isCloud: true;
}

interface PayloadData {
  fromMiniApp: boolean;
  juphoon: {
    */** Juphoon Appkey */*
    appKey: string;
    */** 通话ID */*
    callId: string;
  };

  */** 微信相关配置 */*
  wechat: {
    */** 微信小程序AppId */*
    appId: string;
    */** 微信ModelId */*
    modelId: string;
    */** 设备ID */*
    deviceId: string;
    */** 横屏设置 */*
    landscape: string;
    */** 订阅视频长度 */*
    subscribeVideoLength: string;
    */** 订阅视频旋转 */*
    subscribeVideoRotation: string;
    */** 订阅视频比例 */*
    subscribeVideoRatio: string;
  };
}

{
  "fromMiniApp": true,
  "juphoon": {
    "appKey": "xxxxx",
    "callId": "xxxxx"
  },
  "wechat": {
    "appId": "xxxxx",
    "deviceId": "xxxxxx",
    "modelId": "xxxx",
    "landscape": false,
    "subscribeVideoLength": 320,
    "subscribeVideoRotation": 1,
    "subscribeVideoRatio": 75
  }
}

const resp = await wmpfVoip.callDevice({
        roomType: roomtype,
        modelId: config.modelId,
        sn,
        payload: JSON.stringify({
          fromMiniApp: true,
          juphoon: {
            appKey: 'appKey',
            callId: 'yourCallId',
          },
          wechat: {
            appId: 'wechat_appId',
            modelId: 'modelId',
            deviceId: '',
            landscape: '',
            subscribeVideoLength: 320,
            subscribeVideoRotation: 1,
            subscribeVideoRatio: 75
          }
        }),
        encodeVideoRotation: 1,
        encodeVideoLength: 320,
        encodeVideoRatio: 75,
        isCloud: true
      })
      // 拉起呼叫页面
      wx.redirectTo({
        url: CallPagePlugin
      })