飞尔智能移动端接入指南 Powered by MM-Wiki

飞尔智能移动端接入指南

创建于 2019/08/29 15:19:16

修改于 2019/12/03 13:57:12

### 功能概述
飞尔智能SDK主要提供对飞尔AI音箱（FR-X1）的配置管理功能，集成与设备端、云服务的通讯协议，便于开发者快速、高效的实现移动端与设备端的互联互通，主要分为以下几个部分：

+ SDK接入前期准备
+ 实现音箱网络配置
+ 与音箱建立连接
+ 与音箱保持通信
+ 调用音箱相关服务信息接口

### SDK实现的功能：

|功能名称|功能描述|Android接口列表|iOS接口列表|
|:---|:---|:---|:---|
|设备序列号|获取设备的序列号|requestVboxInfo()|(void)requestVboxInfo|
|设备版本|支持版本进行在线OTA升级|sendStartUpdateInfo()|(void)startUpgradeVbox|
|位置信息|1.获取设备所在位置|requestVboxInfo()|(void)requestVboxInfo
||2.可以手动调整设置设备、家、公司个性化地址。|setVBoxLocation() setUserPoiInfo() qryUserPoiInfo() setVboxLinkNetLocation()| |
|还原所有设置|可还原音箱及帐号配置信息|requestClearData() resetUserAccount()|void)resetVbox:(httpCompletionBlock)completionBlock;|
|解绑设备|在APP中手动解绑设备|unBindVbox()|(void)unbindVbox:(httpCompletionBlock)completionBlock;|
|设备绑定状态通知|当设备进行绑定、解绑信息通知|见附录|@property (nonatomic, copy) void (^selectVboxBlock)(NSInteger code, NSString \*vboxId);|
|设备配网功能|1.音箱配网采用蓝牙BLE和ELian两种方式，通过手动方式进行配网连接。|startWifiConfig()|(void)startWiFiConnect:(NSString \*)ssid password:(NSString \*)password;|
||2.支持热点配网（当前手机本身热点）|startHotSpotConfig()||
|展示网络连接状态|获取设备在线、离线、休眠状态|requestVboxState()|(void)requestVboxState;|
|设备休眠|用户可在APP手动进行设备休眠及解除休眠操作|sendSleepMode()|(void)vboxSleep; (void)vboxWakeup;|
|唤醒反馈设置|设置音箱的反馈方式，即仅指示灯或指示灯+提示音|sendModifySettingInfo()| (void)vboxSetWakeupFeedBack:(BOOL)isLightWithSound;|
|设备昵称|设置音箱的个性昵称及房间位置|setVboxNickInfo()|(void)setVboxNick:(NSString \*)nick room:(NSString \*)room completion:(httpCompletionBlock)completionBlock;
|自定义唤醒词|更改唤醒词，用户可以自己设定4-6个字的唤醒词|requestVboxWakeWord() addWakeupWord() sendSwitchWakeWord() sendCustomWakeWord() getCustomWakeWord()|(void)evaluateWakeUpWord:(NSString \*)word completion:(httpCompletionBlock)completionBlock; (void)requestVboxWakeupWordList; (void)requestVboxWakeupWordDetail:(NSString \*)word completion:(requestVboxWakeUpWordDetailBlock)completionBlock; (void)switchWakeupWord:(NSString \*)word type:(NSInteger)type; (void)setCustomWakeUpWord:(VBCustomWakeWordModel \*)customWord; (void)generateWakeUpWord:(NSString \*)word pinyin:(NSString \*)pinyin completion:(httpCompletionBlock)completionBlock;|
|红外设备学习|1.用户通过选择品类-品牌-红外学习的过程，完成添加红外设备的功能|getIrBrands() getIrDeviceCategory() getIrBrands()| (void)queryIrDeviceCategory:(httpCompletionBlock)completionBlock; (void)queryIrDeviceBrand:(NSString \*)categoryNo completion:(httpCompletionBlock)completionBlock; (void)queryIrDeviceInfo:(NSString \*)categoryNo brandNo:(NSString \*)brandNo completion:(httpCompletionBlock)completionBlock; (void)addIrDevice:(FSBindDeviceInfo \*)deviceInfo completion:(httpCompletionBlock)completionBlock;|
||2.学习方式分为逐个学习（型号匹配）和一键学习（遥控器匹配）两种方式|qryInfraredModelAndRid() sendInfraredData() irChangeMatchProgress() sendInfraredData() startIrLearn()|(void)changeIRLearnProgress:(FSChangeIrLearnStatusParam \*)irLearnStatus completion:(infraCompletionBlock)completionBlock; (void)sendIRData:(FSSendIrDataEntity \*)irDataEntity completion:(infraCompletionBlock)completionBlo|
|红外设备列表展示|学习过的红外设备列表展示，并可进行增删改查及调整红外设备所在房间位置|getUserIrDeviceList() deleteUserDevice() submitIrDeviceInfo() updateUserIrDevice()|(void)queryIrDeviceList:(httpCompletionBlock)completionBlock; (void)updateIrDevice:(FSUpdateDeviceInfo \*)deviceInfo completion:(httpCompletionBlock)completionBlock; (void)deleteIrDevice:(NSString \*)deviceId completion:(httpCompletionBlock)completionBlock;|
|红外功能H5接口|集成红外功能H5页面|FrPageView|
|遥控器面板控制|通过手机远程控制音箱发射红外码进而控制红外设备|sendInfraredData() updateDeviceStatus() qryDeviceStatusById()|(void)sendIRData:(FSSendIrDataEntity \*)irDataEntity completion:(infraCompletionBlock)completionBlock; (void)updateIrDeviceStatus:(NSString \*)deviceId key:(NSString \*)key completion:(httpCompletionBlock)completionBlock; (void)queryIrDeviceStatus:(NSString \*)deviceId completion:(httpCompletionBlock)completionBlock;|
|语音控制昵称|设置语音控制昵称|submitIrDeviceInfo() updateUserIrDevice()|(void)updateIrDevice:(FSUpdateDeviceInfo \*)deviceInfo completion:(httpCompletionBlock)completionBlock;|
|闹钟提醒|1.手动或语音设置闹钟和提醒的功能|sentSetAlarm()|(void)setVboxAlarm:(AlarmEntity \*)alarm;|
||2.获取闹钟列表|requestAlarmList()|(void)requestVboxAlarmList:(requestAlarmsBlock)completionBlock;|
|倒计时|手动或语音设置倒计时功能|qryCountdown() sendSetCountdown()| (void)requestVboxCountDown; (void)startCountdown:(NSString \*)timeString; (void)stopCountdown;|
|音乐开通授权|授权酷狗帐号后，可使音箱播放酷狗音乐|initMusic() qryVipInfo() sendCode() doLogin() accUnBind()|(void)sendMusicVerifyCode:(NSString \*)phoneNum success:(successBlock)success fail:(failBlock)fail; (void)loginMusicByMobile:(NSString \*)phoneNum code:(NSString \*)code multipleUsers:(multipleUserBlock)multipleUsers success:(successBlock)success fail:(failBlock)fail; (void)loginMusicByMobile:(NSString \*)phoneNum code:(NSString \*)code userId:(NSString \*) userId success:(successBlock)success fail:(failBlock)fail; (void)qryMusicInfoWithSuccess:(successBlock)success fail:(failBlock)fail; (void)logoutMusicWithUserId:(NSString \*)userId success:(successBlock)success fail:(failBlock)fail;|
|温湿度查询|获取当前设备周围环境的温湿度情况，展示在APP中|requestVboxState()|(void)requestVboxState;|

### 安全策略

##### 1.SDK参数配置

SDK内部参数由飞尔提供，包括RSA秘钥、应用ID和业务代码，针对不同接入方，提供完全不同的配置参数，从而确保各合作伙伴不会发生冲突。

调用SDK时，需要的用户ID，Token需要接入）从飞尔云服务器获取，任一参数错误都会导致sdk无法正常调用。

SDK内部也不会将任何参数以任何形式序列化到外部存储设备，app结束后会立即释放。

##### 2.SDK与飞尔云通信加密

1. HTTP加密：

飞尔云HTTP服务全部采用https协议，通过SDK访问飞尔云服务器时，所传递的数据均经过两层加密，第一层通过AES进行加密，第二层通过RSA进行加密，防止数据通过外部抓包等方式进行解析。

2. TCP加密：

飞尔TCP长连接端口均增加了SSL加密机制，SDK和音箱或者飞尔云进行连接时，必须通过SSL认证才能连接成功。

##### 3.SDK混淆机制（Android）

Android端SDK经过混淆处理，防止通过反编译方式获取源码。混淆配置如下：

```java
-keepclasseswithmembernames class * {
 native <methods>;
}
-keep class com.feiersmart.app.entity.** { *; }
-keep class com.feiersmart.app.vbox.** { *; }
//1.0.1.070版本以后新增
-keep class com.kugou.common.** { *; }
-keep class com.kugou.kgmusicsdk.** { *; }
```
### 账号绑定流程

##### 1.概述

合作方使用飞尔sdk时，为了简化用户的使用流程，可以通过sdk使用合作方的账号来绑定飞尔的账号；合作方获取到飞尔的账号userid和token后，就可以正常调用sdk封装的业务接口；如果在使用的过程中，sdk业务接口返回token失效，需要重新使用以下流程获取新的token。主要包括以下两种方案，合作方可以根据自已的账号体系选择一种使用。

##### 2.合作方账号安全校验方案

使用该方式绑定飞尔账号时，飞尔云端会调用合作方的云端接口获取用户账号信息。

1、调sdk需要传入合作方账号的唯一标识（uid）和合作方云端的账号鉴权标识（code）。

2、飞尔云端会通过参数uid和code，调合作方的接口获取合作方的账号信息，合作方可以通过code校验本次调用是否已经被授权。

![](/images/3/4/flow2.png)
##### 3.合作方账号未校验方案

使用该方式绑定飞尔账号时，飞尔云端不会通过合作方的云端接口进行合作方账号有效性的验证。

![](/images/3/4/flow1.png)

### SDK接入指南

飞尔智能SDK主要针对Android和iOS开发者：

[Android接入指南](https://appsdk.feiersmart.com/page/display?document_id=7)
[iOS接入指南](https://appsdk.feiersmart.com/page/display?document_id=8)