# 第三方账号接入
说明
该接口需要联系商务开通权限。
# 账号接入方式
# iFLYOS 账号
iFLYOS
是基于账号体系
来为用户提供更好的能力,实现多场景的打通,以及信源权限等管理的。所以我们提供了iFLYOS账号
作为统一的账号来认证使用iFLYOS Voice Service
的服务。iFLYOS账号
使用的是“手机号 + 验证码”的方式来认证用户。
# 第三方账号
如果厂商有自己的账号体系,或不方便接入iFLYOS账号
,可以使用第三方账号
来接入iFLYOS
。这种情况下,对于用户认证、设备授权的安全性,更多的由厂商的服务提供保证。
授权流程具体如下:
说明
设备接入时,需要通过IVS SDK
来获取iFLYOS
授权Token
,无论使用iFLYOS账号
还是第三方账号
,对设备来说都是透明的,设备端的逻辑无需改动。
# 第三方账号授权
设备的授权过程,一般都是需要厂商应用
来协助引导用户进行对应操作。以下为相关主要流程操作:
- 当
设备
收到OS授权服务
返回的user_code
时,通过某种方式,将user_code
输出给应用。输出的方式可以考虑参考以下几种方案:- 通过BLE通讯回传应用;(适合通过BLE配网的设备)
- 通过WIFI内网通讯回传应用;(适合通过AP配网的设备)
- 通过直接显示的方式;(适合带有显示屏的设备)
- 通过音频播放(
user_code
为6位数字),用户在应用
中输入;(适合没有显示屏的设备)
- 当
应用
取得user_code
后,向厂商的服务上报user_code
(厂商用户认证后); - 厂商服务接收到
user_code
后,调用OS授权服务
提供的验证user_code接口
(带用户信息); OS授权服务
对user_code
验证通过后,会将用户绑定到对应设备上,并等待设备
获取Token
;- 当
设备
获取Token
时,OS授权服务
会生成Token信息,给设备
返回Token信息
,同时返回成功给厂商服务
;
注意
云端接口调用需要认证,具体请参考:获取服务端接口访问令牌
# 通过user_code进行设备授权接口
Host
https://auth.iflyos.cn
URL
POST /oauth/thirdparty/device_confirm
请求header
"Authorization": "Bearer {{server_client_access_token}}"
server_client_access_token
通过第一个接口获取- 不包含
{{}}
Bearer
与token
之间是有一个空格的
请求body
{
"user_code": "123456",
"thirdparty_id": "xxxx"
}
参数说明
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
user_code | string | 是 | 设备申请授权时获取的user_code |
thirdparty_id | string | 是 | 第三方账号系统用户唯一标识 |
响应
Status: 200 OK
{
"code": "0000",
"message": "授权成功"
}
# 接入App SDK
iFLYOS
通过App SDK
向厂商提供各自对音箱的管理能力,厂商可以通过在自家APP
中集成App SDK
,即可快速向用户提供各种对设备的管理功能。比如:通用配网、设备管理、智能家居控制、信源管理、闹钟管理等等。
以下为接入App SDK
情况下,厂商应用
与iFLYOS
的交互流程:
厂商操作步骤:
- 当
厂商应用
用户登录后,或者App SDK
调用登录接口时,应用
向厂商服务
获取Token信息
; 厂商服务
调用OS授权服务
提供的SDK用户云端授权接口
(需要传用户信息),OS授权服务
会返回属于用户的Token信息
;应用
收到用户的Token信息
后,调用App SDK
提供的方法,将Token信息
配置到SDK即可;
# 小飞在线SDK用户token云端授权接口
Host
https://auth.iflyos.cn
URL
POST /oauth/thirdparty/app_token
请求header
Accept: application/json
Content-Type: application/json
"Authorization": "Bearer {{server_client_access_token}}"
server_client_access_token
通过第一个接口获取- 不包含
{{}}
Bearer
与token
之间是有一个空格的
请求body
{
"thirdparty_id": "xxxx"
}
参数说明
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
thirdparty_id | string | 是 | 第三方账号系统用户唯一标识 |
响应
Status: 200 OK
{
"token_type": "bearer",
"refresh_token": "THIRDPARTY_xxxxnP90c4YeHxxx1O83zmUhv_oH3xxxxx5fRU3WqNAZ93aOnBnycdB",
"expires_in": 86400000,
"created_at": 1547709087,
"access_token": "THIRDPARTY_xxxx2bUyll3xxxzMI53d2oac6cPkxxxxx4wfszqC1T8Cvvm9Pxj"
}
# 设备解绑接口
URL
POST https://api.iflyos.cn/home/thirdparty/unbind_device
请求header
"Authorization": "Bearer {{server_client_access_token}}"
通过appid申请的token进行用户设备解绑,目标设备需要满足两个条件:
- 设备属于该appid
- 设备绑定的用户为该appid的第三方账号用户
请求body
{
"client_id": "72f72235-25d2-4196-a098-9f7a3346eff2",
"device_id": "e5074994-d28e-463b-9b7b-754d47cd837a"
}
参数说明
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
client_id | string | 是 | 需要解绑的设备的client_id |
device_id | string | 是 | 需要解绑的设备的device_id |
成功响应
Status: 200 OK
{
"message": "解绑成功"
}
失败响应
Status: 400 Bad Request
{
"message": "设备不在该appid下",
"code": "1002"
}
# 设备绑定关系同步
请在OS设备接入控制台中填写回调地址,但设备绑定关系变动时,我们将会通知你。当设备使用第三方账号时可以配置该回调地址。当设备的绑定状态变更时,iFLYOS会向该地址发送POST
请求,要求第三方服务返回HTTP状态码:200
。若服务响应时间超过5秒或返回200
以外的http状态码时,会进行两次重试。
请求校验
回调地址需要校验请求是否来源于iFLYOS时,可以通过请求Header的X-Sign
字段进行校验
校验步骤
- 从设备接入控制台 - 产品信息中获取设备的
client_secret
- 拼接字符串"iflyos" +
请求body
+client_secret
- 对步骤2中的字符串进行md5(小写)
- 校验步骤3的签名是否与X-Sign相同
请求headers
Content-Type: application/json
X-Sign: xxxxxxxxxxxx
请求body
{
"type": "bind",
"client_id": "client_id",
"device_id": "device_id",
"timestamp": 1592905420372,
"third_id": "xxxxxx"
}
请求参数
参数名 | 参数说明 | 参数示例 | 必填 |
---|---|---|---|
type | 通知类型 bind: 绑定 unbind: 解绑 | bind | 是 |
client_id | 设备client_id | xxx-xxx-xxx-xx | 是 |
device_id | 设备device_id | xxx-xxx-xxx-xx | 是 |
timestamp | 状态变更的时间戳(单位:毫秒) | 1592905420372 | 是 |
third_id | 设备绑定用户的third_id,当通知类型为unbind 时值为null | 1592905420372 | 否 |
# 第三方账号功能申请
需要提供以下信息:SDK的AppID
(AppId需要提前生成)、设备的ClientID
、是否提供手机号、用户标识的格式(数字、字符串、MD5、UUID ....)