设备消息接入指引

一、申请类目

1.1 申请工具-设备管理类目

登录小程序管理后台mp.weixin.qq.com，左侧最下方“设备”-基本设置-服务类目，添加“工具-设备管理”类目（该类目无需资质。如已有该类目可忽略此流程）

二、设备接入

2.1 开通设备管理功能

进入小程序案例台-功能-硬件设备，阅读设备使用条件和接入流程等，点击“开通”。管理员扫码确认后开通成功，进入设备管理页面。

2.2 添加硬件设备 （需审核）

进入硬件设备，点击添加设备，按照每个字段对应的说明填写信息，如实填写设备相关信息，否则会导致审核不通过。

2.3 获取设备 model_id

设备注册成功后，可获得平台分配的 model_id ，model_id 是调用小程序设备能力相关接口的重要凭证。获取 model_id 后，小程序可按照相关文档指引调用「设备消息」等硬件能力。

2.4 申请设备能力（需审核）

model_id 获取之后，在设备管理入口，点击右侧“申请设备能力”-“消息能力”。

（设备消息能力审核通过状态）

三、获取设备消息

「小程序设备消息」能力指的是，只要用户在小程序内订阅通知，开发者就可以将这些事件以订阅消息的形式发送给用户。消息在微信内的产品形态，目前以“服务通知”形式呈现。 申请设备消息必须先完成“二、设备接入”。关于小程序订阅消息的基础介绍可参考文档

3.1 获取模板

登录小程序管理后台——功能——订阅消息——公共模板库——长期订阅，查看可选用的设备消息模板。

基于设备状态的变化，对于一些需要对用户进行提醒的情况，专门为设备提供了长期订阅消息，会以「服务通知」的形式下发给用户。目前可能用到的场景包括但不限于：

1. 对生命财产可能造成影响的告警：烟雾/水浸/温度/防盗传感器告警、门锁被撬、陌生人闯入等
2. 影响到设备正常使用的提前预警：低电量预警、故障提醒、耗材用尽提醒等
3. 需要人工介入做进一步操作的提醒：门铃呼叫、洗衣完成等

如现有模板无法满足，需申请新增模板，请加群沟通。「硬件服务」沟通群：

申请格式如下：

申请事项：申请新增设备模板消息

小程序名称：

小程序主体：

APPID：

设备消息场景描述：

所属行业：如：智能家居

设备型号：如：空气净化器

模板框架：如：

标题：空气净化器耗材提醒

提醒时间：mmdd hhmm

所在位置：卧室

提示说明：空气净化器滤网已到达更换时间，请及时更换。

属于哪种情况：

1. 对生命财产可能造成影响的告警
2. 影响到设备正常使用的提前预警
3. 需要人工介入做进一步操作的提醒
4. 其他，请补充具体内容

3.2 获取模板ID

选择设备消息模板中需要的关键词，并提交。

注意：设备消息模版的关键词内容由平台生成，为枚举值，开发者不能够自定义内容。

提交后，可在“我的模板”中找到对应模板的模板 ID ，每个模板以 template_id 标记。

3.3 获取设备票据

获取 snTicket 用于「发起订阅」步骤。详见服务端设备票据接口 hardwareDevice.getSnTicket 。

四、触发设备消息

4.1 发起用户订阅

发起订阅调用  wx.requestSubscribeDeviceMessage  接口会有以下授权弹窗出现，用户同意订阅消息后，才会有设备消息发送至用户的微信会话

呼叫、告警等消息，可引导用户在小程序内完成设备消息订阅，用户需勾选左侧消息，并点击右侧强提醒按钮后提交“允许”。

（以上为小程序门禁设备长期消息弹窗样式）

示例代码

wx.requestSubscribeDeviceMessage({
    sn: 'xxxx',
    snTicket: 'xxxxx',
    modelId: 'xxxxx',
    tmplIds: ['xxxxx'],
    success(res) {
        console.log('[wx.requestSubscribeDeviceMessage success]: ', res)
        // { 'QCpBsp1TGJ1ML-UIwAIMkdXpPGzxSfwJqsKsvMVs3io': 'accept' }
    },
    fail(res) {
        console.log('[wx.requestSubscribeDeviceMessage fail]: ', res)
    }
})

接入文档：https://developers.weixin.qq.com/miniprogram/dev/framework/device/device-access.html#_5-%E5%8F%91%E9%80%81%E8%AE%BE%E5%A4%87%E6%B6%88%E6%81%AF

4.2 发送设备消息

开发者通过微信服务端接口向用户推送设备消息。详见服务端设备消息发送接口  hardwareDevice.send 

注意：开发者需要在小程序的合理场景内，给用户提供长期消息的授权弹窗。如用户实现房屋认证后通过用户操作触发“门禁机呼叫提醒”的订阅弹窗。