Web SDK 集成指南
本文是 MTpush Web SDK 標準的集成指南文檔。
快速測試
集成前準備
- 準備一個能訪問的 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：
<script type="text/javascript" src="./webPushSdk.min.2.1.2.js"></script>
<script type="text/javascript" src="./webPushSdk.min.2.1.2.js"></script>
此代碼塊在浮窗中顯示
引入該 js 後，就可以使用 Window 上的全局對象 MTpushInterface。
tips
隨包包含sw.xxx.js該文件是service worker文件，用於接收訊息。
SDK預設會從根目下載入該檔案。
service worker 最大的作用域是worker所在位置，（按句話說，如果腳本sw.js位於/js/sw.js中，預設情況下它只能控制/js/下的url）。
所以請盡可能使用預設配置，放在網站根目錄。
如果有特殊情況，存放在第三方cdn，請在服務端使用 Service-Worker-Allowed 標頭指定 worker的最大作用域。
隨包包含sw.xxx.js該文件是service worker文件，用於接收訊息。
SDK預設會從根目下載入該檔案。
service worker 最大的作用域是worker所在位置，（按句話說，如果腳本sw.js位於/js/sw.js中，預設情況下它只能控制/js/下的url）。
所以請盡可能使用預設配置，放在網站根目錄。
如果有特殊情況，存放在第三方cdn，請在服務端使用 Service-Worker-Allowed 標頭指定 worker的最大作用域。
此代碼塊在浮窗中顯示
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);
此代碼塊在浮窗中顯示
範例程式碼
// 请在初始化前注册事件监听
// 极光通道断开连接时的回调
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(data) {
console.log("在线推送创建失败", data);
},
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();
// 请在初始化前注册事件监听
// 极光通道断开连接时的回调
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(data) {
console.log("在线推送创建失败", data);
},
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。
