瀏覽器推播(Web Push)
讓訪客在瀏覽器接收通知並測試發送:權限、網站檔案與 VAPID 金鑰。
本頁內容
Web Push 透過瀏覽器顯示通知。網站聊天小工具的訪客必須先允許通知。它與後台的鈴鐺或客服通知是不同功能。
步驟 1:在你的網域安裝 service worker
請網站管理員放置 mybot-sw.js,否則瀏覽器無法接收和顯示通知。
Service worker 是瀏覽器接收通知的小型指令碼,必須位於你的網站;GetMyBot 網域的指令碼無法控制你網域的通知。含協定、不含頁面路徑的網站位址稱為 origin,例如 https://example.com。
-
在後台開啟**「聊天小工具 → Web Push」**,下載
mybot-sw.js。 -
將檔案放在每個使用小工具的 origin 根目錄,路徑須完全相同:
https://example.com/mybot-sw.js https://shop.example.com/mybot-sw.jsWeb Push 設定會列出每個允許的通知連結所需的檔案位址,可直接開啟檢查。
-
在瀏覽器開啟檔案,應透過 HTTPS 回傳 JavaScript,不應是網站頁面、
404或重新導向。SPA 或 CDN 網站尤其要確認此路徑沒有回傳index.html。 -
平台更新後,像更新其他靜態檔案一樣重新上傳。修改 Web Push 設定或輪替金鑰時不用重裝。
路徑必須是 /mybot-sw.js,小工具只註冊或沿用此路徑的 worker。mb_key 和 mb_api 兩個公開路由參數會自動加入,無須手動設定。
自行註冊 worker
若需自行控制註冊,或限制通知點擊可開啟的位址,可用網站程式碼註冊:
navigator.serviceWorker.register("/mybot-sw.js?nav=https://shop.example.com");
nav 可用逗號列出最多 8 個完全相符的 HTTPS origin。Worker 會獨立依自己的清單與自身 origin 檢查點擊目標,不依賴步驟 2 的伺服器清單。小工具發現這類註冊後,會保留你的 nav 值,不會覆蓋。
網站已有其他 service worker
小工具永遠不會取代其他 worker,因為那可能破壞網站,而沿用其他 worker 也沒有必要的推播與點擊處理器。若頁面已受另一 worker 控制,訂閱會顯示「不可用」。請在根範圍沒有其他 worker 的網站放置 mybot-sw.js,或先聯絡支援討論整合。
步驟 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 文件。
測試固定引用該文件的已發佈版本,與彈出視窗或活動相同。啟動後,後台立即取得訊息 ID,送達在背景完成。目前所有畫面都沒有受眾選擇、排程或停止發送功能。
通知內容限制
任一限制不符,伺服器會整份拒絕,不會截斷:
| 欄位 | 限制 |
|---|---|
title | 必填,1–120 字元 |
body | 必填,1–512 字元 |
tag | 可選,最多 128 字元 |
actions | 最多 2 個;每個識別碼和標籤 1–64 字元,不得重複 |
icon_url、image_url | 僅 HTTPS,不可含 userinfo 或錨點 |
navigation | 以 / 開頭的相對路徑,或完全相符的允許 origin |
data | 只能用 action、campaign_id、content_id、experiment_id、message_id;每值最多 256 字元 |
| 完整 payload | 最多 3 KiB |
data 值若含 bearer 、secret、password、token= 或 @ 會被拒絕,避免把客戶資料或權杖放進通知。自帶 receipt_signature 的 payload 也會被拒絕,此服務欄位由伺服器送達時填入。
伺服器和 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。