# 闹钟和提醒_v1.0

设备要求
提醒控件的状态
SetAlert指令
- 消息样例
SetAlertSucceeded事件
- 消息样例
SetAlertFailed事件
- 消息样例
DeleteAlert指令
- 消息样例
DeleteAlertSucceeded事件
- 消息样例
DeleteAlertFailed事件
- 消息样例
AlertStarted事件
- 消息样例
AlertStopped事件
- 消息样例
AlertEnteredForeground事件
AlertEnteredBackground事件
- 消息样例

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

# 设备要求

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

# 提醒控件的状态

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
    }
  }
}

参数	说明	类型
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..."
    }
  }
}

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

# Payload参数说明

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

# SetAlertFailed事件

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

# 消息样例

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

参数	说明	类型
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..."
    }
  }
}

参数	说明	类型
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..."
    }
  }
}

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

# Payload参数说明

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

# DeleteAlertFailed事件

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

# 消息样例

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

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

# Payload参数说明

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

# AlertStarted事件

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

# 消息样例

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

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

# Payload参数说明

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

# AlertStopped事件

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

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

# 消息样例

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

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

# Payload参数说明

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

# AlertEnteredForeground事件

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

###消息样例

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

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

# Payload参数说明

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

# AlertEnteredBackground事件

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

# 消息样例

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

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

# Payload参数说明

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

← 扬声器_v1.0 音频播放器_v1.1 →

# 闹钟和提醒_v1.0

# 设备要求

# 提醒控件的状态

# SetAlert指令

# 消息样例

# Header参数

# Payload参数说明

# SetAlertSucceeded事件

# 消息样例

# Header参数

# Payload参数说明

# SetAlertFailed事件

# 消息样例

# Header参数

# Payload 参数

# DeleteAlert指令

# 消息样例

# Header参数

# Payload参数说明

# DeleteAlertSucceeded事件

# 消息样例

# Header参数

# Payload参数说明

# DeleteAlertFailed事件

# 消息样例

# Header参数

# Payload参数说明

# AlertStarted事件

# 消息样例

# Header参数

# Payload参数说明

# AlertStopped事件

# 消息样例

# Header参数

# Payload参数说明

# AlertEnteredForeground事件

# Header参数

# Payload参数说明

# AlertEnteredBackground事件

# 消息样例

# Header参数

# Payload参数说明