# 本地闹钟
消息类型 | 名称 | 必须实现 |
---|---|---|
response | set_alarm | 否 |
delete_alarm | 否 | |
request | state_sync | 否 |
# 选择闹钟实现方式
TIP
- iFLYOS 系统提供两种闹钟能力,云端闹钟和本地闹钟只能二选一。为了降低设备开发成本,iFLYOS 建议你使用云端闹钟。
- 为了更好的用用户体验,我们约定,无论实现设备闹钟还是本地闹钟,在闹钟响起后,设备均应该在语音唤醒或按键操作之后停止闹钟。
- 纯软件项目无需实现闹钟能力(无论云端闹钟还是设备闹钟)。
# 云端闹钟
在请求时,context中不包含alarm
对象,则代表设备使用云端闹钟。用户设置闹钟后,云端会记住用户的闹钟列表,当闹钟时间到时,你的设备会收到如下iflyos_response
:
# 闹钟时间到
{
"iflyos_responses": [
...,
{
"header": {
"name": "audio_player.audio_out"
},
"payload": {
"type": "RING",
"url": "https://music.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",
"resource_id": "e52e7xxxxxxxxxxxe52e7"
}
}
]
}
收到该iflyos_response
后,设备使用 RING 通道的播放器播放闹钟铃音即可。
# 更新云端闹钟列表
在闹钟列表发生变更后(可能是因为闹钟响铃、用户通过语音或关联APP增删查改闹钟),云端会下发以下指令。
{
"iflyos_responses": [
...,
{
"header": {
"name": "system.update_cloud_alarm_list"
},
"payload": {
}
}
]
}
在收到指令后,若你的设备本地需要显示闹钟列表,我们建议你立即调用GET /alerts,更新闹钟列表中的数据。
# 本地闹钟
在请求时,context中包含alarm
对象,则代表设备使用本地闹钟。如果你想在设备本地保存闹钟列表,需要实现alarm
类iflyos_response
。
在此之前你需要考虑以下几个问题:
- 实现本地闹钟需要设备本地做闹钟列表持久化保存,不能因为设备重启等原因造成设备闹钟列表丢失。(这样会造成设备开发的复杂度提升)
- 实现本地闹钟需要保证设备本地时间正确。iFLYOS 在接入大量厂商时发现很多芯片的时间钟不稳定,我们建议使用
system.ping
来保证你的设备系统时间是准确的。(这样会造成设备开发的复杂度提升) - 实现本地闹钟需要在设备本地对设备闹钟进行一定的容错处理。(这样会造成设备开发的复杂度提升)
如果选择了客户端闹钟,请按照本篇的内容,完成本地闹钟的实现和处理。
注意
闹钟的设置、修改、删除和响铃,都必须使用状态同步(system.state_sync
)来告知云端;
# context
"iflyos_context": {
...
"alarm": {
"version": "1.0",
"local": [
{
"alarm_id": "xxxxx",
"timestamp": 1558598737
}
],
"active": {
"alarm_id": "xxxxx"
}
},
...
}
参数 | 类型 | 说明 | 必填 |
---|---|---|---|
version | String | 模块版本,现在是1.1 | 是 |
local | List | 设备本地闹钟列表,如果没有,请传输空数组 | 是 |
local.alarm_id | String | 设备闹钟的唯一标识 | 是 |
local.timestamp | Long | unix时间戳 | 是 |
active | Object | 正在活动的闹钟 | 否 |
active.alarm_id | String | 设备闹钟的唯一标识 | 是 |
版本说明
版本 | 说明 | 更新日期 |
---|---|---|
1.0 | 基础实现 | 2019-07-01 |
# response
# 设置闹钟
在设备发起recognize
请求或状态同步之后,可能会得到一个闹钟response
。在收到这个iflyos_response
之后,你需要根据信息在设备本地记录和设置闹钟。
回复示例
{
"iflyos_responses": [
...,
{
"header": {
"name": "alarm.set_alarm"
},
"payload": {
"alarm_id": "xxxxx",
"timestamp": 1558598737,
"url": "https://www.iflyos.cn/example....2.m4a"
}
}
]
}
参数 | 类型 | 说明 | 必有 |
---|---|---|---|
alarm_id | String | 闹钟ID | 是 |
timestamp | Long | 响铃时间的 unix 时间戳 | 是 |
url | String | 铃声地址 | 是 |
# 删除闹钟
在设备发起recognize
请求或状态同步之后,可能会得到一个闹钟response
。在收到这个iflyos_response
之后,你需要根据信息在设备本地记录中删除对应alarm_id
的闹钟。
回复示例
{
"iflyos_responses": [
...,
{
"header": {
"name": "alarm.delete_alarm"
},
"payload": {
"alarm_id": "xxxxx",
}
}
]
}
参数 | 类型 | 说明 | 必有 |
---|---|---|---|
alarm_id | String | 闹钟ID | 是 |
# request
# 状态同步
当本地闹钟时间到时,你需要在闹钟开始响和结束响的时候发送request
至 iFLYOS 云端
请求示例
{
"iflyos_header": {...},
"iflyos_context": {...},
"iflyos_request": {
"header": {
"name": "alarm.state_sync",
"request_id": "xxxxxxxx"
},
"payload": {
"type": "STARTED",
"alarm_id": "xxxxx"
}
}
}
参数 | 类型 | 说明 | 必填 |
---|---|---|---|
iflyos_header | Object | 构建的通用 iflyos_header | 是 |
iflyos_context | Object | 构建的通用 iflyos_context | 是 |
type | String | 状态类型,取值: - STARTED:alarm开始响铃 - STOPPED:alarm响铃停止,无论是自然响铃完成还是用户操作(唤醒或按键)停止了闹钟,均发送该请求。 | 是 |
alarm_id | String | 该状态对应的闹钟ID | 是 |