GetMyBot 知識庫

瀏覽器推播(Web Push)

讓訪客在瀏覽器接收通知並測試發送:權限、網站檔案與 VAPID 金鑰。

本頁內容

Web Push 透過瀏覽器顯示通知。網站聊天小工具的訪客必須先允許通知。它與後台的鈴鐺或客服通知是不同功能。

步驟 1:在你的網域安裝 service worker

請網站管理員放置 mybot-sw.js,否則瀏覽器無法接收和顯示通知。

Service worker 是瀏覽器接收通知的小型指令碼,必須位於你的網站;GetMyBot 網域的指令碼無法控制你網域的通知。含協定、不含頁面路徑的網站位址稱為 origin,例如 https://example.com。

  1. 在後台開啟**「聊天小工具 → Web Push」**,下載 mybot-sw.js。

  2. 將檔案放在每個使用小工具的 origin 根目錄,路徑須完全相同:

    https://example.com/mybot-sw.js
    https://shop.example.com/mybot-sw.js
    

    Web Push 設定會列出每個允許的通知連結所需的檔案位址,可直接開啟檢查。

  3. 在瀏覽器開啟檔案,應透過 HTTPS 回傳 JavaScript,不應是網站頁面、404 或重新導向。SPA 或 CDN 網站尤其要確認此路徑沒有回傳 index.html。

  4. 平台更新後,像更新其他靜態檔案一樣重新上傳。修改 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。

若收不到通知:

  1. 在瀏覽器開啟 https://你的網站/mybot-sw.js,確認回傳的是指令碼,不是 404、重新導向或 HTML。
  2. 確認頁面 origin 在小工具允許清單中,通知連結也符合允許網址。
  3. 確認訪客瀏覽器已授予權限,且頁面不受其他 service worker 控制。
  4. 金鑰輪替後所有人都需重新訂閱。
  5. 無法測試發送時,檢查是否缺少已訂閱瀏覽器或已發佈的 Push 文件。

API 與 MCP

個人權杖可呼叫管理路由,見 REST API。讀取需要 web_push:read 範圍與機器人的 web_push.read 權限;寫入需要 web_push:write 和 web_push.write,啟用還需要 integrations.secrets。MCP 提供四個唯讀工具,包括訂閱清單,見 MCP。

下一步