浏览器推送通知(Web Push)
启用访客浏览器通知并发送测试消息,了解授权、网站脚本和 VAPID 密钥。
本页内容
Web Push 由浏览器显示通知。访客必须先在你的小组件网站允许通知。它不同于管理页面里的铃铛和客服通知。
第 1 步:在自己的域名安装 Service Worker
请网站管理员放置 mybot-sw.js。没有它,浏览器无法接收和显示通知。Service Worker 是浏览器用于处理通知的小脚本,必须托管在你的网站;GetMyBot 域名下的脚本不能管理你的域名。带协议但不含页面路径的网站地址叫 origin,例如 https://example.com。
- 在管理页面打开小组件 → Web Push,下载
mybot-sw.js。 - 将文件放在每个使用小组件的 origin 的根目录,路径必须正好是:
Web Push 设置列出每个允许通知链接应有的地址,可直接在浏览器打开检查。https://example.com/mybot-sw.js https://shop.example.com/mybot-sw.js - 打开文件地址,确认 HTTPS 返回 JavaScript,而不是网站页面、
404或重定向。单页应用和 CDN 网站要特别检查此路径没有返回index.html。 - 平台更新后,像其他静态资源一样重新上传文件。仅修改 Web Push 设置或轮换密钥时无需重装。
路径不能改变:小组件只注册或复用 /mybot-sw.js。路由用的两个公开参数 mb_key 和 mb_api 由它自动加入,无需手填。
自行注册 Service Worker
若要自行控制注册或限制通知点击后的目的地址,可用网站代码注册:
navigator.serviceWorker.register("/mybot-sw.js?nav=https://shop.example.com");
nav 可用逗号列出最多 8 个精确 HTTPS origin。Worker 会独立按此列表及自身 origin 检查点击目的地址,不依赖服务器端允许列表。小组件发现你自行注册后会保留 nav,不会覆盖它。
网站已有自己的 Service Worker
小组件不会替换其他 Service Worker,否则可能损坏网站;通过其他 Worker 建立订阅也不会安装通知和点击处理器。如果页面已由别的 Worker 控制,订阅会显示“不可用”。可将 mybot-sw.js 放在没有其他 Worker 控制根作用域的网站,或先联系支持讨论共存方案。
第 2 步:为机器人开启 Web Push
Web Push 设置位于小组件页面,与其他网页渠道设置相邻。两个字段必填:
- VAPID 联系地址:用于推送服务报告送达问题的
mailto:地址或 HTTPS 链接,例如mailto:help@example.com。 - 允许的通知链接:每行一个 HTTPS origin。点击通知只能打开你网站上的相对路径或这些精确 origin。它是必填项;不在列表内的链接在发送前会被拒绝。
首次保存时服务器生成 VAPID 密钥对。设置中只显示供浏览器使用的公钥;私钥永不离开服务器,也不会由 API 返回。静默时段可通过 API 设置,但这个页面目前没有对应字段。
第 3 步:取得访客同意
访客必须自行允许通知,单纯加载页面不会订阅:
- 浏览器授权请求只在访客明确点击小组件的通知按钮后出现。
- 从未点击的人不会看到错误;浏览器不支持推送或权限已被拒绝时,首次尝试前按钮会隐藏。
- 加载小组件只会更新已有同意,不会弹出授权、安装 Worker 或创建新订阅。
- 拒绝会长期保留,刷新页面也不消失,即使浏览器仍保留订阅对象。
小组件加载后,网站代码也可调用:
await window.mybot.push.subscribe(); // 请求许可并注册订阅
await window.mybot.push.unsubscribe(); // 在服务器撤销并取消浏览器订阅
订阅状态为 subscribed(有效)、revoked(访客退订)、expired(送达地址不再有效)。管理页面和 API 可见浏览器类型、语言、时区、状态及日期。送达地址和加密密钥在服务器加密保存,写入后不会向所有者展示,也不会通过 API 或 MCP 返回。
发送
测试通知会发送到最近订阅的一个浏览器,必须同时满足:机器人已启用 Web Push、至少一个 subscribed 订阅、以及在内容工作台有一份已发布的 Push 文档。测试发送引用具体的已发布版本,与弹窗或活动相同。
启动后管理页面立即得到消息编号,实际送达在后台继续。受众选择、定时和停止发送目前没有界面。
通知内容限制
违反任何限制,服务器会拒绝整个发送,不会截断内容。
| 字段 | 限制 |
|---|---|
title | 必填,1–120 字符 |
body | 必填,1–512 字符 |
tag | 可选,不超过 128 字符 |
actions | 最多 2 个;每个动作 ID 和标题各 1–64 字符,不能重复 |
icon_url、image_url | 仅 HTTPS,不能包含 userinfo 或锚点 |
navigation | 以 / 开头的相对路径,或一个精确允许的 origin |
data | 只能有 action、campaign_id、content_id、experiment_id、message_id,每值不超过 256 字符 |
| 完整载荷 | 最多 3 KiB |
data 中若包含 bearer 、secret、password、token= 或 @ 会被拒绝,以免在通知中传递资料值或令牌。自带 receipt_signature 也会被拒绝;该内部值在送达时由服务器填入。服务器和 Worker 均将 //host/path 和含反斜杠的链接视为外部 origin,而非相对路径。
静默时段
静默时段是重复出现的本地时间区间,其间的送达会推迟而非取消,消息将在下一个允许的时间发出。使用订阅时记录的收件人时区,没有时使用机器人时区。结束时间早于开始表示跨午夜;落在夏令时切换“缺失时段”的时间会顺延到实际存在的时刻。设置属于 Web Push 配置,可通过 REST 的 quiet_hours 字段调整,目前管理页面没有编辑器。
送达、重试与回执
- 后台处理器领取消息并在送达期间持有租约,最多尝试 8 次或持续 24 小时,以先达到者为准。
- 推送服务返回
429时按其Retry-After重试,最多等待 24 小时;超时和5xx使用带随机抖动的延迟重试;其他4xx为最终失败。 404或410表示浏览器订阅失效,会标记为expired,不再重试。- Worker 在访客点击和关闭通知时分别发送
click、close回执。回执已签名且绑定单条消息及订阅,不能伪造或挪用于其他消息。 - 设置页面报告按状态统计订阅及通知打开次数。内部记录
accepted、sent、failed、expired、clicked、closed,也进入用户中的客户事件列表。
失败送达只保存封闭列表中的原因代码,不保存推送服务的响应正文。
轮换 VAPID 密钥
更换 VAPID 密钥会让全部现有订阅失效,因此管理页面会显示受影响浏览器数并要求确认。技术上首次请求返回 409 和活跃订阅数;确认后生成新密钥对,旧订阅失效。每位访客都须重新允许通知,因为浏览器订阅绑定旧密钥。小组件在访客下次明确同意时会丢弃旧密钥订阅并重建,不会长期保留无效订阅。
安全边界
- MyBot 只向端口 443 的公开 HTTPS 地址发送。Loopback、私有、link-local、multicast 和 CGNAT 地址会被拒绝;域名解析出多个地址时,全部都必须公开。
- 每次送达都重新解析并检查域名,只连接通过检查的地址;不跟随重定向,并限制响应大小。
- 订阅地址在账户范围内按指纹去重,因此一个机器人无法探知浏览器是否订阅另一个机器人。
- 浏览器路由不属于
/api,而属于小组件信任域;每次都检查签名小组件密钥、小组件会话和页面的精确 origin,并使用小组件的共同限流。
数据与保留
浏览器订阅和消息归入 push 数据保留类别,默认保存 180 天。它们与其他客户数据一样参与订阅者合并、个人数据导出和删除。
浏览器支持与排查
浏览器须同时支持通知、Service Worker 和 Push API。当前桌面及 Android 的 Chrome、Edge、Firefox 可用;iOS Safari 只为访客添加到主屏幕的网站提供 Web Push。
收不到消息时:
- 在浏览器打开
https://你的网站/mybot-sw.js,确认返回脚本而非404、重定向或 HTML 页面。 - 核对页面 origin 已列入小组件允许列表,通知链接也在允许范围内。
- 确认访客浏览器确实授权,且页面没有被其他 Service Worker 控制。
- 密钥轮换后,所有人都需要重新订阅。
- 测试发送不可用时,检查是否有已订阅浏览器和已发布的 Push 文档。
API 与 MCP
个人令牌可访问管理路由,见 REST API。读取需要 web_push:read 作用域和机器人的 web_push.read 权限;写入需要 web_push:write 和 web_push.write,启用还需要 integrations.secrets。MCP 提供四个只读工具,包括订阅列表,见 MCP。