A-v6.1.0.3版本升级到v6.2.3.7版本

一、功能说明

1、新增

1.1、新增订阅方式

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

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

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

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

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

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

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

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

XLinkAddDeviceTask task=XLinkAddDeviceTask.newBuilder()
        .setXDevice(device)
        //设置来自设备的pinCode
        .setPinCode(pinCode)
        .setListener(listener)
        .build();
XLinkSDK.startTask(task);

注：

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

1.2、新增快捷登录任务

如果用户已经进行过登录，且不希望再次要求用户登录应用时需要输入账号和密码时，可以使用此快捷登录任务进行登录。快捷登录要求需要提供用户此前已登录过的缓存信息。

//构建登录的用户信息对象
XLinkUser user=new XLinkUser();
user.setUid(10086);
user.setAuthString("auth string");
user.setRefreshToken("refresh token");
 
//执行快捷登录任务
XLinkRefreshTokenTask task=XLinkRefreshTokenTask.newBuilder()
        .setXLinkUser(user)
        .setListener(listener)
        .build();
XLinkSDK.startTask(task);
 
//使用快捷登录时，请不要在初始化时配置用户信息
//XLinkConfig.newBuilder().setXLinkUser(userCache)

注意事项：
1.快捷登录任务是一个任务，请务必启动 XAPP SDK 之后才能使用；
2.使用快捷登录任务时，请不要在初始化时配置用户信息，会造成冲突；
3.推荐使用新的快捷登录方式（若旧方式可满足需求也不需要变更）

快捷登录成功时，将回调成功方法，登录失败时，将回调错误方法，错误码来源为 API 错误码，详情请参考APP-SDK错误码

1.3、新增短信登录任务

使用短信登录任务是新提供的一个登录任务，用户可以不使用账号密码，直接使用自己的手机号和短信验证码登录账号。

• 获取短信验证码
  获取短信验证码是需要直接使用 restful 接口的，该接口说明在新增接口中有提及，使用方式如下：

//构建登录的用户信息对象
XLinkUser user=new XLinkUser();
user.setUid(10086);
user.setAuthString("auth string");
user.setRefreshToken("refresh token");
 
//执行快捷登录任务
XLinkRefreshTokenTask task=XLinkRefreshTokenTask.newBuilder()
        .setXLinkUser(user)
        .setListener(listener)
        .build();
XLinkSDK.startTask(task);
 
//使用快捷登录时，请不要在初始化时配置用户信息
//XLinkConfig.newBuilder().setXLinkUser(userCache)

• 进行短信验证码登录
  短信验证码登录时，需要企业ID、手机号及短信验证码，如果是非默认地区（中国大陆，+86）的手机号则需要设置手机区号。

XLinkSmsAuthorizeTask task = XLinkSmsAuthorizeTask.newBuilder()
        //企业ID
        .setCorpId(corpId)
        //手机号
        .setPhone(phone)
        //短信验证码
        .setVerifyCode(setVerifyCode)
        .setListener(new TaskListenerAdapter<UserAuthApi.UserSmsAuthResponse>() {
            @Override
            public void onComplete(Task<UserAuthApi.UserSmsAuthResponse> task, UserAuthApi.UserSmsAuthResponse result) {
                //短信验证登录结果，用户信息
            }
            @Override
            public void onError(Task<UserAuthApi.UserSmsAuthResponse> task, Throwable error) {
            }
        })
        .build();
XLinkSDK.startTask(task);

注：

1. 若未注册过的手机号，则会自动注册账号
2. 通过短信验证码登录并注册的账号，默认情况下没有登录密码，无法通过正常的账号密码方式登录

1.4、新增设备连接任务

设备连接任务是用于指定时间内尝试进行设备连接并返回结果的任务，在给定的超时时间内，若设备能连接成功，则返回成功结果；否则返回超时结果。

//配置当前设备的连接策略
int flag = XLinkConstant.FLAG_POLICY_LOCAL_ONCE_CONNECTION | XLinkConstant.FLAG_POLICY_CLOUD_ONCE_CONNECTION;
 
//执行设备连接任务
XLinkConnectDeviceTask task = XLinkConnectDeviceTask.newBuilder()
        //不设置时，默认使用该设备已有的连接策略
        //设备不存在设备管理维护列表中时，默认为一次性内网连接与外网连接
        .setConnectionFlags(flag)
        .setXDevice(xdevice)
        .setListener(listener)
        .setTimeout(45000)
        .build();
XLinkSDK.startTask(task);

注：

1. 在给定的超时时间内如果设备没有连接上，实际上不意味着设备肯定连接不上。如设置的设备连接策略是云端自动连接时，当连接断开后，设备实际上会在后台自动尝试重新连接，或者在满足连接条件时自动重新连接
2. 所有使用此方法的设备都会被添加到设备管理维护列表中，当已有该设备时，将会更新相应的设备信息；设备的状态变更都会在全局回调XLinkDeviceStateListener中回调
3. 若设备原本已存储设备管理列表中（如已同步过该设备），设置的连接策略将会覆盖原有的连接策略
4. v5版本中也存在类似的任务，功能是类似的，但是不完全一样，升级时请注意变更
5. 设备连接状态也可以直接通过设备管理进行切换处理

1.5、连接策略

字段	意义	说明
FLAG_POLICY_NONE_CONNECTION	无连接策略	不进行任何处理，延用当前设备状态
FLAG_POLICY_AUTO_CONNECTION	进行云端、内网自动连接	当设备云端或内网断开时，尝试自动重新连接
FLAG_POLICY_LOCAL_AUTO_CONNECTION	内网自动连接	当设备内网状态断开时会尝试进行自动连接
FLAG_POLICY_LOCAL_ONCE_CONNECTION	内网一次性连接	当设备内网状态断开后不会再进行连接，切换为此连接策略时，不影响当前内网的连接状态
FLAG_POLICY_CLOUD_AUTO_CONNECTION	云端自动连接	当设备云端状态断开时会尝试进行自动连接
FLAG_POLICY_CLOUD_ONCE_CONNECTION	云端一次性连接	当设备云端状态断开后不会再进行连接，切换为此连接策略时，不影响当前云端的连接状态

1.6、设备连接策略管理

设备的连接策略也是支持直接通过设备管理对象进行操作——XLinkDeviceManager。

//为设备添加内网的自动连接功能，不改变原有的连接策略
XLinkDeviceManager.getInstance().addDeviceConnectionFlags("xxx",XLinkConstant.FLAG_POLICY_LOCAL_AUTO_CONNECTION);
  
//移除设备的某种连接策略，不影响其它的连接策略
XLinkDeviceManager.getInstance().removeDeviceConnectionFlags("xxx",XLinkConstant.FLAG_POLICY_LOCAL_AUTO_CONNECTION);
  
//将设备的连接策略切换成某种连接策略，覆盖处理
XLinkDeviceManager.getInstance().setDeviceConnectionFlags("xxx",XLinkConstant.FLAG_POLICY_LOCAL_AUTO_CONNECTION);
  
//以上设置连接策略之后并不会立即生效，需要手动调用连接进行处理
int flag = XLinkDeviceManager.getInstance().getDeviceConnectionFlag("xxx");
XLinkDeviceManager.getInstance().connectDevice("xxx",flag);
  
//也可以直接构建相应的连接策略后，直接进行设备的连接处理
//在连接操作中会直接使用新的连接策略覆盖替换当前的设备原连接策略
int flag = XLinkConstant.FLAG_POLICY_LOCAL_AUTO_CONNECTION|XLinkConstant.FLAG_POLICY_CLOUD_AUTO_CONNECTION;
XLinkDeviceManager.getInstantce().connectDevice("xxx",flag);

注：

1. 在设备管理列表中配置连接策略时，连接策略不一定会即时生效

1.若当前设备已经内网连接中，但是原有的连接策略为仅一次性连接，切换为内网自动连接时，则在下一次设备断开时会自动进行连接；
2.若当前设备未进行任何内网连接，当设备切换为内网自动连接时，由于设备此前未进行内网任何连接，所以需要手动调用才会建立起内网连接并生效。

1. 通过设备管理切换连接策略要求设备必须已经存在设备管理维护列表中，否则不会进行任何处理
2. XLinkConnectDeviceTask会将直接连接的设备添加到设备列表中进行处理
3. 通过设备管理切换连接策略时，允许对现有连接策略进行更新，而XLinkConnectDeviceTask是直接覆盖原有连接策略

1.7、新增 XAPP SDK 重置方法

在此前版本中，XAPP SDK 初始化后，实际上 XAPP SDK 是只能进行启动与停止，不再支持其它的操作，包括如：API 地址的切换，配置信息的更新等。因此在一个进程中只能初始化一次 XAPP SDK，也只能配置一次 XAPP SDK。

为了解决以上问题，此次版本更新新增了支持 XAPP SDK 反初始，即重置 XAPP SDK 的功能，当使用 XAPP SDK 后需要重新配置信息时，可以通过 XAPP SDK 的反初始化方法重置 XAPP SDK 后再重新初始化。任何时间重置 XAPP SDK 时，都必定会终止当前所有任务，清除所有缓存数据信息，如设备信息，用户信息

//当SDK已经初始过后
//反初始化SDK，进行SDK的重置
//注意重置SDK时，必定会先终止SDK，请尽量在终止SDK前确定所有的任务都已经取消或者终止，防止不必要的问题
XLinkSDK.deinit();
 
//重新初始化SDK
XLinkConfig config = XLinkConfig.newBuilder()
    ...
    .build();
//请务必注意任何时间初始化SDK时应该使用此方法，不应该直接调用 XLinkSDK.init(),否则会有不兼容的问题
XLinkAndroidSDK.init(config);

1.8、新增 XAPP SDK 配置信息

在此版本更新中，新增了 XAPP SDK 的配置信息，提供了 XAPP SDK 支持的协议版本配置，设备内网自动连接功能配置，其它一些配置信息调整。

XLinkConfig config = XLinkConfig.newBuilder()
        //配置当前SDK支持的设备协议版本类型
        .setProtocolVersionSupportedFlags(XLinkConstant.FLAG_PROTOCOL_VERSION_V6)
        //配置当前SDK是否开启内网自动连接功能
        .setLocalNetworkAutoConnection(false)
        //配置SDK的日志输出功能
        .setLogConfig(XLinkAndroidSDK.defaultConfig(context))
        ...
        .build();

配置信息	说明
支持协议版本配置	由于设备仅支持某一种具体的协议类型，而 XAPP SDK 是兼容不同的协议类型；当明确知晓使用的设备协议类型，通过配置支持的协议可使 XAPP SDK 进行一些通讯数据上的优化，也会在一定程序上提高数据的通讯效率，降低丢包率；默认仅支持v6版本的设备
内网自动连接功能	在某些情况下对于内网的功能并不依赖，但是维护内网连接是会消耗一定的资源与数据通讯处理，并且大部分情况下通过外网即可完成相应的功能；因此当使用的场景基本不需要设备内网连接时，建议设置关闭此配置，有助于提升 XAPP SDK 的处理效率，减少资源占用
日志输出配置	此版本更新日志输出配置与之前无差异，但是表现将有一些变化。在此前版本中，如果不选择将日志输出到文件则无法在控制台查看到日志信息，现在已经修正该处理方式，不管何时，只要是开启了日志输出，都可以在控制台中查看到日志信息

1.9、新增 restful 接口

在此版本更新中，新增了部分 restful 接口

条目	内容
URL	/v2/user-cancelled
Method	XLinkRestful.getApplicationApi().deleteUserCancelled()
说明	注销当前用户，注意一旦注销将清除所有用户信息，无法找回

条目	内容
URL	/v2/user_auth_sms/verifycode
Method	XLinkRestful.getApplicationApi().posUserSmsVerifyCode(…)
说明	短信验证登录，发送手机验证码，有效期为2分钟

条目	内容
URL	/v2/user_auth_sms/captcha
Method	XLinkRestful.getApplicationApi().posUserSmsCaptcha(…)
说明	短信验证登录，请求或者刷新发送短信的图片验证码

条目	内容
URL	/v2/user_auth_sms
Method	XLinkRestful.getApplicationApi().authorizeSmsUser(…)
说明	短信验证登录，获取用户调用凭证

2、移除

2.1、设备管理对象

对于设备管理对象（API-XLinkDeviceManager）来说，由于连接策略的使用及部分结构调整，原有的一些连接方法将不再提供并移除掉。所有的连接操作都将以设备及连接策略的方式进行连接处理。

移除方法	说明
connectDeviceCloud(XDevice device)	进行设备云端连接，现已移除
connectDeviceLocal(XDevice device, XLinkDeviceStateListener stateListener)	进行设备内网连接，现已移除
disconnectDeviceLocal(XDevice device)	断开设备的内网连接

以上方法为原有的部分连接方法，现都已不再使用，请使用connectDevice(XDevice device, int flag)方法代替，连接时需要提供设备的连接策略

3、变更

3.1、类引用变动

为了解决兼容性问题，移动了一个类的引用位置，如有使用请留意变更或者重置导入即可，方法不进行任何变更，可正常使用。

类名	移动新位置	解决方式
DeviceHelper	cn.xlink.sdk.v5.util	删除引用位置的 import 语句，重新导入或者全局替换 import 语句

3.2、协议版本兼容

此前版本中，设备存在v5版本。v5版本的设备与v6版本的设备在扫描时是存在差异性的，因此在 XAPP SDK 配置时，提供了配置支持的协议类型，目前可选的协议类型有两种：

协议类型	说明
FLAG_PROTOCOL_VERSION_V5	v5版本协议
FLAG_PROTOCOL_VERSION_V6	v6版本协议

默认情况下仅开启v6版本协议的支持，需要兼容v5版本设备时，请注意开启v5版本协议支持。允许支持多个版本的协议。

XLinkConfig config = XLinkConfig.newBuilder()
        //配置当前SDK支持的设备协议版本类型
        .setProtocolVersionSupportedFlags(XLinkConstant.FLAG_PROTOCOL_VERSION_V6)
        //配置当前SDK是否开启内网自动连接功能
        .setLocalNetworkAutoConnection(false)
        //配置SDK的日志输出功能
        .setLogConfig(XLinkAndroidSDK.defaultConfig(context))
        ...
        .build();

注意事项：

1.当明确知晓使用的设备版本时，建议只使用该版本的设备时，仅配置支持该版本的协议，可以减少资源的使用及优化数据通讯，减少网络拥塞问题
2.需要兼容v5版本设备时，请务必配置支持v5版本协议，默认仅支持v6版本协议

3.3、连接策略配置变更

由于此版本更新新增了是否开启内网自动连接功能，该功能默认是不开启的，即默认情况下是不会尝试内网连接设备的。而此前版本中，由于没有默认情况下都是自动进行内网连接的，所以请注意此处变更。

3.3.1、设备添加

设备添加时是可选添加后的内网连接设置的，原配置默认为内网自动连接，当前版本默认为不进行内网自动连接，如果需要保留该内网自动连接功能，请注意更新该配置。

XLinkAddDeviceTask task = XLinkAddDeviceTask.newBuilder()
        //是否在添加成功后进行内网连接，此处相当于设置内网连接策略为自动连接
        //默认为false，相当于不需要内网连接
        .setConnectLocal(true)
        ...
        .build();
XLinkSDK.startTask(task);

注：

1. 原有添加设备时必定会进行内网的连接，所以实际上添加完之后是保持着内网连接的状态的，若不设置connectLocal的参数，默认为 false，即在设备断开后不会再尝试重新连接
2. 也可以在添加后再通过设备管理对象更新设备的连接策略
3. connectLocal的配置是内网自动连接，当设备内网连接断开后会尝试自动连接，仅需要某次连接时可添加后重新设置连接策略

3.3.2、设备同步

与设备添加类似，原配置默认为内网自动连接，当前版本更新默认为不进行内网自动连接，如果需要保留内网自动连接功能，请注意更新该配置。

XLinkSyncDeviceListTask task = XLinkSyncDeviceListTask.newBuilder()
        //是否在同步设备列表成功后进行内网连接，此处相当于设置内网连接策略为自动连接
        //默认为false，相当于不需要内网连接
        .setConnectLocal(true)
        ...
        .build();
XLinkSDK.startTask(task);

注：

1. 原有的同步设备列表默认会进行内网的自动连接，当前版本同步设备列表之后将不再进行内网自动连接
2. connectLocal的配置是内网自动连接，当设备内网连接断开后会尝试自动连接，仅需要某次连接时可同步设备列表后重新设置连接策略

3.3.3、全局配置

若完全需要保留设备内网自动连接功能，可以直接在初始化时开启该功能，开启该功能后则将与此前版本的 XAPP SDK 处理策略一致，不管任何位置默认都是进行内网自动重连，除非再进行局部的配置。

XLinkConfig config = XLinkConfig.newBuilder()
        //全局开启默认进行内网自动重连配置
        .setLocalNetworkAutoConnection(true)
        ...
        .build();
XLinkAndroidSDK.init(config);

二、更新说明

日期	更新内容
2018.09.14	版本更新说明
2018.08.31	新增版本更新说明

• 版本说明

类别	更新类型
配置优化	1.新增 XAPP SDK 反初始化，重置方法 2.新增支持的协议类型配置接口，优化数据通讯 3.新增内网自动连接配置接口，默认不开启 4.修正日志输出不转存到文件的情况下也允许输出到控制台
扫描优化	1.优化扫描任务，提高扫描结果的准确率及发现速度 2.优化扫描任务逻辑，提高扫描成功率 3.优化扫描操作，默认不开启设备内网自动扫描连接
订阅优化	1.修复订阅设备任务某些情况下不重试的问题，优化订阅任务流程 2.新增订阅设备方式
数据通讯	1.优化发送策略任务逻辑，修复任务某些情况下会尝试重试的问题 2.修复设备云端连接失败时，云端状态已断开时依然重试的问题 3.修复某些情况下云端断开时，未及时通知外部管理类状态变更的问题 4.优化设备上下线状态消息通知，提高准确性及响应速度
接口更新	1.新增短信登录的 restful 接口，新增用户注销接口 2.新增快捷登录任务 3.新增连接设备任务，新增连接策略 4.新增短信登录任务
资源优化	1.优化数据缓存，断开连接时清除缓存信息
其它	1.修正描述性文本错误

上次更新：2024-05-09