Web SDK API
最新更新:2024-09-18
鑒權
開發者在執行初始化的時候,需要傳入必要信息,該數據結構由開發者服務端生成並傳回瀏覽器,用於開發者授權此瀏覽器運行的 MTpush 初始化。開發者需確保能調用獲取到此數據的皆為合法用戶。
初始化數據結構
interface MTInitInfo {
website_push_id: string;
code: number;
master_secret: string;
passwd: string;
pull: number;
regid: string;
sess: string;
tagalias: number;
uid: number;
vapid_pubkey: string;
}
type dataType = {
code: number;
content: string;
message: string;
};
interface InitType {
appkey: string; //開發者在 Engagelab 平台註冊的應用程式 appkey,必填
user_str: string; //用戶唯一標識,必填
swUrl?: string; //預設 "/sw.min." + sdkEnv.version + ".js"
debugMode?: boolean; //預設 false,
webSocketUrl?: string; //如果不存在則用 baseUrl
fail?: (data: dataType | undefined) => void; //初始化失敗回調
success?: (data: dataType | undefined) => void; //初始化成功回調
webPushcallback?: def;
canGetInfo?: (d: MTInitInfo) => void;
custom?: (Callback: () => void) => void; //自訂提示可用時回調,完成操用後調用 Callback 可申請
}
interface MTInitInfo {
website_push_id: string;
code: number;
master_secret: string;
passwd: string;
pull: number;
regid: string;
sess: string;
tagalias: number;
uid: number;
vapid_pubkey: string;
}
type dataType = {
code: number;
content: string;
message: string;
};
interface InitType {
appkey: string; //開發者在 Engagelab 平台註冊的應用程式 appkey,必填
user_str: string; //用戶唯一標識,必填
swUrl?: string; //預設 "/sw.min." + sdkEnv.version + ".js"
debugMode?: boolean; //預設 false,
webSocketUrl?: string; //如果不存在則用 baseUrl
fail?: (data: dataType | undefined) => void; //初始化失敗回調
success?: (data: dataType | undefined) => void; //初始化成功回調
webPushcallback?: def;
canGetInfo?: (d: MTInitInfo) => void;
custom?: (Callback: () => void) => void; //自訂提示可用時回調,完成操用後調用 Callback 可申請
}
此代碼塊在浮窗中顯示
同一範圍只能註冊一個 service worker。當初始化成功時報錯,類似於 Failed to execute 'subscribe' on 'PushManager': Subscription failed - no active Service Worker 的錯誤,確認是否有 service worker 衝突,需合併 service worker 或解決 service worker 的作用域衝突。
SDK 初始化
接口說明
初始化接口。
window.MTpushInterface.init(Object:InitType)
window.MTpushInterface.init(Object:InitType)
此代碼塊在浮窗中顯示
參數說明
- 詳見 InitType 說明。
- 回調 Object data 說明:
參數名稱 | 參數類型 | 參數說明 |
---|---|---|
code | number | 返回碼,0 代錶成功,其他失敗,詳見 錯誤碼 |
message | string | 結果描述 |
content | string | 註冊失敗 1003 時返回失敗信息 |
調用示例
MTpushInterface.init(
{
appkey: "xxx",
user_str: "adminDemo",
fail (data) {
console.log("在線推播建立失敗", data);
},
success (data) {
console.log("在線推播建立成功", data);
},
webPushcallback (cod, tip) {
console.log("用戶得到的狀態碼及提示", code, tip);
},
//swUrl?: string; //預設 "/sw.min." + sdkEnv.version + ".js"
canGetInfo (d) {
//此時可以得到 RegId 也可以在d裏面取到所有的數據
console.log("得到RegId", MTpushInterface.getRegistrationID(), d);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (reqPermission) => {
//當使用自定義提示配置時,需調用 reqPermission 來請求並配置權限 在custom回調中拿到請求權限函數,在適當的時機直接調用reqPermission來請求通知權限。
document.getElementById("xx")?.addEventListener("click", reqPermission); },
});
MTpushInterface.init(
{
appkey: "xxx",
user_str: "adminDemo",
fail (data) {
console.log("在線推播建立失敗", data);
},
success (data) {
console.log("在線推播建立成功", data);
},
webPushcallback (cod, tip) {
console.log("用戶得到的狀態碼及提示", code, tip);
},
//swUrl?: string; //預設 "/sw.min." + sdkEnv.version + ".js"
canGetInfo (d) {
//此時可以得到 RegId 也可以在d裏面取到所有的數據
console.log("得到RegId", MTpushInterface.getRegistrationID(), d);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (reqPermission) => {
//當使用自定義提示配置時,需調用 reqPermission 來請求並配置權限 在custom回調中拿到請求權限函數,在適當的時機直接調用reqPermission來請求通知權限。
document.getElementById("xx")?.addEventListener("click", reqPermission); },
});
此代碼塊在浮窗中顯示
獲取 RegistrationID
接口說明
調用此 API 來取得當前賬戶對應的 RegistrationID。 隻有初始化簽名成功後才返回對應的值,否則返回空字符串。該方法需在 canGetInfo 回調觸發後調用。
window.MTpushInterface.getRegistrationID()
window.MTpushInterface.getRegistrationID()
此代碼塊在浮窗中顯示
調用示例
var rid = window.MTpushInterface.getRegistrationID();
var rid = window.MTpushInterface.getRegistrationID();
此代碼塊在浮窗中顯示
停止推播
調用此 API 來斷開與後台建立的推播長連接,停止接收推播訊息。
window.MTpushInterface.mtPush.stopPush()
window.MTpushInterface.mtPush.stopPush()
此代碼塊在浮窗中顯示
推播訊息監聽
接口說明
建議在初始化前調用訊息監聽。
window.MTpushInterface.onMsgReceive(fn)
window.MTpushInterface.onMsgReceive(fn)
此代碼塊在浮窗中顯示
參數說明
參數名稱 | 參數類型 | 參數說明 |
---|---|---|
fn | function | 訊息接收處理函數 |
調用示例
window.MTpushInterface.onMsgReceive(function (res) {
if(res.type===0){
// res.data.messages[]
// res.data.messages[].msg_id
// res.data.messages[].title
// res.data.messages[].content
// res.data.messages[].extras
}else{
// res.data.title
}
});
window.MTpushInterface.onMsgReceive(function (res) {
if(res.type===0){
// res.data.messages[]
// res.data.messages[].msg_id
// res.data.messages[].title
// res.data.messages[].content
// res.data.messages[].extras
}else{
// res.data.title
}
});
此代碼塊在浮窗中顯示
返回數據
參數名稱 | 參數類型 | 參數說明 |
---|---|---|
type | number | |
data | Object | 訊息內容 |
Engagelab 通道訊息數組(messages)
參數名稱 | 參數類型 | 參數說明 |
---|---|---|
msg_id | string | 訊息 ID |
title | string | 訊息標題 |
content | string | 訊息內容 |
extras | Object | 訊息附加字段 |
係統通道訊息數據
支持 w3c interface NotificationOptions,詳見 mdn web docs。
檢查推播服務狀態
window.MTpushInterface.getPushAuthority()
window.MTpushInterface.getPushAuthority()
此代碼塊在浮窗中顯示
返回數據結構為如下:
{
mtPush:{
code:1, //1 成功,-1 初始化中,0 失敗
msg:'成功'
},
webPush:{
code:1, // 0 webpush 不可用(瀏覽器不支持), 1 可用, 2 權限已被禁用, 3 權限冇確認
msg:'成功'
}
}
{
mtPush:{
code:1, //1 成功,-1 初始化中,0 失敗
msg:'成功'
},
webPush:{
code:1, // 0 webpush 不可用(瀏覽器不支持), 1 可用, 2 權限已被禁用, 3 權限冇確認
msg:'成功'
}
}
此代碼塊在浮窗中顯示
獲取瀏覽器通知權限
window.MTpushInterface.getWebPermission()
window.MTpushInterface.getWebPermission()
此代碼塊在浮窗中顯示
返回參數說明
- granted :可用
- denied :禁用
- default:權限冇確認
上報自訂訊息數據
如需做自訂訊息的數據統計,請使用自訂上報接口上報數據。
window.MTpushInterface.customClickReport('msg_id');//msg_id為自訂訊息的msg_id
window.MTpushInterface.customClickReport('msg_id');//msg_id為自訂訊息的msg_id
此代碼塊在浮窗中顯示
斷線監聽
接口說明
初始化成功後出現斷線,SDK 會自動嘗試重連和簽名。 建議在初始化前調用此事件監聽,收到此事件請重新調用初始化。
window.MTpushInterface.mtPush.onDisconnect(fn)
window.MTpushInterface.mtPush.onDisconnect(fn)
此代碼塊在浮窗中顯示
調用示例
window.MTpushInterface.mtPush.onDisconnect(function () {
});
window.MTpushInterface.mtPush.onDisconnect(function () {
});
此代碼塊在浮窗中顯示
取消瀏覽器訂閱
取消通知訂閱,某些帳號隱私等級較高情況下,退出帳號時不需要通接收知時可使用該方法。
MTpushInterface.unSubscribe();
MTpushInterface.unSubscribe();
此代碼塊在浮窗中顯示
設置 TagsAlias
window.MTpushInterface.setTagsAlias({});
window.MTpushInterface.setTagsAlias({});
此代碼塊在浮窗中顯示
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
此代碼塊在浮窗中顯示
參數說明
參數名稱 | 參數類型 | 參數說明 |
---|---|---|
tags | string[] | 必填,數組最大長度為 1000,每個元素最多 40 個字符 |
alias | string | 必填,最多 40 個字符 |
接口說明
開發者通過該接口可以設置及刪除特定 alias 下的 tags,該接口是覆蓋邏輯,通知設置為空串可以刪除已有 tags。
多次顯示類別提示
window.MTpushInterface.promptPushCategories();
window.MTpushInterface.promptPushCategories();
此代碼塊在浮窗中顯示
接口說明
在用戶訂閱推送後,開發者可以根據需要多次顯示類別提示,需要在初始化SDK完成後調用。
錯誤碼
code | message | 備註 |
---|---|---|
0 | success | 調用成功 |
1000 | unknown error | 未知錯誤 |
1001 | initing , please try again later | 正在初始化,稍後再試 |
1002 | invalid config | 初始化配置錯誤 |
1003 | init failed | 初始化失敗,詳情參考控製台列印 |
1004 | init timeout | 初始化超時 |
1005 | network error | 網路錯誤,無網路或者連接不上 websocket |