应用开发指南

开发指南

最近更新时间:2020-08-27 15:05:45

本文介绍开发者如何基于物联网开发平台小程序 SDK(下称 SDK)构建自主品牌小程序,通过 SDK 使用平台提供的能力。

前提条件

  1. 使用 SDK 需要您的运行环境包含 Node.js 以及 npm。
  2. 登录 物联网开发平台控制台 创建项目及产品,具体操作请参见 产品定义
  3. 登录 物联网开发平台控制台 获取 AppKey 和 AppSecret,具体操作请参见 获取应用 AppKey 和 AppSecret

接入 SDK

安装 SDK

  1. 在微信小程序目录下,通过 npm 安装 SDK
    npm install qcloud-iotexplorer-appdev-sdk
  2. 微信开发者工具 的项目界面中,单击界面右上角的【详情】,选择【本地设置】,勾选【使用 npm 模块】。
    使用 npm 模块
  3. 在微信开发者工具的项目界面中,选择菜单栏的【工具】>【构建 npm】,构建成功后界面提示完成构建。
    构建 npm

部署登录接口

使用物联网开发平台的 微信号注册登录 应用端 API,可以让小程序用户通过微信注册登录到物联网开发平台。由于登录相关的应用端 API 涉及物联网开发平台 AppSecret 以及小程序用户的 OpenId 等敏感信息,该应用端 API 需要由开发者的后台服务器调用。

请使用自己的后台服务器搭建一个登录接口,实现以下流程。

  1. 接收小程序传递的用户信息。
  2. 调用 微信号注册登录 应用端 API。
  3. 返回该应用端 API 的响应内容。

初始化 SDK

初始化 SDK 后,才能通过 SDK 使用物联网开发平台提供的云端能力。请参考以下示例代码,补充必要的信息与实现,以初始化 SDK。

  1. QcloudIotExplorerAppDevSdk 的构造函数参数中,将 appKey 的值修改为您实际获取的 AppKey。
  2. 补充 getAccessToken 函数的实现。
    1. 调用您的后台服务器的登录接口,传递小程序的用户信息作为参数。获取小程序用户信息请参见 wx.login 以及 wx.getUserInfo 小程序 API。
    2. 将后台服务器返回的 AppGetTokenByWeiXin 应用端 API 响应内容作为 getAccessToken 函数返回的 Promise 的值。
// app.js
const {
  QcloudIotExplorerAppDevSdk
} = require('qcloud-iotexplorer-appdev-sdk/qcloud-iotexplorer-appdev-sdk');

App({
  onLaunch() {
    this.sdk = new QcloudIotExplorerAppDevSdk({
      debug: true,
      appKey: '此处填写您的 AppKey',
      getAccessToken: this.getAccessToken
    });

    // 提前初始化
    this.sdk.init();
  },

  getAccessToken() {
    return new Promise((resolve, reject) => {
      // 1. 获取小程序用户信息
      wx.getUserInfo({
        success: resolve,
        fail: reject
      });
    }).then(userInfo => new Promise((resolve, reject) => {
      // 2. 调用您的后台服务器的登录接口
      // 仅为示例,请根据真实的接口修改以下代码
      wx.request({
        url: '/login',
        data: {
          userInfo: userInfo
        },
        header: {
          'content-type': 'application/json'
        },
        success(res) {
          // 返回数据结构示例
          // { Token: 'ACCESS_TOKEN', ExpireAt: 1234567890 }
          resolve({
            Token: res.data.Token,
            ExpireAt: res.data.ExpireAt,
          });
        },
        fail(err) {
          reject(err);
        }
      });
    }));
  }
})

// pages/index/index.js
Page({
  onLoad() {
    // 该次调用与 app.js 中的调用拿到的是同一个 Promise,不会导致执行多次
    getApp().sdk.init()
      .then(() => {
        // 初始化完成
      });
  }
})

// pages/otherpage/otherpage.js
Page({
  onLoad() {
    // 若前面已初始化完成,这里将直接 resolve
    getApp().sdk.init();
      .then(() => {
        // 初始化完成
      });
  }
})

使用 SDK

调用应用端 API

应用端 API 是物联网开发平台为了满足智能家居场景,为用户开发自有品牌的小程序或 App 而提供的云端服务,用户无需实现用户管理、设备管理、设备定时、家庭管理等基础能力,可通过调用应用端 API 快速完成移动应用端的开发。关于应用端 API 的更多信息,请参见 应用端 API 简介

SDK 对应用端 API 的调用过程进行了封装,发送请求时会自动带上公共参数 AccessTokenRequestId

以下示例代码以调用 获取用户绑定设备列表 应用端 API 为例。

sdk.requestApi(
  'AppGetFamilyDeviceList', // 请求应用端 API 的 Action 名
  { FamilyId: 'default' } // 请求应用端 API 的数据
)
  .then(data => {
    // 请求成功
      console.log(data);
  })
  .catch(err => {
    // 请求失败
       console.error(err);
  });

设备配网

SDK 目前支持 softAP 和 SmartConfig 方式进行设备配网。

softAP 配网

关于 softAP 方式配网的流程,请参见 softAP 配网开发

sdk.connectDevice({
  connectType: 'softap',
  connectOpts: {
    targetWifiInfo: { // 需要设备去连接的 Wi-Fi 的信息
      SSID: 'target-wifi-ssid',
      password: 'target-wifi-password'
    },
    softApInfo: { // 设备热点信息,若不传则需要引导用户自行去连接设备热点
      SSID: 'softap-ssid',
      password: 'softap-password'
    },
    familyId: 'default',
    onProgress: (progress) => {
      console.log('onProgress', progress.code, progress.msg);
    },
    onError: (error) => {
      console.error('onError', error.code, error.msg);
    },
    onComplete: () => {
      console.log('onComplete');
    }
  }
});

SmartConfig 配网

关于 SmartConfig 方式配网的流程,请参见 SmartConfig 配网开发。SmartConfig 方式配网需要调用 生成 Wi-Fi 设备配网 Token 的应用端 API, 获取 Wi-Fi 设备配网 Token。

// 1. 获取 Wi-Fi 设备配网 Token
sdk.requestApi('AppCreateDeviceBindToken')
  .then(data => {
    const bindDeviceToken = data.Token;
    // 2. 开始配网
    sdk.connectDevice({
      connectType: 'smartconfig',
      connectOpts: {
        targetWifiInfo: { // 需要设备去连接的 Wi-Fi 的信息
          SSID: 'target-wifi-ssid',
          BSSID: '00:11:22:aa:bb:cc',
          password: 'target-wifi-password'
        },
        bindDeviceToken: bindDeviceToken, // 用于绑定的设备 token
        familyId: 'default',
        onProgress: (progress) => {
          console.log('onProgress', progress.code, progress.msg);
        },
        onError: (error) => {
          console.error('onError', error.code, error.msg);
        },
        onComplete: () => {
          console.log('onComplete');
        }
      }
    });
  });

控制设备

通过调用 用户控制设备 应用端 API,可以对用户已绑定的设备发起控制操作。

// 指定要控制的设备的属性数据
const deviceData = {
  light_switch: 0,
};

sdk.requestApi('AppControlDeviceData', {
  ProductId: '****uctId', // 填写实际的产品 ID
  DeviceName: 'light1', // 填写实际的设备名称
  Data: JSON.stringify(deviceData) // 控制报文 JSON
})
  .then(data => {
    // 请求成功
      console.log(data);
  })
  .catch(err => {
    // 请求失败
      console.error(err);
  });

长连接通信能力

SDK 支持通过 WebSocket 为用户订阅所绑定设备的上报数据以及状态信息,SDK 初始化时默认自动连接 WebSocket 服务端。

通过设备 ID 列表订阅

sdk.subscribeDevices([
  'Product1/Device1',
  'Product1/Device2',
  'Product2/Device3'
]);

通过设备列表订阅

subscribeDevices 函数支持传入设备列表(如 获取用户绑定设备列表 应用端 API 返回的设备列表)以订阅设备信息,要求参数数组中的设备信息包含 DeviceId 字段。

sdk.requestApi('AppGetFamilyDeviceList', { FamilyId: 'default' })
  .then(data => {
    sdk.subscribeDevices(data.DeviceList);
  })
  .catch(err => {
    // 请求失败
      console.error(err);
  });

监听设备上报数据及状态信息

const { EventTypes } = require('qcloud-iotexplorer-appdev-sdk/qcloud-iotexplorer-appdev-sdk');

// 监听设备上报数据推送
sdk.on(EventTypes.WsReport, ({ deviceId, deviceData }) => {
  console.log('websocket device report', deviceId, deviceData);
});

// 监听设备在线状态变更推送
sdk.on(EventTypes.WsStatusChange, ({ deviceId, deviceStatus }) => {
  console.log('websocket device status change', deviceId, deviceStatus);
});

// 监听设备控制推送
sdk.on(EventTypes.WsControl, ({ deviceId, deviceData }) => {
  console.log('websocket device control', deviceId, deviceData);
});

获取用户基本信息

// sdk.isLogin: boolean; 用户是否登录
console.log(sdk.isLogin);

// sdk.userId: string; 用户 ID
console.log(sdk.userId);

// sdk.nickName: string; 用户昵称
console.log(sdk.nickName);

// sdk.userInfo: UserInfo; 用户详细信息
console.log(sdk.userInfo);
console.log(sdk.userInfo.Avatar);

// sdk.getDefaultFamilyId: () => Promise< string >; 获取用户默认的家庭 ID
sdk.getDefaultFamilyId().then(familyId => console.log(familyId));

UserInfo 数据结构说明

属性名 属性描述 类型
Avatar 头像 string
CountryCode 国家代码 string
Email 邮箱 string
NickName 昵称 string
PhoneNumber 电话号码 string
UserID 用户 ID string

SDK Demo

目录