设备绑定开发指南
引言
目前DemoApp（以Android为例）支持的设备绑定效果见设备绑定【重要】。
设备端存在4G【4G无线】/有线/局域网（设备热点模式）网络连接的情况。也存在使用App网络进行二维码/蓝牙配网，最终使用Wifi无线网络，或手机AP热点模式下使用手机4G/5G无线网络的情况。
设备绑定解绑方式和场景
目前支持两种方式的设备绑定和解绑，分别为云端API接口和AppSDK接口。如下表所示：
| 绑定和解绑方式 | 链接说明 | 备注（适用场景） |
|---|---|---|
| 云端API接口 （建议模式） | 绑定设备 解绑设备 | 适合客户有云平台，有设备管理需求（比如：使用自己的设备列表），有历史设备 适合客户使用自有账号体系，对接多个云平台的场景 适合客户前期使用相速通用版方案，后计划迁移使用相速私有化部署模式的情况 |
| AppSDK接口 | Android: 设备绑定 设备解绑 iOS: 设备绑定 设备解绑 | 适合客户无云平台或不关注设备绑定到云平台的场景 |
通过云端API接口绑定和解绑【重要】
- 使用自有账号体系下，强烈建议客户使用云端接口绑定方式（相比AppSDK绑定方式更简单且能保持数据一致性）
- 强烈建议客户自己管理设备，使用自己的设备列表（可以兼容历史系统以及方便后续升级到私有化部署模式）
建议客户优先使用自己的云平台管理设备，比如：App上使用自己的设备列表。这样可以兼容历史数据，可以对接多个云平台等。尤其是在使用了自有账号体系情况下，强烈建议客户自己管理设备。
设备绑定和解绑先走自己的云平台，再调用AIRTC云平台绑定接口和解绑接口，这样充分保证了客户云平台与AIRTC云平台数据的一致性，同时云端绑定和解绑接口是同步的，使用简单，无需监听消息网关中设备的绑定状态。
另外，客户的App绑定自己的云平台可以参考相速AppSDK绑定的实现（见下图标号1）。
图中一 ~ 二解释如下：
标号一：客户设备端（以下简称设备端）自行通过配网流程，确保设备端网络连通。
标号二：设备端集成DeviceSDK，按要求先进行初始化。后调用xs_iot_open，再调用xs_iot_connect。设备网络连通情况下，AppSDK会与AIRTC云平台建立设备信令长连接并验证激活码的有效性，这个过程也称为设备上线。
通过云端接口绑定，无论设备是否上线，激活码等无异常情况下都会成功。设备上线可以在云端绑定成功前后。
如果客户在海外存在多机房的情况，则绑定设备时，建议就近调用某个区域中心的网关接口。先获取用户所属的数据中心（任何一个区域数据中心都支持），再调用指定数据中心的绑定或解绑接口。通过云端API接口绑定的一般流程
以AP热点模式绑定为例
图中标号1 ~ 3解释如下：
标号1: App通过扫描设备机身二维码，向自己的云平台查询设备的平台来源（适合客户使用了多家AppSDK，确定使用了某家设备，才初始化某家AppSDK的场景）。如果确定是相速AIRTC方案的设备，需要初始化相速AppSDK，否则不需要初始化（当然进一步的判断可能还包含设备列表，如果包含了相速AIRTC的设备，也是要初始化相速AppSDK，不过可以延迟，否则可能无法直播等视频操作）。
标号2: 一旦设备配网完成，整合了相速AIRTC DeviceSDK的设备，就会自己与相速云平台建立连接，即设备上线。新增设备连网成功（或已绑定状态）上报。如果设备未绑定，则是连网成功状态（等待App来绑定）。如果设备已绑定，则是已绑定状态，复用之前的Online状态。详见：物的状态变更消息之Status参数。
- 4G或有线状态下，设备会网络连通后，会立即上线，无需配网的过程。此时新增的设备连网成功（或已绑定状态）上报对这种场景同样适用。
标号3: App调用客户云平台绑定接口，客户云平台调用相速云平台的绑定接口。此绑定接口的内部逻辑判断遵循控制台上该产品配置的绑定方式的约束。此时如果设备是已上线，则设备与相速云平台交互后，最终绑定成功，返回Online状态。
绑定过程中各细分步骤错误情况及技术说明
以AP热点模式绑定为例，Android表示Android客户端特有，iOS表示iOS客户端特有。
| 错误场景 | 描述 | 备注 | 错误【码】 | 技术说明 |
|---|---|---|---|---|
| 手机扫描不到AP(Android) | 设备可能没有Reset进入配网模式 | 通常是绑定设备操作流程问题 | 无 | App在UI上加强用户绑定流程引导 |
| 连接AP失败(Android) | 1. 输入错误默认AP密码 2. 自动连接时，密码正确但连接失败，通常是设备问题 | 用户操作或App自动连接 | 无 | 针对这两种情况，建议App监听连接状态，做好相应的提示 |
| 手机与AP连接后，与设备通信(Android) | 连接AP热点IP失败 | 需要确认连接的设备IP与手机分配的IP在同一网段 | Connect()方法返回值false表示socket连接失败 | 研发阶段务必确保双方IP地址在同一网段。原则上不会发生在用户使用阶段 |
| 连接AP失败(iOS) | 1. 输入错误默认AP密码 2. 密码正确但连接失败，通常是设备问题 3. 连接了错误设备AP热点 4. 设备AP热点的ip及port端口错误 5. 其他手机已连接了设备热点 | 用户操作或App自动连接。 | App调用AppSDK的startConnectWithReq方法，连接成功返回true，连接失败返回false。连接失败原因参考AIRTCAPLinkError错误枚举: NoError BadConfigError BadParamError ConnectTimeoutError ReadTimeoutError WriteTimeoutError ReadMaxedOutError ClosedError OtherError 其他由系统API抛出的错误信息 | 当请求失败时，App根据错误枚举值做友好提示。 AIRTCAPLinkError错误枚举释义: NoError（无错误） BadConfigError（配置无效错误） BadParamError（请求参数错误） ConnectTimeoutError（连接超时错误） ReadTimeoutError（读超时错误） WriteTimeoutError（写超时错误） ReadMaxedOutError（读取达到上限） ClosedError（连接已关闭） OtherError（其他错误） |
| 手机与AP连接后，与设备通信 | App发送WiFi信息给设备失败 | 发送的WiFi信息格式异常或缺少字段 | 设备端返回： 1001 1002 | 1001：缺少ssid字段 1002：JSON格式无效 原则上开发阶段就会固化好，不应该发生在用户使用阶段 |
| 设备无法连接找到的WiFi | 1. WiFi信息错误 2. 设备不支持频段 | 设备语音提示异常，可考虑在通信阶段由设备返回支持2.4G/5G WiFi，由APP过滤可用的WiFi | 无 | 设备需要做好连接网络失败时的友好提示 |
| 所有平台间接口 | 调用所有的平台间接口 | 500 | 提供请求id和截图反馈 | |
| 2000 | 请求参数不合法，按照接口定义检查参数和类型是否匹配 | |||
| 平台间接口带cloudToken参数发起请求 | 20017 | cloudToken不合法，检查cloudToken是否正确或已过期 | ||
| 绑定接口 | 调用平台间绑定接口 | 发起云端绑定 | 5005 | 产品不存在或未关联。检查productKey是否正确，检查APP是否已关联产品。 |
| 30313 | 账号未注册，请先注册。通过App先进行自有用户登录操作 | |||
| 31493, 31007 | 激活码非法，检查productKey和deviceName是否正确 | |||
| 绑定消息监听 | 通过监听物的状态变更消息，来判断设备的绑定状态等信息 | 设备状态： online：上线 offline：离线 bindOnline：绑定上线（设备上线，但是未绑定） | 监听不到消息 | 参考：物的消息变更消息 监控不到绑定消息时务必第一时间反馈 |
| 设置设备属性 | 调用平台接口设置一些默认属性 | 部分私有化部署环境支持 | 6221 | 设备处于离线或休眠状态，要先将设备恢复成在线状态 |
通过AppSDK绑定和解绑
1. AppSDK绑定bindToken（设备扫手机二维码）模式
用于设备扫App配网二维码绑定的场景，支持测试设备和正式量产设备。
图中一 ~ 二和1~7标号（步骤）解释如下：
标号一：客户设备端（以下简称设备端）通过自己实现或集成三方SDK。针对无线网络场景，需要依赖步骤2（标号2），也就是通过二维码或蓝牙等方式获取到无线网络的信息，才能进行配网，连通设备端网络。
标号二：设备端集成DeviceSDK，按要求先进行初始化。后调用xs_iot_open，再调用xs_iot_connect。如果是有线网络场景，则与AIRTC云平台建立设备信令长连接并验证激活码的有效性。如果是无线网络场景，则会等待，依赖步骤一的无线网络场景完成。这个过程也称为设备上线。
标号1：客户自有客户端（以下简称客户端）通过Android AppSDK的设备绑定流程中的BIND_TOKEN模式，调用start方法，从AIRTC云平台获取到bindToken。客户端只监听设备绑定成功与否的回调结果即可。注意：AppSDK会自动监听是否可以发起设备绑定请求。
- iOS AppSDK的设备绑定流程类似，请点击。
标号2：设备绑定之bindToken传递：客户端需要将bindToken和配网信息（无线网络场景下）通过二维码或者蓝牙传递给设备端，也可以在配网之后通过局域网通信方式传给设备端，没有强制要求。设备端解析成功之后，将bindToken信息通过xs_iot_setBindToken接口传递给IoTSDK。
标号3：设备绑定之bindToken验证：DeviceSDK（IoTSDK）通过设备信令到AIRTC云平台验证bindToken有效性。 设备端需要监听设备绑定是否成功的结果。
标号4：云平台bindToken验证有效后，会通过信令向AppSDK发送设备可绑定的回调。AppSDK收到回调后，就会自动发起设备绑定请求。
标号5：AppSDK向AIRTC云平台发起绑定设备请求，云平台执行设备端和客户端的绑定动作。由于是HTTPS同步请求，AppSDK可以获取到云平台的绑定结果。结果会回调给监听的客户端，客户端就可以知道设备绑定是否成功了。
- 1和5拆分开，主要是为了确保设备端就在就安装者在身边，降低串号的风险。
- 注意：步骤4和5的衔接为AppSDK自动完成，无需客户端的参与。
标号6：云平台在绑定成功后，会生成一个deviceToken，通过设备信令发送给DeviceSDK。设备端会收到DeviceSDK回调的绑定结果，设备端需要保存该deviceToken。后deviceSDK向云平台进行业务请求，会携带该deviceToken，作为业务鉴权凭证。
标号7：云平台绑定成功后的消息也会打入消息队列，客户云平台可以消费消息队列，获取设备绑定成功的消息。
2. AppSDK绑定扫码激活（又称快速绑定）模式
用于4G或有线设备无需配网，直接通过App来扫设备信息二维码进行绑定的场景。支持测试设备和正式量产设备。
图中一 ~ 二和1~6标号（步骤）解释如下：
标号一：客户设备端（以下简称设备端）通过自己实现或集成三方SDK。此步骤不依赖DeviceSDK存在。
标号二：设备端集成DeviceSDK，按要求先进行初始化。后调用xs_iot_open，再调用xs_iot_connect。因为网络已经连通，设备与AIRTC云平台建立设备信令长连接并验证激活码的有效性。这个过程也称为设备上线。
标号1：客户自有客户端（以下简称客户端）通过Android AppSDK的设备绑定流程中的SCAN_QUICK_ACTIVE模式，调用start方法（支持传入productKey和deviceName方法）。客户端只监听设备绑定成功与否的回调结果即可。
- iOS AppSDK的设备绑定流程类似，请点击。
标号2：设备绑定之bindToken传递：平台端将bindToken通过设备信令传递给设备端，设备端解析成功之后，执行绑定操作（见标号3）。
标号3：设备绑定之bindToken验证：DeviceSDK（IoTSDK）通过设备信令到AIRTC云平台验证bindToken有效性。 设备端需要监听设备绑定是否成功的结果。
标号4：云平台bindToken验证有效后，会通过信令向AppSDK发送设备绑定结果的回调。AppSDK收到回调后，提示客户端设备绑定结果。
标号5：云平台在绑定成功后，会生成一个deviceToken，通过设备信令发送给DeviceSDK。设备端会收到DeviceSDK回调的绑定结果，设备端需要保存该deviceToken。后deviceSDK向云平台进行业务请求，会携带该deviceToken，作为业务鉴权凭证。
标号6：云平台绑定成功后的消息也会打入消息队列，客户云平台可以消费消息队列，获取设备绑定成功的消息。
设备解绑流程说明
通过AppSDK解绑类似AppSDK绑定，参考AppSDK提供的相关接口即可。
特别说明
- 通过DemoApp绑定的设备，如果使用相同的ProductKey/DeviceName，以及相同的账号登录客户自有的客户端，则可以看到DemoApp添加的设备。反之亦然。
- 无论通过哪种AppSDK绑定方式，设备都要自己实现配网（DeviceSDK不支持配网）。