闹钟和提醒_v1.0

本接口定义设置/管理/取消 闹钟/提醒/计时器所用到的指令和事件。

设备要求

  1. 若已成功设置过提醒,你的设备需要能够在断开网络连接后也能够正常触发闹钟/提醒/定时器工作。
  2. 你的设备需要能够保存和维护多个闹钟/提醒/定时器。
  3. 用NTP(Network Time Protocol)来管理设备端本地的时钟
  4. 在断电/重启时,能够保存并正确执行之前设置成功的提醒/定时器

提醒控件的状态

IDLE(空闲状态): 在之前设定的提醒响起之前,提醒控件应该处于空闲状态;当一个提醒被关闭或者闹铃结束之后,提醒控件应该回到IDLE状态

FOREGROUND ALERT(前景状态) 和 BACKGROUND ALERT(背景状态): 假定已经设定了设备端提醒,当提醒开始响起并且上报了AlertStarted事件到服务端时,提醒控件应该从空闲状态进入到前景状态或背景状态。

提醒开始时,若提醒通道在前景(对话通道非活跃),则闹钟控件应该在前景状态。当提醒开始时,若对话通道活跃,闹钟控件需要从前景状态进入背景状态,当对话通道不活跃时,闹钟控件需要从背景状态进入前景状态。

当提醒被用户语音、设备按钮或GUI操作停止,提醒控件应该从前景状态进入空闲状态。

提醒状态

SetAlert指令

在用户通过语音请求设置提醒,或者通过配套APP启用提醒时,设备会收到服务端下发的该指令。当设备端在收到SetAlert指令时,应该在本地设置一个特定时间的提醒,到设定的时间能够自动触发提醒。

若payload中含有 loopCount ,客户端的循环提醒在用户通过语音指令等操作停止提醒时停止循环,或loopCount次数到时停止循环,或在提醒后1小时自动停止循环。

若云端下发了assets,提醒触发时,将播放assets音频而不是本地存储的提醒音频文件,并且assets必须按照assetPlayOrder的列表顺序进行播放。

assets.url[i]不可访问或音频文件下载失败,设备端暂时使用本地已缓存的近似的音频。

消息样例

{
  "directive": {
    "header": {
      "namespace": "Alerts",
      "name": "SetAlert",
      "messageId": "e52e7a4c...",
      "dialogRequestId": "49687be..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov...",
      "type": "TIMER",
      "scheduledTime": "2018-08-06T15:49Z",
      "assets": [
        {
          "assetId": "S0wiXQZ1rvBkovHd...",
          "url": "https://www.iflyos.cn/example....2.m4a"
        },
        {
          "assetId": "g7i2dciPYEWEigs4b...",
          "url": "https://www.iflyos.cn/example....2.m4a"
        },
      ],
      "assetPlayOrder": [             
        "S0wiXQZ1rvBkovHd...", 
        "g7i2dciPYEWEigs4b..."
        ],
      "backgroundAlertAsset": "S0wiXQZ1rvBkovHd...",
      "loopCount": 1,
      "loopPauseInMilliSeconds": 60000
    }
  }
}

Header参数

参数 说明 类型
messageId 代表一条message的唯一ID String
dialogRequestId 客户端必须为recognize请求创建的唯一ID,此参数用于关联响应特定Recognize事件发送的指令 String

Payload参数说明

参数 说明 类型 必须出现
token 需要设置的提醒的唯一token String
type 提醒类型,默认取值ALARM
可取值: TIMER(倒计时),ALARM(闹钟),REMINDER(提醒)
String
scheduledTime 触发时间,使用ISO 8601格式 String
assets 包含播放给用户的音频文件的列表 List
assets[i].assetId 每一个音频文件的唯一ID String
assets[i].url 音频文件的链接地址,客户端需要将音频文件下载并缓存下来。URL将在提醒时间后一小时失效 String
assetsPlayOrder 音频文件的播放顺序,通过assetId组成列表
提醒:
1. assetId在一个列表中可能出现多次,此时按照顺序多次播放。
2. 如果设备端未成功下载和缓存音频文件,设备端应该播放默认提醒音频。
List
backgroundAlertAsset 提醒进入BACKGROUND ALERT状态时播放的音频,此音频ID应该包含在assets列表中。如果payload中没有带这个参数,提醒进入BACKGROUND ALERT状态时播放默认的音频文件 String
loopCount assets文件被循环播放的次数
提醒:
循环直至用户主动停止循环,或循环次数到,或提醒触发时间后的1小时才失效
Long
loopPauseInMilliSeconds 两次循环之间的间隔时间。毫秒为单位。
提醒:
没有明确取值或取值为0,代表两次循环之间没有间隔(连续提醒)
Long

SetAlertSucceeded事件

设备端收到SetAlert指令时设置提醒,提醒设置成功之后,上报该事件给服务端。

消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "SetAlertSucceeded",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload参数说明

参数 说明 类型 必须出现
token 所设置的提醒的token,与SetAlert指令中的token对应 String

SetAlertFailed事件

设备端收到SetAlert指令时设置提醒,设置提醒失败时,上报该事件给服务端。

消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "SetAlertFailed",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload 参数

参数 说明 类型 必须出现
token 所设置失败的提醒的token,与SetAlert指令中的token对应 String

DeleteAlert指令

在用户通过语音请求取消/删除提醒,或者通过配套APP删除提醒时,设备会收到服务端下发的该指令。当设备端在收到DeleteAlert指令时,应该从本地删除token对应的提醒。如果该提醒正在闹铃当中,则应该先停止提醒(并上报AlertStopped事件),再删除提醒。

消息样例

{
  "directive": {
    "header": {
      "namespace": "Alerts",
      "name": "DeleteAlert",
      "messageId": "e52e7a4c...",
      "dialogRequestId": "49687be..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

参数 说明 类型
messageId 代表一条message的唯一ID String
dialogRequestId 客户端必须为recognize请求创建的唯一ID,此参数用于关联响应特定Recognize事件发送的指令 String

Payload参数说明

参数 说明 类型 必须出现
token 需要删除的提醒的token String

DeleteAlertSucceeded事件

设备端收到DeleteAlert指令后删除提醒,提醒删除成功之后,上报该事件给服务端。

消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "DeleteAlertSucceeded",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload参数说明

参数 说明 类型 必须出现
token 已删除的提醒的token String

DeleteAlertFailed事件

设备端收到DeleteAlert指令后删除提醒,删除提醒失败时,上报该事件给服务端。

消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "DeleteAlertFailed",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload参数说明

参数 说明 类型 必须出现
token 删除失败的提醒的token String

AlertStarted事件

提醒时间客户端自动触发提醒,提醒开始时上报该事件给服务端。

消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "AlertStarted",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload参数说明

参数 说明 类型 必须出现
token 已经触发的提醒的token,与SetAlert指令中的token对应 String

AlertStopped事件

触发后正在闹铃的提醒被停止时,上报该状态给服务端。有以下几种情况:

  1. 闹铃中收到DeleteAlert指令,客户端需先停止正在闹铃中的提醒,上报该状态后再删除本地提醒,并上报DeleteAlertSucceeded事件或DeleteAlertFailed事件。
  2. 用户通过设备端上按钮或者屏幕操作停止了提醒闹铃。
  3. 循环次数完成,或提醒时间到后循环了一小时,之后自动停止提醒。
  4. 端在提醒设定时间点处于断电状态,回到有电状态时已经离设定时间点超过30分钟。

消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "AlertStopped",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload参数说明

参数 说明 类型 必须出现
token 已经停止的提醒的token,与SetAlert指令中的token对应 String

AlertEnteredForeground事件

闹铃响起时提醒通道在前景(提醒音频以最大音量播放),或者在提醒音频播放当中闹钟通道重新变为前景(对话通道从活跃状态变为非活跃状态),上报该事件给服务端。

###消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "AlertEnteredForeground",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload参数说明

参数 说明 类型 必须出现
token 变化状态的提醒的token,与SetAlert指令中的token对应 String

AlertEnteredBackground事件

提醒音频播放当中,用户开始了语音请求,或者服务端下发了Speak指令,对话通道从非活跃状态进入了活跃状态,提醒通道从前景进入背景,上报该事件给服务端。

消息样例

{
  "event": {
    "header": {
      "namespace": "Alerts",
      "name": "AlertEnteredBackground",
      "messageId": "e52e7a4c..."
    },
    "payload": {
      "token": "S0wiXQZ1rVBkov..."
    }
  }
}

Header参数

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

Payload参数说明

参数 说明 类型 必须出现
token 变化状态的提醒的token,与SetAlert指令中的token对应 String