I-SDK基本配置 | 文档中心

程序运行前要配置SDK config配置信息，之后调用[[XLinkSDK share] startWithConfig:config]后生效。前面快速开始时已经介绍了最简单的配置方式，此部分将具体地介绍一些常用的配置。

SDK 支持以下功能配置：

调试日志输出功能
API域名配置（API环境切换）
CM服务器地址和端口配置
全局的数据通讯策略
SSL的配置

XLinkConfig *config = [[XLinkConfig alloc] init];
 //设置API服务器地址与端口,默认值为正式环境: https://api2.xlink.cn:443
config.apiServer = @"https://api2.xlink.cn:443";
//设置CM服务器地址与端口,默认值为正式环境: mqtt.xlink.cn,1884
config.cloudServer = @"mqtt.xlink.cn";
config.cloudServerPort = @"1883";
//SSL目前仅对CM连接有效,测试环境时需要开启SSL false
//SSL设置为YES的时候，cloudServerPort需要设置为1884
config.enableSSL = NO;
//设置是否输出输出日志
config.debug = YES;
//设置数据默认发送策略,默认为XLinkSendDataPolicyAuto
config.sendDataPolicy = XLinkSendDataPolicyAuto;
[XLinkSDK share] startWithConfig:config];

调试日志输出功能

SDK 的日志输出功能必须设置才能正常使用，否则无法正常输出到控制台查看，SDK已提供了默认的日志输出实现，默认日志配置如下：

将输出日志到控制台

默认的日志输出配置仅需要一句代码

XLinkConfig *config = [[XLinkConfig alloc] init];
...
config.debug = YES;
...

API域名配置

API域名默认是使用正式环境的API域名配置，配置选项列表说明如下：

配置名称	含义	默认值
apiServer	设置HTTP API服务器	https://api2.xlink.cn:443
cloudServer	设置云端服务器IP	mqtt.xlink.cn
cloudServerPort	设置云端服务器端口	1883
enableSSL	是否使用SSL	NO

其中关于API及CM服务器是包括了正式环境与测试环境的地址，以下为不同环境下的地址信息:

环境	域名	端口	启用SSL(仅公有云)
正式环境API	https://api2.xlink.cn	443	true
正式环境CM	mqtt.xlink.cn	1884
测试环境API	http://api-test.xlink.io	1080	false
测试环境CM	54.222.229.62	1883

如果您的使用环境为私有云，请联系运维工作人员获取响应的API、CM服务器地址。

注意：不进行服务器地址配置的情况下，默认使用正式环境信息

全局的数据通讯策略

物联云平台采用设备物模型属性来描述物理设备的状态和能力

可通过设备状况的查询和回调接口来获取设备的实时状态
可通过设置设备物模型属性的接口来实现设备的远程控制

SDK 与设备连接有不同的情况，包括以下三种情况：

通过云平台与设备连接，后续简称为：云端连接
通过内网（局域网）与设备连接，后续简称为：内网连接
同时存在云端连接与内网连接

SDK 支持指定内网的本地连接或外网的云端连接来发送数据，也可以采用 AUTO 模式由 SDK 底层自适应内外的数据通讯。数据发送的策略有如下几种：

发送策略	说明
XLinkSendDataPolicyAuto	默认值，自动选择发送数据的通道(内/外网)，选择的依据是当前通道的 RTT，RTT 低的通道会被选中
XLinkSendDataPolicyLocalOnly	只尝试从内网发送
XLinkSendDataPolicyLocalFirst	尝试从内网发送，失败则尝试外网发送
XLinkSendDataPolicyCloudOnly	只尝试从外网发送
XLinkSendDataPolicyCloudFirst	尝试从外网发送，失败则尝试内网发送

在初始化 XLinkSDK 时可以设置全局使用的数据通讯策略：

XLinkConfig *config = [[XLinkConfig alloc] init];
...
config.sendDataPolicy = XLinkSendDataPolicyCloudOnly;
...

全局的回调监听

SDK 提供了常用接口的全局回调，包括了以下几种回调

XLinkCloudDelegate-云端回调，SDK 与云平台连接的状态回调及所有来自云端的消息推送
XLinkUserDelegate-用户状态回调，SDK 维护的用户状态回调，涉及用户退出、授权信息过期、踢出等状态
XLinkDataDelegate-数据回调，SDK 接收到设备数据变更的通知回调
XLinkDeviceStateDelegate-设备状态回调，SDK 维护的设备状态变更时的通知回调

这部分的监听回调都在全局配置时添加的，一般情况下是在应用对象中（Application）中统一进行监听和处理

XLinkCloudDelegate-云端回调

云端回调包括SDK连接到CM云端服务器的连接状态回调,以及所有来自云端的消息推送

设置云端连接状态回调的代理：

[XLinkSDK share].cloudDelegate = self;

云端回调方法：

// 当SDK与云平台连上/断开的时候，会回调这个方法。
- (void)onCloudStateChangedWithCloudConnectionState:(CloudConnectionState)state{
}
// 当SDK连接上云端，并接收到云端推送时，会回调这个方法。
- (void)onReceiveEventNotify:(EventNotify *)eventNotify{
}

事件的详细介绍说明请查看进阶篇

XLinkUserDelegate-用户状态回调

用户登录状态的回调，在用户账号退出时，会通过此回调进行用户退出账号原因的通知

设置用户授权状态变化回调的代理：

// 用户授权状态变化回调的代理
[XLinkSDK share].userDelegate = self;

用户授权状态变化回调方法:

//用户信息回调
//当帐号信息被正确设置，而且用户被下线（被踢或者手动退出）的时候，会回调这个方法。
- (void)onUserLogout:(LogoutReason)reason{
    // 请根据LogoutReason进行处理
}

用户退出原因有四种：

原因	说明
LogoutReasonUserLogout	用户主动退出，一般情况下由于调用`[[XLinkSDK share] logoutAndStop]`引起的
LogoutReasonSingleSignKickOff	用户账号由于被其它人登录导致了当前账号被踢出的
LogoutReasonTokenExpired	用户凭证过期
LogoutReasonUserAuthInfoInvaild	用户授权信息不正确

通常情况下，除了LogoutReasonUserLogout都是需要用户重新登录的，一般发生时也建议调用[[XLinkSDK share] logoutAndStop]停止当前SDK

XLinkDataDelegate-数据回调

设备数据数据变更回调，在设备的数据变更时，设备进行上报后会通过回调方法通知到APP进行更新。
目前包含的回调数据类型有以下几种：
1.设备物模型属性发布；
2.设备事件上报回调。

设置接收数据变化的回调

//接收设备数据变化的回调
[XLinkSDK share].dataDelegate = self;

回调方法：

/// 当SDK收到设备发布物属性时，会回调这个方法。
/// @param xDevice 接收到数据的设备
/// @param dataPayload 物属性
- (void)onAttributePublishWithDevice:(XDevice *)xDevice dataPayload:(NSDictionary *)dataPayload {
    
}

/// 当SDK收到设备事件上报时，会回调这个方法。
/// @param xDevice 接收到数据的设备
/// @param eventName 接收到事件名
/// @param dataPayload 时间内容
- (void)onThingEventReportWithDevice:(XDevice *)xDevice eventName:(NSString *)eventName dataPayload:(NSDictionary *)dataPayload {

}

XLinkDeviceStateDelegate-设备状态回调

设备状态回调在设备状态发生变更时会进行回调，请注意并非所有的设备都会在此回调接口中进行回调，有且仅有存在设备维护列表中的设备状态发生改变时才会通知此回调通知，关于“维护列表设备”的详细说明可参考附录FAQ

设备状态回调的注意点：
\1. 通过XLinkSyncDeviceListTask同步列表操作进行设备同步后,默认都会添加到维护列表中
\2. 通过XLinkAddDeviceTask添加的设备也会添加到设备维护列表中
\3. 目前设备状态回调未进行过滤操作,即存在多次回调均为同一设备状态(当内部进行状态改变操作时发生回调,无论设备状态是否已经发生过改变)

设置设备连接状态回调的代理：

[XLinkSDK share].deviceStateDelegate = self;

设备状态回调方法

// 受SDK管理的设备状态发生改变时
-(void)onDeviceStateChanged:(XDevice *)xDevice withDeviceState:(XDeviceState)state{
 
}
 
//设备属性（设备名称）或者设备状态发生改变时，还有设备订阅关系变化的时候会回调这个方法。
- (void)onDeviceChanged:(XDevice *)xDevice withEvent:(XDeviceEvent)event{
     
}

SDK 启动与停止

注意以上为 SDK 初始化的一些基础配置，SDK 需要在启动后才能正常使用,包括HTTP的请求和Task的使用等

// 启动SDK
[[XLinkSDK share] start];

不使用SDK时，可调用stop。

// 停止SDK, 断开云端连接，回收资源
[[XLinkSDK share] stop];

当App退出登录（授权失败或其他原因需要重新授权的情况）时，可调用[[XLinkSDK share] logoutAndStop]

// 停止SDK, 断开云端连接，回收资源，清除授权信息。
//请注意此处会停止当前的SDK,如果需要再次使用必须再次StartSDK
[[XLinkSDK share] logoutAndStop];

注意：任何时候使用[[XLinkSDK share] stop]方法都会导致SDK的中止,而一旦SDK中止后,就不会再与设备保持任何通讯;在任何一次stop之后需要使用SDK的话,请务必调用start操作

多点登录

多点登录是针对对于同一账号可能在不同场景中使用时，不希望账号之前发生互踢现象而新增的一个功能。如同时允许在 pad 及手机上登录同一账号。

使用多点登录时，需要指定多点登录的登录源，当不存在登录源信息时，默认为同一基本用户。当存在登录源信息时，在相同账号登录时会依赖登录源进行识别，以判断是否允许同一账号同时处于登录可用状态。

XLinkConfig *config = [[XLinkConfig alloc] init];
...
//设置登录源,单点登录时可以不进行设置,不同登录源允许多点登录
config.resource = resource;
...
 
[[XLinkSDK share] startWithConfig:config];

不同登录对账号的登录状态影响如下:

登录状态1	登录状态2	是否允许同时登录
默认登录源+账号	默认登录源+账号	不允许
默认登录源+账号	其它登录源+账号	允许
登录源1+账号	登录源1+账号	不允许(同账号且同一登录源)
登录源1+账号	登录源2+账号	允许(同账号但不同登录源)

注意：登陆源只支持数字和字母（暂不支持空格），最大长度为16个字符，默认为 null

上次更新：2024-05-09