# 系统_v1.1

版本修改
SynchronizeState 事件
- 消息样式
UserInactivityReport 事件
- 消息样式
ResetUserInactivity 指令
- 消息样式
SoftwareInfo 事件
- 消息样式
ReportSoftwareInfo 指令
- 消息样式
CheckSoftwareUpdate 指令
CheckSoftwareUpdateSucceeded 事件
CheckSoftwareUpdateFailed 事件
UpdateSoftware 指令
UpdateSoftwareStarted 事件
UpdateSoftwareSucceeded 事件
UpdateSoftwareFailed 事件
FactoryReset 指令
Reboot 指令
RevokeAuthorization 指令
ExceptionEncountered 事件
- 消息样式

# 版本修改

版本	新增
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	版本号，仅用于显示。当`needUpdate`为`true`时，该字段不可为空	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事件。

TIP

设备更新过程，可以需要经过多次重启，才能完成最终更新。这种情况，应该在最后一次更新成功的时候，再链接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	执行指令过程中发生错误，并且该错误没有落到指定的类别

← 云端配置_v1.0 设置_v1.0 →