Appearance
APP SDK集成
一、简介
欢迎使用物联云平台应用端开发套件（XLINK APP SDK）服务！
为了便于企业能快速开发物联网应用 XLINK APP SDK 通过高度集成与云端、设备的通讯能力，设备管理能力、设备连接维护能力等，提供设备发现、设备添加、设备删除、设备控制等功能。
物联云平台应用端 SDK 包括 Android 和 iOS 版本，以及可以用于 Web/HTML5 运行环境的 JS SDK。
- 如果您是从旧版本 XAPP SDK 升级上来的，请务必查看相关的，Android升级请看Android升级指南，iOS升级请看iOS升级指南
- 如果您是全新集成物联云平台 XAPP SDK，请根据顺序快速开始了解 XAPP SDK 并根据指引进行使用
二、XLINK APP SDK功能特性
本SDK为应用程序提供了新设备发现、添加、连接和控制等接口，具体如下：
- 发现新设备 用于通过App自动扫描同网络下的新设备。
- 添加设备 将扫描到的新设备添加到当前用户账号下。
- 连接设备 实现与设备建立本地或云端的连接，以获取设备实时状态或远程控制设备，包括：
- 连接设备后，SDK内部自动维护与设备的连接。
- 连接策略可配置（仅限内/外网或自动切换）。
- 设备状态可知（未初始化、连接（内网连接/外网连接）、正在连接、断开）
- 获取设备状态 物联云平台采用数据端点来描述物理设备的状态和能力，通过设备状况的查询和回调接口，可以获取设备的实时状态，例如：
- 查询设备一个或多个数据端点状态
- 设备数据端点状态的更新通知
- 可订阅一个或多个数据端点的变化
- 控制设备 可通过更新数据端点状态的接口来实现设备的远程控制：
- 接收云端推送（EventNotify） 可通过该回调接口，接收来自于云端的消息推送，如通知、异常告警等。
- 其它：
- 可选的debug level
- 崩溃日志自动收集
- 运行时的log收集
除了上述基础的物联网接口外，物联云平台还为App开发者提供了丰富的RESTful APIs，详细请参阅《应用端RESTful API开发指南》。
三、流程简介
术语表
| 术语 | 意义 |
|---|---|
| 术语 | 意义 |
| XLINK APP SDK(XAPP SDK) | 物联云平台应用软件开发包，即通常所说的——SDK |
| XLINK Device SDK(XDEV SDK) | 物联云平台设备软件开发包，即通常所说的——设备 SDK |
| 产品 | 即企业要开发、生产、销售一个类型的设备，对应到企业管理后台的产品管理 |
| 设备 | 设备是产品的实体设备，这里特指直接接入物联云平台的智能设备，如网关，插座，灯泡 |
| 子设备 | 间接接入物联云平台的设备，如通过网关接入的温度传感器 |
| 企业后台 | 指物联云平台提供给企业客户的管理后台 |
| 企业账号 | 指登录企业管理后台的管理员账号 |
| 企业ID | 注册企业账号后，系统会自动给账号分配一个企业ID，调用Http接口需要使用到 |
| APP用户 | 指在APP端通过Http接口注册和登录的终端用户账号 |
| 数据端点 | 数据端点指产品的属性，APP可以通过获取和修改设备数据端点的值来进行控制设备.云平台可以根据维护的数据端点来处理数据统计、消息推送服务 |
| 设备分享 | 用户可以将设备分享给其他用户，与其他用户共同拥有设备，共同控制设备，只有设备的管理者才可分享设备给其他用户 |
| 订阅 | App用户与设备产生一种订阅关系授权，必须已订阅该设备的APP用户才能通过云端链接和控制设备及收到设备的消息推送 |
| 设备管理员 | 设备管理员可以分享设备、取消他人的订阅关系等。 平台默认第一个订阅设备的用户为管理员 |
| XLinkSDK | 代指 SDK 包中的入口 XLinkSDK |
| 启动 SDK | 代指 XLinkSDK.start() 操作，表示开始运行SDK |
| 停止 SDK | 代指 XLinkSDK.stop() 操作，表示停止运行SDK |
| 添加设备 | 代指设备配对并添加到设备维护列表中的操作 |
| 订阅设备 | 代指设备与当前用户绑定关系的操作（需要与云端通讯） |
| 通讯策略 | 代指原有的“发送策略”，XLinkSendDataPolicy，防止某些情况下的理解存在错误 |
| 消息推送 | 代指云端下发的消息事件 EventNotify |
| 踢出 | 代指用户单点登录状态下被其它登录强制下线的情况 |
| 快捷登录 | 代指用户不需要使用账号及密码登录，通过 SDK 配置的用户信息即可快速登录并使用 SDK 的操作 |
| APP | 代指手机应用，使用大写不使用小写 |
| v5/v6 | v代指 version 版本号，所有版本号 v 以小写形式存在 |
| 内网/本地 | 代指同一局域网内 |
| 云端连接 | 代指 SDK 管理设备连接状态时，与服务器保持的连接 |
| 内网连接 | 代指 SDK 管理设备连接状态时，与同一局域网内设备的保持的连接 |
| CM 服务器/云端服务器 | 代指用于连接设备及 SDK 进行通讯，使用 MQTT 协议进行通讯的服务器，与 Restful 接口使用的 http 服务器并不相同，二者是区分开的；通常会简称为 CM 或云端 |
四、注意事项
需要注意的是，物联云平台提供的 XLINK APP SDK 只是对通讯能力的封装的库文件，并不是一个可执行文件。如需要完成对设备的控制、添加等功能，仍然需要基于 XLINK APP SDK 开发应用进行具体功能的实现。
五、常用API接口概览
| API接口 | 功能概述 |
|---|---|
| API调用规范 | API调用规范，帮助开发者更有效地使用API接口 |
| 用户注册 | 用户可通过手机或者邮箱在物联云平台下注册成为一个用户。 |
| 用户登录 | 通过账号和密码进行登录认证获得一个有效的调用凭证，即可通过调用凭证使用物联云平台用户相关的接口。 |
| 用户基础信息 | 获取用户基础信息。 |
| 用户消息 | 用户消息是指用户收到用户订阅的设备触发了告警规则而产生的告警消息，并显示在用户的消息列表中，用户可以对消息进行查看，删除等操作。 |
| 用户拓展属性 | 用户通过设置、修改其扩展属性用来实现相关功能。可以使用扩展字段来存储用户地址、生日等自定义信息。 |
| 设备功能 | 物联云平台提供了用户可注册设备的入口，只需要在物联云平台管理台中的产品配置“允许用户注册设备”之后，用户可以通过本接口注册新的设备并与设备建立订阅关系。一般用于用户绑定蓝牙设备后进行蓝牙设备注册。 |
| 家庭管理 | Home解决用户在设备使用过程的家庭场景需求，具体有Home家庭的创建管理、家庭消息盒子等内容。 Home管理员可通过Home来管理家庭成员和家庭中的设备权限 |
| 第三方用户身份接入 | 物联云平台用户身份系统允许使用目前主流的第三方账号体系进行认证登录（如QQ、微信、微博），也支持使用其他平台账号体系登录（必须符合物联云平台第三方登录认证规范，并且在物联云平台进行相应配置）。 |
| APP SDK错误码说明 | APP SDK错误码说明 |