A-设备订阅关系管理

一、设备订阅关系管理

通过 XLinkAddDeviceTask 可在云端建立用户和设备之间的订阅关系。订阅关系建立后，可使用 XLinkSyncDeviceListTask 获取与当前用户有订阅关系的设备列表。通过XLinkRemoveDeviceTask可解除订阅关系。

订阅关系	操作途径
订阅关系的建立	1.添加设备 2.设备分享 3.其他建立云端订阅关系的途径（如通过二维码订阅）
订阅关系的解除	1.删除设备 2.设备重新激活（设备重置后再连上云端，设备会重新激活） 3.其他解除云端订阅关系的途径

1、二维码订阅设备

除了使用通过正常的流程（扫描设备->添加订阅设备）订阅设备外，设备也允许使用二维码进行订阅。使用二维码订阅时不需要依赖于 XAPP SDK 的任务，直接通过 RESTFUL 接口即可进行处理。

二维码订阅时设备不要求一定在线，但是设备必须已经激活
二维码订阅操作必须设备支持允许
二维码订阅时必须用户已登录并携带有效 token

1.1、配置设备支持二维码订阅

您需要先登录物联云平台。

产品必须添加一个二维码订阅专用的系统数据端点（$1002）
该产品下的设备必须本身上报该数据端点值为 true，说明设备支持二维码订阅
通过产品下选择某个设备，在设备详情界面查看其二维码

1.2、二维码订阅设备

通过第三方方式获取到二维码图片中的文本信息之后，将文本信息提供给 RESTFUL 接口即可订阅设备。

直接使用接口订阅

URL: /v2/user/{user_id}/qrcode_subscribe
REQUEST:
{
    "qrcode": "二维码数据"
}
RESPONSE:
{
    "id": "设备ID",
    "mac": "设备MAC地址",
    "pid":"产品ID",
    "name":"设备名字"
    "sn":"序列号",
    "custom_property":{
        "{key}": "{value}"
    }
}

调用 XAPP SDK 封装 RESTFUL 接口进行订阅

String qrCode = "xxx";
Call<DeviceApi.QRCodeSubscribeResponse>  call = XLinkRestful.getApplicationApi().qrCodeSubscribeDevice(userId,request);

2、订阅关系变更回调

在订阅关系建立或解除时，以下两个回调会被触发：

设备信息变更

public void onDeviceChanged(XDevice xDevice, XDevice.Event event) {
   switch(event) {
       case SUBSCRIBE: // 与xDevice的订阅关系建立
           break;
       case UNSUBSCRIBE: // 与xDevice的订阅关系解除
           break;
   }
}

云端事件推送

public void onEventNotify(EventNotify eventNotify) {
    switch (eventNotify.messageType) {
        ...
        case EventNotify.MSG_TYPE_SUBSCRIPTION_CHANGE: {
            //消息类型为设备订阅关系发生变化
            EventNotifyHelper.SubscriptionChangeNotify notify = EventNotifyHelper.parseSubscriptionChangeNotify(eventNotify.payload);
             
            //根据设备ID获取变更的设备对象
            XDevice device = XLinkDeviceManager.getInstance().getDeviceFromDeviceId(eventNotify.device_id);
             
            //请注意不一定设备维护列表中一定会有此设备
            if(device!=null){
                if (notify.sub == EventNotifyHelper.SubscriptionChangeNotify.SUBSCRIBED) {
                        // 与xDevice的订阅关系建立
                }else if (notify.sub == EventNotifyHelper.SubscriptionChangeNotify.UNSUBSCRIBED) {
                        // 与xDevice的订阅关系解除
                }  
            }
        }
        ...
    }
    ...
}

尽管这两个回调都可用，强烈建议统一在 onEventNotify() 中进行所有云端消息推送的处理，可以避免一些不必要的错误操作；这是因为onDeviceChanged()方法只会在当前设备管理列表中存在相应的设备时，才能提供对应的设备对象进行回调，若设备管理列表中不存在相应的设备对象时，则无法回调该方法。

实际上onDeviceChanged()的回调也是来源于onEventNotify()，当设备的订阅关系变更时，XAPP SDK 将接收到云端的消息推送，在此过程中会再回调到onDeviceChanged()事件中。

当接收到订阅关系变化的通知时，XAPP SDK内部已断开和设备的连接，开发者应主动或提示用户刷新设备列表。

以上两个回调依赖云端连接，属于云端的推送消息。主要提供给APP开发者处理订阅关系被动建立或被动解除的情况（例如人为重置设备）。

如果是用户主动添加或删除设备（XLinkAddDeviceTask 或 XLinkRemoveDeviceTask ），那么在执行成功的时候就要进行后续处理，例如刷新设备列表、更新ui等等，不应该等待云端通知再进行处理

3、新增订阅方式——自v6.2版本起

此版本更新了一种新的订阅方式，该订阅方式与原订阅方式在实现处理上是完全不同的，相对于原有的订阅方式更加高效，灵活性也更强。

新的订阅方式主要通过以下流程进行：

设备开启订阅使能
扫描设备
从设备获取 pinCode，校验码
从云端获取订阅码
发送订阅码给设备
设备提交订阅码到云端验证
接收云端订阅结果返回

这里的普通场景是指：设备与 APP 处于相同的网络中（相同的局域网），且设备与 APP 都能正常连接到外网（即可连接到云端）的情况。

在普通场景下，首先需要扫描到设备，之后仅需要使用一个任务即可完全以上所有操作，并且任务兼容旧的任务，是属于相同的任务类。

扫描设备
扫描设备与此前的任务是一致的，都是使用相同的任务进行扫描。

//扫描设备并监听设备扫描结果回调
XLinkScanDeviceTask task = XLinkScanDeviceTask.newBuilder()
        .setProductIds("pid1", "pid2")
        .setRetryInterval(3000)
        .setTotalTimeout(30000)
        .setScanDeviceListener(listener)
        .build();
XLinkSDK.startTask(task);

订阅设备
在扫描到设备之后，则可以将该设备对象作为参数，执行订阅设备任务。

//扫描设备并监听设备扫描结果回调
XLinkScanDeviceTask task = XLinkScanDeviceTask.newBuilder()
        .setProductIds("pid1", "pid2")
        .setRetryInterval(3000)
        .setTotalTimeout(30000)
        .setScanDeviceListener(listener)
        .build();
XLinkSDK.startTask(task);

注：

以上任务与原订阅任务完全相同，差异在于需要提供来自设备的 pinCode
若不设置设备的 pinCode，默认为物联云平台密钥，注意设备的 pinCode 应该是厂商决定的，只有厂商决定不使用 pinCode 时，才可以不设置

上次更新：2024-05-09