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 返回 “会话超时”等错误，插件会自动重新订阅。
