跳到正文

操作按钮 ​

一条通知最多可以带三个按钮。无需先读完提醒再打开电脑处理,直接在锁屏上操作即可:打开运行记录、触发重启、复制验证码。

三种类型 ​

类型按钮的作用value 的内容
view打开 URLURL,例如 https://status.example.com
http在后台发送 HTTP 请求JSON 字符串:{"url":"…","method":"POST","headers":{…},"body":"…"}
copy将文本复制到剪贴板要复制的原始文本

对于 http,只有 url 是必填项,method 默认为 GET。当存在 body 且未设置内容类型时,会自动添加 Content-Type: application/json。

http 和 copy 无需打开应用即可运行,即使应用已关闭也一样。view 会将应用或浏览器切换到前台。

按钮显示的位置 ​

无论应用处于前台、后台还是已关闭,按钮都会显示在 iOS 和 Android 的系统通知中,同时也会保留在消息本身里。后者很重要:即使把横幅划走,之后打开这条消息时按钮依然可用。

  • 按钮标签在两个平台上都会按你发送的内容原样显示。如果 iOS 无法及时准备自定义按钮,会回退为每种类型的通用标签,即 打开、运行、复制,按钮功能不受影响。
  • 锁屏。 http 和 copy 无需解锁即可在锁屏上运行。view 会打开应用或浏览器,因此手机会先要求解锁。在 Android 上,只有锁屏设置为显示通知内容时,按钮才会出现在锁屏上。
  • 请求失败。 如果 http 请求失败(状态码非 2xx/3xx 或网络错误),会弹出一条带 重试 按钮的通知。可能已经到达你服务器的请求,不会被自动重试。
  • 应用版本。 系统通知按钮需要 Pocket Alert 应用 2.0.1 或更高版本。较旧的版本只会在消息内部显示按钮。

审批流程 ​

两个 http 按钮 批准 和 拒绝,可以把一条通知变成一键操作面板。这种模式适用于任何需要等待人工确认的场景:

  • 等待人工审批的部署流水线
  • 在花钱或修改生产环境之前需要确认的 LLM 代理
  • 超过某个金额的退款
  • 门、闸机、灯、车库门

请求直接从手机发送到你的端点。Pocket Alert 不会代理该请求,也不会读取响应正文。

幂等性由你负责

连续点击同一个 http 按钮两次,就会发送两次请求,我们不会拦截重复操作。如果重复触发代价很高,请让端点具备幂等性。

来自 Webhook 的按钮 ​

Webhook 可以携带操作模板,其中的 %path% 占位符会从传入的载荷中取值填充。例如,Sentry 告警可以附带一个指向具体问题的 查看问题 按钮;Stripe 事件则可以附带一个指向对应收款的 查看付款 按钮。

替换后的值会先进行 JSON 转义,再解析模板,因此载荷字段中即使包含引号,也无法跳出并改写 URL。如果某个按钮解析结果无效,例如告警中没有 runbook URL 却出现了 Runbook 按钮,则只丢弃该按钮,其余按钮和消息照常送达。出错的按钮绝不会导致告警丢失。

创建或编辑 Webhook 时,可以在控制台中设置模板,也可以通过 Webhook API 设置。

限制与验证 ​

  • 每条消息最多 3 个按钮,按发送顺序显示。
  • actions 数组经 JSON 编码后最多 2048 字节。它随推送一同发送,而推送上限为 4 KB,因此过长的 message 会被截短以腾出空间。
  • view 和 http 需要有效的 http(s) URL。其他情况在 API 中返回 400;在 Webhook 模板中则会丢弃无效按钮。
  • 未知的 type 值返回 400。

付费功能

免费套餐的消息会在服务端去除操作按钮,消息本身仍会正常送达。

相关链接 ​

Pocket Alert 文档