Embedded API v1 介绍

说明

嵌入式协议(Embedded iFLYOS Voice Service, 简称EVS)是一个相对IVS更简单的协议,为厂商接入提供方便,降低设备运行要求,本协议采取websocket进行通讯。

创建设备

在使用EVS协议接入iFLYOS前,需要先在设备接入控制台创建设备。点击查看创建流程

授权认证

连接到 iFLYOS 之前,你需要做以下动作

  1. 通过设备接入平台添加一个嵌入式API版本的设备
  2. 参考设备认证授权文档实现设备端的授权功能流程,获取对应Token信息

根据上面的指南你能获取到两个 Token 信息分别是:access_token,refresh_token;同时也会获取到一个 expires_in。

{
  "token_type": "bearer",
  "refresh_token": "4_vujpFOfu0G5yf4**************DwX5S80s74CY7",
  "expires_in": 86400000,//单位秒
  "created_at": 1526485197,//单位秒
  "access_token": "bd6XMEqzIokI6mnMM**************iKAdYNa9T-1WXY"
}
参数 类型 说明 是否必需
token_type string 取值:bearer或jwt,当前仅支持bearer
access_token string 在建立 websocket 连接时和每次发送 request 时需要使用
expires_in long access_token的有效时长,单位为秒
created_at long 令牌创建时间,unix时间戳,单位为秒
refresh_token string 令牌刷新token

你的系统需要通过 created_atexpires_in 以及当前时间来判断 access_token 的有效期,并且及时刷新,下面我们提供一个使用 javascript 来判断的 token 的时候刷新的代码

let expires_in = 86400000//单位秒
let created_at = 1526485197//单位秒
let expires_time = expires_in + created_at

let time_now = Math.floor(Date.now() / 1000)

// token还有一个小时要过期
if (expires_time - time_now < 3600) {
  // 调用刷新 access_token 接口,使用 refresh_token 刷新token信息;
  // 保存刷新后的token信息,包括 expires_in 等信息;
}
// 使用最新access_token执行

连接协议 - 使用 WebSocket 连接到 iFLYOS

  1. device_id 是指每个设备的唯一标识,一般使用设备的 SN 码即可;(为了确保设备上的接口不被破解滥用,请将 device_id 提交到设备接入控制台,iFLYOS将会在设备授权、连接时,进行验证,非白名单设备将无法使用iFLYOS)

  2. 将上面步骤获取的 access_token 和 device_id 作为URL参数,连接websocket:

    安全地址:wss://ivs.iflyos.cn/embedded/v1?token={access_token}&device_id={device_id}

    非安全地址:ws://ivs.iflyos.cn/embedded/v1?token={access_token}&device_id={device_id}

注意

我们建议你选择安全地址(wss)接入iFLYOS,除非设备本身有无法解决的限制。若你的设备选择接入非安全地址(ws),在设备提交审核时,请说明为什么接入非安全的协议(ws),否则OS运营团队将不会通过你的设备审核。

交互协议说明

设备发送给iFLYOS云端的请求

iFLYOS 中,我们把设备发送到服务端的指令称为请求(request),一次发送一个请求object,每次发送请求时,均需要同步发送iflyos_headeriflyos_context

{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {...}
}

构建通用请求的iflyos_header

iflyos_header 中的内容为向云端报告本次请求来源(如硬件设备)的基础信息,具体包含的内容如下:

"iflyos_header": {
  "authorization": "Bearer xxxxxx",
  "device":{
    "device_id": "xxxxxxx",
    "ip": "xxx.xxx.xxx.xxx",
    "location": {
      "latitude": 132.56481,
      "longitude": 22.36549
   },
    "platform": {
      "name": "android",
      "version": "8.0.1"
   }
 }
}
参数 类型 说明 必填
authorization String 用户的access_token,每一次都需要带上去,用于用户鉴权,需要参考上文方法避免 token 过期
device Object 设备信息
device.device_id String 设备的唯一标识,正式环境请使用设备唯一的SN码
device.ip String 设备公网IP,若设备无法获取,可不填
device.location Object 设备的位置信息,设备端可通过GPS获取或在配网时候从手机获取后写入设备中
device.location.latitude Float 纬度和 longitude 成对出现
device.location.longitude Float 经度和 latitude 成对出现
device.platform Object 设备系统平台信息
device.platform.name String 系统平台名称。取值:android, linux, ios。请注意:全部字母均为小写
device.platform.version String 系统平台版本

构建通用请求 iflyos_context

iflyos_context 用于向云端同步当前的设备状态,以功能模块为区分,代表发送请求时设备最新的信息。每次对服务端发起的请求都要包含它,iflyos_context 中需要包含所有已经实现的设备模块的信息。

"iflyos_context": {
  "system": {...},
  "recognizer": {...},
  "speaker": {...},
  "audio_player": {...},
  "alarm": {...},
  "screen": {...},
  "template": {...},
  "video_player": {...},
  "app_action": {...},
  "playback_controller": {...},
  "launcher": {...},
  "interceptor": {...}
}
参数 类型 说明 必填
system Object 系统信息。点击查看详情
recognizer Object 语音识别器信息。点击查看详情
speaker Object 扬声器信息。点击查看详情
audio_player Object 音频播放器信息。点击查看详情
alarm Object 设备闹钟信息,若未实现设备闹钟,该项可不出现。点击查看详情
screen Object 设备屏幕信息,若设备无屏,该项可不出现。点击查看详情
template String 设备模板显示信息。若设备不实现云端模板,该项可不出现。点击查看详情
video_player Object 视频播放器。若设备不支持视频播放,该项可不出现。点击查看详情
app_action Object app操作。若设备不支持(非安卓设备),该项可不出现。点击查看详情
playback_controller Object 播放控制。若设备没实现音频播放或视频播放,该项可不出现。点击查看详情
launcher Object 启动器。若设备不支持启动器页面跳转等能力,该项可不出现。点击查看详情
interceptor Object 用于拦截器的上下文。若设备未使用云端拦截器,该项可不出现。点击查看详情

iFLYOS云端发送给设备的回复

iFLYOS 中,我们把设备接收到服务端的指令称为响应(response),一次收到一个iflyos_metaiflyos_response集,设备需要按iflyos_response列表顺序执行操作。

{
  "iflyos_meta": {...},
  "iflyos_responses": [
    {
      "header": {
        "name": "xxx"
      },
      "payload": {...}
    },
    {
      "header": {...},
      "payload": {...}
    }
  ]
}

解析通用回复的 iflyos_meta

iflyos_meta 中主要是云端回复的元数据,代表本次回复是对某一个request的回复。

{
  "iflyos_meta": {
    "trace_id": "xxxxxx",
    "request_id": "xxxxx", //当云端主动发送response时,该字段不会出现
    "is_last": true //标记这组回复是不是这个request_id关联的最后一组回复
  }
}
参数 类型 说明 必须出现
trace_id String 本次交互的跟踪标识,提技术支持工单时可能会用到,建议打印在系统日志中
request_id String 本次回复对应的请求的唯一标识,与request中的request_id一致。当云端主动发送response时,该字段不会出现
is_last Bool 标记本次回复是不是这个请求的最后一组回复

注意:设备请求发送成功,但云端不返回执行时,会返回如下的结果:


{
  "iflyos_meta": {
    "trace_id": "xxxxxx",
    "request_id": "xxxx",
    "is_last": true
  },
  "iflyos_responses": []
}

功能模块说明

注意

  • 以下要求必须实现的requestresponse,如果不按需求实现,iFLYOS的运营人员将会在审核时拒绝你的请求。
  • 以下可选实现的requestresponse,你可以根据自身设备的需求进行实现。
name 说明 实现要求
recognizer 语音识别器,这是iFLYOS交互的基础 必须实现
audio_player 音频播放器,播放的内容可能是音乐、新闻、闹钟响铃或TTS语音 必须实现
system 系统相关 必须实现
alarm 设备本地闹钟 可选实现
speaker 扬声器控制 可选实现
video_player 视频播放器, 可选实现
playback_controller 播放控制,在部分场景下,用户可通过触控或按键控制音频播放进度 可选实现
app_action APP操作,针对系统的第三方APP进行的操作 可选实现
screen 屏幕控制 可选实现
template 模板展示,用于通过界面模板给用户反馈更丰富的信息 可选实现
launcher 启动器 可选实现
interceptor 自定义拦截器,是iFLYOS 实现自定义语义理解的基础 可选实现