Web SDK 集成指南
本文是 MTpush Web SDK 标准的集成指南文档。
各通道海外用户支持说明
| 通道类型 | 其他地区用户 | 中国大陆用户 | 说明 |
|---|---|---|---|
| EngageLab通道 | 支持触达 | 支持触达 | SDK默认支持 |
| W3C通道 | 支持触达 | 支持触达 | / |
快速测试
集成前准备
- 准备一个能访问的 https web 服务域名,集成后的页面需在该域名下进行测试与调试。web 离线推送不支持本地调试、不支持 http。
- 访问 Engagelab WebPush,在【集成设定】-【 网站域名】页面,填写 https web 服务域名。

产品说明
Web SDK 为 web 应用提供一个基于各个浏览器内核通知和 websocket 的推送开发框架,对外提供较为简洁的 API 接口,方便第三方应用快速集成推送功能。浏览器内核通知支持 Edge、Chrome、 Safari 、Firefox 、Opera 等主流浏览器,websocket 支持绝大部分主流浏览器。
EngageLab WebPush服务支持PWA推送,您需要使用EngageLab WebPush提供的Web SDK将Web Push功能集成到您的PWA应用程序中,并按照文档中提供的示例代码来注册Service Worker并初始化Web Push功能。一旦集成完成,您就可以使用EngageLab WebPush的API来向您的PWA应用程序用户发送推送通知了。 具体参见文档说明
主要场景:
通知推送消息,自定义推送消息。
jpush-p-web-example.zip 集成压缩包内容
- example
- 是一个 web 页面,通过这个演示了 MTpush SDK 的基本用法,可以用来做参考。
获取应用信息
在控制台上创建应用,创建成功后自动生成 AppKey 用以标识该应用,详情参考 应用设置文档。
SDK 接入
进入 控制台,下载 SDK,在每个页面接入 js:
请使用控制台下载的最新 Web SDK 及随包提供的 Service Worker 文件。SDK 从 2.1.7 起支持按 AppKey 自动适配数据中心;下例中的 webPushSdk.min.<version>.js 是文件名占位符,请替换为下载包中的实际文件名。
SDK 根据 AppKey 自动获取所属数据中心的连接地址和统计上报地址,包括德国法兰克福和美国弗吉尼亚,无需手动设置 baseUrl、report_url 或 webSocketUrl。
<script type="text/javascript" src="./webPushSdk.min.<version>.js"></script>
tips
随包包含sw.xxx.js该文件是service worker文件,用于接收消息。
SDK默认会从根目下加载该文件。
service worker 最大的作用域是worker所在位置,(按句话说,如果脚本sw.js位于/js/sw.js中,默认情况下它只能控制/js/下的url)。
所以请尽可能使用默认配置,放在网站根目录。
如果有特殊情况,存放在第三方cdn,请在服务端使用 Service-Worker-Allowed 标头指定 worker的最大作用域。
引入该 js 后,就可以使用 Window 上的全局对象 MTpushInterface。
终端时区上报
从 Web SDK v3.3.10 起,SDK 会在初始化时上报终端时区信息,供 EngageLab 按用户所在地正确处理夏令时与冬令时。
- SDK 会通过浏览器的
Intl.DateTimeFormat().resolvedOptions().timeZone自动读取 IANA 时区 ID,并在oversea_info上报中携带time_zone_id,例如America/New_York、Asia/Shanghai或UTC。 - 原有的数字时区字段
time_zone会继续上报,保持与旧版本及既有服务端逻辑兼容。 - 此能力不需要在
MTpushInterface.init中新增配置,也不需要业务侧手动传入时区。 - 如果浏览器不支持读取 IANA 时区 ID,或返回的 ID 不可用,SDK 会自动省略
time_zone_id,但仍会按原有逻辑上报time_zone,不会影响推送初始化和使用。
建议升级至 v3.3.10 或更高版本。对于采用夏令时的地区,IANA 时区 ID 可以帮助平台根据事件发生时刻识别正确的 UTC 偏移量;例如
America/New_York会在夏令时与冬令时之间自动切换。
SDK 初始化
生成 user_str
建议使用浏览器指纹生成唯一 user_str,防止无效用户注册:
// 略:Canvas、WebGL、插件指纹采集代码(保持不变)
const visitorId = getFingerprint();
console.log('user_str', visitorId);
示例代码
// 请在初始化前注册事件监听
// 极光通道断开连接时的回调
MTpushInterface.mtPush.onDisconnect(function () {
console.log("onDisconnect");
});
// 得到推送消息(Web 推送、浏览器厂商通道)
MTpushInterface.onMsgReceive((msgData) => {
// msgData 数据结构:{ data: { xxx }, type: 0 },type: 0 是极光通道,1 是系统通道
console.log("得到推送消息:", msgData);
});
function initWebPush() {
const appkey = "your_appkey";
const userStr = visitorId;
if (!(appkey && userStr)) {
console.log("appkey 与 user_str 都不能为空");
return;
}
// 推送初始化
MTpushInterface.init({
appkey: appkey,
user_str: userStr,
fail(err) {
console.log("在线推送创建失败", err);
},
success(data) {
console.log("在线推送创建成功", data);
},
webPushcallback(code, tip) {
console.log("状态码及提示", code, tip);
},
canGetInfo(data) {
// 此时可以得到 RegId,也可以在 data 中取得初始化配置数据
console.log("初始化配置", data);
console.log("得到 RegId", MTpushInterface.getRegistrationID());
},
custom: (requestPermission) => {
// 使用自定义提示配置时,在合适的用户操作时机调用 requestPermission 请求通知权限
document.getElementById("subscribe")?.addEventListener("click", () => {
if (Notification.permission === "default") {
requestPermission();
} else if (Notification.permission === "denied") {
console.log("通知权限已禁用,无法申请权限");
} else {
console.log("已有通知权限,无需重复申请");
}
});
},
});
}
initWebPush();
更多 API
其他 API 的使用方法请参考接口文档:Web SDK API。










