系统_v1.1

版本修改

版本 新增
v1.1 增加CheckSoftwareUpdate指令、CheckSoftwareUpdateSucceeded事件、CheckSoftwareUpdateFailed事件、UpdateSoftware指令、UpdateSoftwareStarted事件、UpdateSoftwareSucceeded事件、UpdateSoftwareFailed事件、RestoreFactory指令、Reboot指令、RevokeAuthorization指令。

SynchronizeState 事件

当建立一个新的连接时,必须发送SynchronizeState事件到云端来更新组件。

消息样式

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "SynchronizeState",
      "messageId": "e52e7a4c..."
    },
    "payload": {
    }
  }
}

header参数

参数名 说明 类型
messageId 代表一条message的唯一ID String

UserInactivityReport 事件

在设备不活跃后的一小时设备需要上报该事件,并在之后的每一小时都上报一次,直到设备活跃。设备活跃的定义:确保用户在设备旁边,如:用户操作了设备上的按键和屏幕或用户开始了语音交互。设备开始活跃时,上报该事件的计时器需要归零。

消息样式

{
   "event": {
    "header": {
      "namespace": "System",
      "name": "UserInactivityReport",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "inactiveTimeInSeconds": 36000
    }
  }
}

header参数

参数名 说明 类型
messageId 代表一条message的唯一ID String

payload参数

参数名 说明 类型 必须出现
inactiveTimeInSeconds 距离用户上一次活跃的秒数,这个值应该永远是3600(1小时)的倍数 Long

ResetUserInactivity 指令

该指令用于将上报UserInactivityReport事件的计时器重置归零。

消息样式

{
  "directive": {
    "header": {
      "namespace": "System",
      "name": "RresetUserInactivity",
      "messageId": "e52e7a4c..."
    },
    "payload": {
    }
  }
}

header参数

参数名 说明 类型
messageId 代表一条message的唯一ID String

SoftwareInfo 事件

该事件用于将设备的软件信息同步到云端,在以下情况必须上报该事件:

  • 当使用永久存储的设备进行初始化或固件更新时
  • 没有永久存储的设备每一次启动/重启时
  • 当接收到ReportSoftwareInfo指令时

消息样式

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "SoftwareInfo",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "firmwareVersion": "String"
    }
  }
}

payload 参数

参数名 说明 类型 必须出现
firmwareVersion 固件版本号,采用32位整型上传 String

ReportSoftwareInfo 指令

云端要求设备上报软件信息的指令,设备端接收到该指令后,需要通过SoftwareInfo事件上报设备的软件信息

消息样式

{
  "directive": {
    "header": {
      "namespace": "System",
      "name": "ReportSoftwareInfo",
      "messageId": "e52e7a4c..."
    },
    "payload": {
    }
  }
}

payload 为空

CheckSoftwareUpdate 指令

云端下发指令,要求设备进行软件版本的检查。设备检查成功后,应该上报CheckSoftwareUpdateSucceeded事件;检查失败则上把CheckSoftwareUpdateFailed事件。

{
    "directive": {
        "header": {
            "namespace": "System",
            "name": "CheckSoftwareUpdate",
            "messageId": "xxxxx"
        },
        "payload": {}
    }
}

payload 为空

CheckSoftwareUpdateSucceeded 事件

当设备收到CheckSoftwareUpdate指令时,应该进行检查更新,当检查成功后,应该上报CheckSoftwareUpdateSucceeded事件来通知云端是否有新的更新。

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "CheckSoftwareUpdateSucceeded",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "needUpdate": true,
      "versionName": "xiaofei-1.1.1",
      "updateDescription": "这是一段更新说明"
    }
  }
}

payload 参数

参数 说明 类型 必须出现
needUpdate 是否需要更新。true为需要更新,false为不需要更新 boolean
versionName 版本号,仅用于显示。当needUpdatetrue时,该字段不可为空 string
updateDescription 升级说明,会通过应用显示、语音反馈来告知用户。该字段允许为空 string

CheckSoftwareUpdateFailed 事件

当设备收到CheckSoftwareUpdate指令时,应该进行检查更新,如果检查失败,应该上报CheckSoftwareUpdateFailed事件来通知云端。

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "CheckSoftwareUpdateFailed",
      "messageId": "e52e7a4c..."
    },
    "payload": {}
  }
}

payload 为空

UpdateSoftware 指令

小飞在线app或者通过小飞在线SDK触发设备更新时,IVS会给设备下发UpdateSoftware指令,当设备收到指令后,自行判断是否需要更新:

  • 如果有更新,进入更新流程,并上报UpdateSoftwareStarted事件,并退出IVS SDK
    • 当更新成功后,应该上报UpdateSoftwareSucceeded事件
    • 如果更新过程失败,重新连接IVS,并上报UpdateSoftwareFailed事件
  • 如果无更新,直接上报UpdateSoftwareFailed事件
  • 如果检查更新出错,上报UpdateSoftwareFailed事件
{
    "directive": {
        "header": {
            "namespace": "System",
            "name": "UpdateSoftware ",
            "messageId": "xxxxx"
        },
        "payload": {}
    }
}

payload 为空

UpdateSoftwareStarted 事件

当设备准备进入更新流程时,上报UpdateSoftwareStarted事件。无论该事件上报结果是否成功,均不应该影响更新流程。即收到UpdateSoftwareStarted响应后,设备可直接退出IVS,并开始下载更新版本。

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "UpdateSoftwareStarted",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "versionName": "xiaofei-1.1.1",
      "updateDescription": "这是一段更新说明"
    }
  }
}

payload 参数

参数 说明 类型 必须出现
versionName 版本号,仅用于应用显示。 string
updateDescription 升级说明,会通过应用显示、语音反馈来告知用户。 string

UpdateSoftwareSucceeded 事件

设备进入更新成功后,自动连接IVS,并上报UpdateSoftwareSucceeded事件。

设备更新过程,可以需要经过多次重启,才能完成最终更新。这种情况,应该在最后一次更新成功的时候,再链接IVS,并上报UpdateSoftwareSucceeded事件

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "UpdateSoftwareSucceeded",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "versionName": "xiaofei-1.1.1",
      "updateDescription": "这是一段升级后的说明"
    }
  }
}

payload 参数

参数 说明 类型 必须出现
versionName 版本号,仅用于应用显示。 string
updateDescription 升级说明,会通过应用显示、语音反馈来告知用户。 string

UpdateSoftwareFailed 事件

当设备收到UpdateSoftware指令时,在检查更新、下载更新、更新未完全完成的情况下,都应该上报UpdateSoftwareFailed事件到云端。

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "UpdateSoftwareFailed",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "error": {
        "type": "String",
        "message": "String"
      }
    }
  }
}

payload参数

参数名 说明 类型 必须出现
error 执行错误的键值对 Object
error.type 更新失败的类型,取值见下表 String
error.message 报错信息 String

错误类型

错误类型 说明
UP_TO_DATE 已是最新,不需要更新
CHECK_ERROR 检查更新出错
DOWNLOAD_ERROR 下载时软件包时出错
INSTALL_ERROR 安装更新时出错

FactoryReset 指令

小飞在线app或者小飞在线SDK触发设备恢复出厂设置,经过用户确认后,云端会下发FactoryReset指令,设备在收到该指令后,应该清除IVS SDK相关的存储数据(是否清除设备其它状态,由设备厂商设计决定),并进入设备出厂状态。

注意

无论设备是否真的成功恢复出厂iFLYOS均会将设备从用户的设备列表中移除,并清除相关的云端信息。

{
    "directive": {
        "header": {
            "namespace": "System",
            "name": "FactoryReset",
            "messageId": "xxxxx"
        },
        "payload": {}
    }
}

Reboot 指令

小飞在线app或者小飞在线SDK触发设备重启,经过用户确认后,云端下发Reboot指令,设备在收到该指令后,对自身进行重启。

{
    "directive": {
        "header": {
            "namespace": "System",
            "name": "Reboot",
            "messageId": "xxxxx"
        },
        "payload": {}
    }
}

RevokeAuthorization 指令

当用户通过小飞在线app或者小飞在线SDK解绑了设备,IVS将下发RevokeAuthorization指令,设备端收到该指令,应该清除设备端跟IVS SDK认证相关的信息,并断开IVS连接。

注意

下发该指令前,云端已将相关授权信息清除,即使设备忽略该指令不处理,本地AccessToken与RefreshToken也一样会失效,无法继续IVS的功能。

{
    "directive": {
        "header": {
            "namespace": "System",
            "name": "RevokeAuthorization",
            "messageId": "xxxxx"
        },
        "payload": {}
    }
}

ExceptionEncountered 事件

当客户端不能执行服务端下发的指令时,必须发送该事件。

消息样式

{
  "event": {
    "header": {
      "namespace": "System",
      "name": "ExceptionEncountered",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "unparsedDirective": "String",
      "error": {
        "type": "String",
        "message": "String"
      }
    }
  }
}

header参数

参数名 说明 类型
messageId 代表一条message的唯一ID String

payload参数

参数名 说明 类型 必须出现
unparsedDirective 无法执行的指令名称. 格式: namespace.name String
error 执行错误的键值对 Object
error.type 客户端不能执行指令是的错误类型
取值: UNEXPECTED_INFORMATION_RECEIVED, INTERNAL_ERROR
String
error.message 报错信息 String

错误类型

错误类型 说明
UNEXPECTED_INFORMATION_RECEIVED 指令不规范或payload不符合指令规格
INTERNAL_ERROR 执行指令过程中发生错误,并且该错误没有落到指定的类别