# 第三方账号接入

说明

该接口需要联系商务开通权限。

# 账号接入方式

# iFLYOS 账号

iFLYOS是基于账号体系来为用户提供更好的能力,实现多场景的打通,以及信源权限等管理的。所以我们提供了iFLYOS账号作为统一的账号来认证使用iFLYOS Voice Service的服务。iFLYOS账号使用的是“手机号 + 验证码”的方式来认证用户。

# 第三方账号

如果厂商有自己的账号体系,或不方便接入iFLYOS账号,可以使用第三方账号来接入iFLYOS。这种情况下,对于用户认证、设备授权的安全性,更多的由厂商的服务提供保证。

授权流程具体如下:

auth_flow.png

说明

设备接入时,需要通过IVS SDK来获取iFLYOS 授权Token,无论使用iFLYOS账号还是第三方账号,对设备来说都是透明的,设备端的逻辑无需改动。

# 第三方账号授权

设备的授权过程,一般都是需要厂商应用来协助引导用户进行对应操作。以下为相关主要流程操作:

  1. 设备收到OS授权服务返回的user_code时,通过某种方式,将user_code输出给应用。输出的方式可以考虑参考以下几种方案:
    • 通过BLE通讯回传应用;(适合通过BLE配网的设备)
    • 通过WIFI内网通讯回传应用;(适合通过AP配网的设备)
    • 通过直接显示的方式;(适合带有显示屏的设备)
    • 通过音频播放(user_code为6位数字),用户在应用中输入;(适合没有显示屏的设备)
  2. 应用取得user_code后,向厂商的服务上报user_code(厂商用户认证后);
  3. 厂商服务接收到user_code后,调用OS授权服务提供的验证user_code接口(带用户信息);
  4. OS授权服务user_code验证通过后,会将用户绑定到对应设备上,并等待设备获取Token
  5. 设备获取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通过第一个接口获取
  • 不包含{{}}
  • Bearertoken之间是有一个空格的

请求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_auth_flow.png

厂商操作步骤:

  1. 厂商应用用户登录后,或者App SDK调用登录接口时,应用厂商服务获取Token信息
  2. 厂商服务调用OS授权服务提供的SDK用户云端授权接口(需要传用户信息),OS授权服务会返回属于用户的Token信息
  3. 应用收到用户的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通过第一个接口获取
  • 不包含{{}}
  • Bearertoken之间是有一个空格的

请求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进行用户设备解绑,目标设备需要满足两个条件:

  1. 设备属于该appid
  2. 设备绑定的用户为该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字段进行校验

校验步骤

  1. 从设备接入控制台 - 产品信息中获取设备的client_secret
  2. 拼接字符串"iflyos" + 请求body + client_secret
  3. 对步骤2中的字符串进行md5(小写)
  4. 校验步骤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 ....)