Web SDK Chrome 插件版本集成指南（適用於 V3）
說明：本文為 MTpush Web SDK 在 Chrome 插件（Manifest V3） 環境下的標準集成指南，僅適用於支援 V3 插件架構的瀏覽器版本。
一、產品介紹
MTpush Web SDK - Chrome 插件版本 是專為基於 Chrome 插件（Manifest V3）開發者設計的推播集成工具。它利用 Chrome 瀏覽器的系統通知能力和 Service Worker 持久連接機制，為插件提供穩定、高效的推播服務。
該 SDK 僅支援 Chrome 瀏覽器及兼容 Chromium 內核的瀏覽器（如 Edge Chromium），並依賴瀏覽器的插件運行環境。無需用戶額外授權，插件初始化後即可接收推播通知。
📦 主要特性
- 系統級通知：直接通過瀏覽器通知中心展示推播訊息
- 插件級集成：適配 Chrome 插件架構，自動訂閱，用戶無感知
- 輕量接入：統一 API，快速初始化與訊息接收
- 支援自定義訊息：支援 tag、alias 等方式靈活篩選目標用戶
📌 適用場景
- 向插件用戶推播提醒、營銷、更新等通知
- 即時傳達用戶關心的資訊，如物流狀態、活動訊息等
- 構建具備訊息能力的瀏覽器工具類插件
二、SDK 壓縮包內容
webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│ ├── webSdkExtension.min.x.x.x.js // 主 SDK 檔案
│ ├── swExtension.min.x.x.x.js // Service Worker 檔案
│ └── push-demo // Chrome 插件示例專案
webPushSdk.min.x.x.x-release.zip
├── chrome-extension
│ ├── webSdkExtension.min.x.x.x.js // 主 SDK 檔案
│ ├── swExtension.min.x.x.x.js // Service Worker 檔案
│ └── push-demo // Chrome 插件示例專案
此代碼塊在浮窗中顯示
三、集成過程
1. 獲取應用資訊
在 EngageLab 控制台新建應用，創建成功後系統將自動生成 AppKey，用以標識該應用。 詳見：應用設置文檔
2. 集成插件 ID
- 獲取你的 Chrome 插件的擴展 ID；
- 登錄 EngageLab WebPush 控制台，進入【集成設置】-【Chrome 插件集成】，填寫插件名稱與擴展 ID。
示意圖：
3. SDK 接入
步驟一：下載 SDK 並配置插件
在 manifest.json 中配置如下：
{
"manifest_version": 3,
"permissions": [
"storage",
"notifications",
"tabs",
"activeTab"
],
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["webSdkExtension.min.x.x.x.js"],
"run_at": "document_end"
},
{
"matches": ["<all_urls>"],
"js": ["init-sdk.js"],
"run_at": "document_end"
}
],
"background": {
"service_worker": "swExtension.min.x.x.x.js"
}
}
{
"manifest_version": 3,
"permissions": [
"storage",
"notifications",
"tabs",
"activeTab"
],
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["webSdkExtension.min.x.x.x.js"],
"run_at": "document_end"
},
{
"matches": ["<all_urls>"],
"js": ["init-sdk.js"],
"run_at": "document_end"
}
],
"background": {
"service_worker": "swExtension.min.x.x.x.js"
}
}
此代碼塊在浮窗中顯示
引入
webSdkExtension.min.x.x.x.js後，可通過window.MTpushInterfaceExtension調用 SDK 方法。
步驟二：生成 user_str
建議使用瀏覽器指紋生成唯一 user_str，防止無效用戶註冊：
// 略：Canvas、WebGL、插件指紋採集代碼（保持不變）
const visitorId = getFingerprint();
console.log('user_str', visitorId);
// 略：Canvas、WebGL、插件指紋採集代碼（保持不變）
const visitorId = getFingerprint();
console.log('user_str', visitorId);
此代碼塊在浮窗中顯示
步驟三：初始化 SDK
if (window.MTpushInterfaceExtension) {
window.MTpushInterfaceExtension.initSdk({
appkey: '', // 控制台生成的 AppKey
user_str: '', // 瀏覽器指紋或登錄用戶唯一標識
});
}
chrome.runtime.onMessage.addListener((message) => {
switch (message.type) {
case 'MTPUSH_INIT_SDK_SUCCESS':
console.log('初始化SDK成功：', message.data);
break;
case 'MTPUSH_INIT_SDK_FAIL':
console.log('初始化SDK失敗：', message.data);
break;
case 'MTPUSH_ON_MSG_RECEIVE':
console.log('收到推播訊息:', message.data);
break;
}
});
if (window.MTpushInterfaceExtension) {
window.MTpushInterfaceExtension.initSdk({
appkey: '', // 控制台生成的 AppKey
user_str: '', // 瀏覽器指紋或登錄用戶唯一標識
});
}
chrome.runtime.onMessage.addListener((message) => {
switch (message.type) {
case 'MTPUSH_INIT_SDK_SUCCESS':
console.log('初始化SDK成功：', message.data);
break;
case 'MTPUSH_INIT_SDK_FAIL':
console.log('初始化SDK失敗：', message.data);
break;
case 'MTPUSH_ON_MSG_RECEIVE':
console.log('收到推播訊息:', message.data);
break;
}
});
此代碼塊在浮窗中顯示
MTPUSH_ON_MSG_RECEIVE會在收到推播訊息時觸發，僅對以下頁面生效：
- 安裝插件（或重啟插件）後新打開的頁面；
- 當前處於前台可見狀態的頁面。
四、注意事項
- SDK 初始化需在「安裝插件後新打開」的頁面中執行，舊頁面無法建立連接。
- 插件被禁用或刪除，將無法接收任何推播。
- 插件啟用或重載後，需重新打開任意頁面進行初始化訂閱。
- 同一瀏覽器中，即便使用相同 AppKey，不同插件或
user_str會被視為不同用戶。 - 插件無需用戶授權通知權限，初始化成功後將自動訂閱系統通知。
五、更多 API
更多 SDK 接口使用方式，詳見官方文檔：Web SDK API
六、運行 Demo 示例
壓縮包內附帶 Chrome 插件示例專案 push-demo，可用於快速測試推播功能：
- 替換
lib目錄為最新 SDK； - 在
init-sdk.js中配置正確的appkey和user_str； - 打開
chrome://extensions，開啟開發者模式，導入解壓後的 demo； - 隨便打開任意網頁，完成初始化訂閱流程；
- 登錄 EngageLab 控制台，推播測試訊息；
- 網頁右下角點擊 Push 圖標，可查看
regid、推播記錄，並設置 tags/alias； - 若 Chrome 返回「會話超時」等錯誤，插件會自動重新訂閱。
