基础介绍
目前插件功能主要分为两部分。
插件 SDK
(pluginSdk)
:全局单例,提供登录态管理、应用端接口调用、蓝牙等能力。设备绑定组件:目前支持 Wi-Fi 类设备配网以及蓝牙设备绑定。
使用指南
1. 申请使用
2. 引入插件
使用插件前,使用者要在
app.json
中声明需要使用的插件。如需使用 "设备绑定组件" ,请在 app.json
上额外声明位置信息权限。{"permission": {"scope.userLocation": {"desc": "您的位置信息将用于小程序位置接口的效果展示"}},"plugins": {"iotexplorer-weapp-plugin": {"version": "插件最新的版本号","provider": "wxb711dd9e4296e7f6"}}}
3. 初始化插件
使用建议
对于 OEM 小程序,如需使用"设备绑定组件",建议:
先在
app.js
上实例化 AppDevSdk,详情参见 SDK 初始化文档。在分包上引用并初始化插件时传入 AppDevSdk 实例(小程序规定每个包大小不能超过2M,插件大小目前为1M左右,所以建议不要占用主包的空间)。
需要等待
pluginSdk.init
初始化完成后,再渲染配网组件 <DeviceConfiguraiton>
。示例代码
// device-configuration-plugin.json{"usingComponents": {"device-configuration": "plugin://iotexplorer-weapp-plugin/DeviceConfiguration"}}// device-configuration-plugin.wxml<device-configuration wx:if="{{pluginInitFinish}}" props="{{deviceConfProps}}" /><view wx:else>插件未初始化</view>// device-configuration-plugin.jsconst app = getApp();Page({data: {deviceConfProps: { /* ... */ },pluginInitFinish: false,},async onLoad() {await pluginSdk.init({appDevSdk: app.sdk,});this.setData({pluginInitFinish: true,});},});
4. 适配插件
因为小程序插件无法调用
wx.onAppHide
、wx.onAppShow
接口,所以需要依赖引用方主动通知,当对应事件触发时,调用 pluginSdk 对应的方法来通知插件。示例代码
wx.onAppShow(function () {pluginSdk.onAppShow();});wx.onAppHide(function () {pluginSdk.onAppHide();});
pluginSdk API 参考
基本属性
参数 | 类型 | 说明 |
appDevSdk | AppDevSdk 实例 | |
uin | string | 获取当前已登录用户的 userId |
userInfo | object | 获取当前已登录用户的信息 |
userInfo.Avatar | string | 头像 |
userInfo.Email | string | 邮箱(用户已绑定邮箱才能获取) |
userInfo.NickName | string | 昵称 |
userInfo.PhoneNumber | string | 昵称(用户已绑定手机才能获取) |
userInfo.UserID | string | 用户 ID |
初始化
1. 接口定义
pluginSdk.init(options: Object);
2. 输入参数
参数名称 | 参数描述 | 类型 | 必填 |
appDevSdk | AppDevSdk 实例 | Object | 是 |
getLoginAccessToken | 获取登录 Token | () => Promise<{ Token: string; ExpireAt: number }> | 是 |
wifiConfProtocolList | 按需注入 WiFi 配网插件,支持的协议类型查看下文 | Array<WiFi配网插件> | 否 |
bluetoothAdapter | 蓝牙适配器 BluetoothAdapter 实例 | Object | - |
bluetoothDeviceAdapterList | 按需注入蓝牙协议 DeviceAdapte,支持的协议类型查看下文 | Array<蓝牙设备适配器> | 否 |
注意:
appDevSdk、getLoginAccessToken 两个参数为互斥关系,初始化时必须传入其中一个。
wifiConfProtocolList 参数说明
按需注入 WiFi 配网插件,目前支持的插件如下:
AirKiss
SoftAp
BleCombo
bluetoothDeviceAdapterList 参数说明
按需注入蓝牙设备适配器,目前支持的蓝牙 DeviceAdapter 如下:
注意:
使用蓝牙辅助配网时请注意,除了注入 WiFi 配网插件外,还要注入相应协议的蓝牙 DeviceAdapter。
3. 示例代码
const { pluginSdk } = requirePlugin('iotexplorer-weapp-plugin');/** WiFi设备相关*/const SimpleConfigPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-simpleconfig').default;const AirKissPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-airkiss').default;const SmartConfigPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-smartconfig').default;const SoftApPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-softap').default;const BleComboPlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-blecombo').default;const QrcodePlug = require('qcloud-iotexplorer-appdev-plugin-wificonf-qrcode').default;const {// 适用于使用BleCombo乐鑫协议的设备BleComboEspDeviceAdapter,// 适用于使用标准蓝牙辅助协议的设备BleComboLLSyncDeviceAdapter,// 适用于使用双路通讯协议的设备BleComboDualModeDeviceAdapter,} = require('qcloud-iotexplorer-appdev-plugin-wificonf-blecombo');/*** 蓝牙设备相关*/// 标准蓝牙协议const { StandardDeviceAdapter4Mp: StandardDeviceAdapter } = require('qcloud-iotexplorer-bluetooth-adapter-llsync');// 标准蓝牙广播协议const StandardAdvertDeviceAdapter = require('qcloud-iotexplorer-bluetooth-adapter-llsync-advert');Page({async onLoad() {console.log('设备适配器', [StandardDeviceAdapter,StandardAdvertDeviceAdapter,BleComboEspDeviceAdapter,BleComboLLSyncDeviceAdapter,BleComboDualModeDeviceAdapter,]);try {// Todo 这里需要补充appDevSdk初始化的代码await pluginSdk.init({// 注意:appDevSdk、getLoginAccessToken、getLoginTicket 三个为互斥关系,初始化时只需传入一个即可appDevSdk: getApp().appDevSdk, // 对于OEM小程序,建议先在app.js上初始化,然后调用plugin.init时注入// 当使用getLoginAccessToken时,需要传入appKey// appKey: 'xxx',// getLoginAccessToken: async () => {// // ...await some asynchronous 异步请求Token// return {// Token: 'xxx',// ExpireAt: 't',// };// },// getLoginTicket: async () => {// // ...await some asynchronous 异步请求Ticket// return {// Ticket: 'xxx'// };// },// 往插件里按需注入WiFi设备配网协议wifiConfProtocolList: [AirKissPlug,SimpleConfigPlug,SmartConfigPlug,BleComboPlug,SoftApPlug,QrcodePlug,],// 往插件里按需注入蓝牙DeviceAdapter// 注意:BleCombo比较特殊,除了需要注入"BleComboPlug"外,因为涉及到蓝牙,也要注入对应协议的"DeviceAdapter"bluetoothDeviceAdapterList: [StandardDeviceAdapter,StandardAdvertDeviceAdapter,BleComboEspDeviceAdapter,BleComboLLSyncDeviceAdapter,BleComboDualModeDeviceAdapter,],});} catch (err) {/* 调用方自行处理出错后的逻辑 */console.error('插件初始化失败', err);}// 因为小程序插件无法使用onAppShow、onAppHide 所以需要依赖调用方来实现,当对应事件触发时,调用pluginSdk对应的方法// 请务必实现wx.onAppShow(this.onAppShow);wx.onAppHide(this.onAppHide);},onUnload() {wx.offAppShow(this.onAppShow);wx.offAppHide(this.onAppHide);},onAppShow() {pluginSdk.onAppShow();},onAppHide() {pluginSdk.onAppHide();}});
设备绑定组件
目前插件使用 Taro 开发,基于 Taro 的限制,需要将参数都放入
props 属性上
,如下示例代码:示例代码
<device-configurationprops="{{deviceConfProps}}"/>
Page({data: {deviceConfProps: {productId: 'xxx',familyId: 'xxx',wifiConfProps: {extraInfo: {}},onSuccess() {},onError() {},onComplete() {},navigateBack: () => wx.navigateBack(),}},})
组件参数
参数名称 | 参数描述 | 类型 | 必填 |
productId | 产品 ID | string | 是 |
navigateBack | 因为小程序插件无法调用 wx.navigateBack 接口,需要依赖引用方主动通知 | function | 是 |
familyId | 如不传入,组件会先让用户选择家庭 | string | 否 |
onSuccess | 配网成功时回调,回调参数 { deviceId: string; familyId: string } | function | 否 |
onError | 配网失败时回调 | function | 否 |
onComplete | 配网完成时回调;仅在配网成功时,用户单击 完成 按钮时才触发回调参数 { deviceId: string; familyId: string } | function | 否 |