Web SDK API
SDK 會根據 AppKey 自動取得所屬資料中心的連線位址及統計上報位址,包括德國法蘭克福和美國維吉尼亞,無需手動設定 baseUrl、report_url 或 webSocketUrl。
鑒權
開發者在執行初始化的時候,需要傳入必要信息,該數據結構由開發者服務端生成並傳回瀏覽器,用於開發者授權此瀏覽器運行的 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 | { code: number; [key: string]: unknown },
message: string,
};
interface InitType {
report_url?: string; // 统计上报地址,私有云或自定义部署场景使用
baseUrl?: string; // 服务器域名;与 report_url 同时存在时走私有云或自定义部署逻辑
userLang?: string; // 默认取浏览器当前的 navigator.language,必须是浏览器支持的语言值
safari_url?: string; // Safari 推送测试字段
appkey: string; // 开发者在 EngageLab 平台注册的应用 appkey,必填
user_str: string; // 用户唯一标识,必填
swUrl?: string; // 默认 "/sw" + sdkEnv.prefix
is_temporary?: "n" | "t"; // 默认 "n"
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 可申请通知权限
maOpen?: boolean; // 是否开启 ma-sdk 模块
maChannel?: string; // ma-sdk 使用的渠道名称,默认值为 default-channel
appName?: string; // ma-sdk 使用的网站名称,用于上报
userIdentity?: { userId?: string; anonymousId?: string }; // ma-sdk 使用的用户身份
maCompletion?: (code: number, msg: string) => void; // ma-sdk 初始化完成回调
openUrl?: string; // 点击通知时的跳转链接
encodeSwUrl?: boolean; // 是否对 swUrl 进行编码
regidSearchPath?: string; // 查询 Registration ID 的页面路径
}
- 參數說明:
- openUrl:點擊通知時開啟的位址
- 若發送通知時未指定開啟位址,則將使用本參數的值作為跳轉連結;
- 若該參數未設定,則會預設跳轉至整合網域;
- 在多網域整合場景下,該參數可實現向對應位址的跳轉;
- encodeSwUrl:是否對 swUrl 進行編碼
- 使用場景:若 swUrl 中含有 @ 等特殊符號,且伺服器限制了此 url 資源的存取,會導致 Service Worker 註冊失敗;需增加重新註冊 Service Worker 的機制,重試時將 swUrl 進行編碼。
- regidSearchPath:用於指定查詢 Registration ID 的頁面路徑,預設值為 /engagelab/regid,詳見文檔 Registration ID 查詢功能使用指南。
- openUrl:點擊通知時開啟的位址
同一範圍只能註冊一個 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)
參數說明
- 詳見 InitType 說明。
- 回調 Object data 說明:
| 參數名稱 | 參數類型 | 參數說明 |
|---|---|---|
| code | number | 返回碼,0 代錶成功,其他失敗,詳見 錯誤碼 |
| message | string | 結果描述 |
| content | string | Object | 失敗詳情;初始化失敗(1003)時可能傳回包含伺服器錯誤碼 code 的物件,詳見伺服器初始化錯誤碼。 |
調用示例
const appkey = "your_appkey";
const userStr = "adminDemo";
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("得到 RegId", MTpushInterface.getRegistrationID(), data);
// MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "swefgwwefwfwfwf" });
},
custom: (requestPermission) => {
// 使用自定义提示配置时,在合适的用户操作时机调用 requestPermission 请求通知权限
document.getElementById("subscribe")?.addEventListener("click", () => {
if (Notification.permission === "default") {
requestPermission();
} else if (Notification.permission === "denied") {
console.log("通知权限已禁用,无法申请权限");
} else {
console.log("已有通知权限,无需重复申请");
}
});
},
});
獲取 RegistrationID
接口說明
調用此 API 來取得當前賬戶對應的 RegistrationID。 隻有初始化簽名成功後才返回對應的值,否則返回空字符串。該方法需在 canGetInfo 回調觸發後調用。
window.MTpushInterface.getRegistrationID()
調用示例
var rid = window.MTpushInterface.getRegistrationID();
停止推播
調用此 API 來斷開與後台建立的推播長連接,停止接收推播訊息。
window.MTpushInterface.mtPush.stopPush()
推播訊息監聽
接口說明
建議在初始化前調用訊息監聽。
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
}
});
返回數據
| 參數名稱 | 參數類型 | 參數說明 |
|---|---|---|
| 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()
返回數據結構為如下:
{
mtPush:{
code:1, //1 成功,-1 初始化中,0 失敗
msg:'成功'
},
webPush:{
code:1, // 0 webpush 不可用(瀏覽器不支持), 1 可用, 2 權限已被禁用, 3 權限冇確認
msg:'成功'
}
}
- webPush對象的錯誤碼:
以下狀態碼適用於 getPushAuthority().webPush.code 和 webPushcallback(code, tip),與初始化 fail 回呼的錯誤碼獨立。
| code | msg | 備註 |
|---|---|---|
| 0 | The browser does not support the Notifications API | 瀏覽器不支持通知 API |
| 1 | Notification permissions available, message subscription successful. | 通知權限可用,消息訂閱成功 |
| 2 | Notification permissions have been disabled, message subscription failed. | 通知權限已被禁用,消息訂閱失敗 |
| 3 | Notification permissions have not been confirmed, message subscription has not been performed. | 通知權限尚未確認,未進行消息訂閱 |
| -1 | The browser does not support Service Worker. | 瀏覽器不支持 Service Worker |
| -2 | Service Worker does not support HTTP. | Service Worker 不支持 HTTP 協議 |
| -3 | Service Worker registration failed. | Service Worker 註冊失敗 |
| -4 | Notification permission is available, but message subscription failed. | 通知權限可用,但消息訂閱失敗 |
| -5 | Subscription has been canceled | 已取消訂閱 |
獲取瀏覽器通知權限
window.MTpushInterface.getWebPermission()
返回參數說明
- granted :可用
- denied :禁用
- default:權限冇確認
自訂訊息打點
自訂訊息如需上報做數據統計,請使用自訂上報接口。
展示上報:
window.MTpushInterface.customDisplayReport('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(function () {
});
取消瀏覽器訂閱
取消通知訂閱,某些帳號隱私等級較高情況下,退出帳號時不需要通接收知時可使用該方法。
MTpushInterface.unSubscribe();
設置 TagsAlias
window.MTpushInterface.setTagsAlias({});
MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
參數說明
| 參數名稱 | 參數類型 | 參數說明 |
|---|---|---|
| tags | string[] | 必填,數組最大長度為 1000,每個元素最多 40 個字符 |
| alias | string | 必填,最多 40 個字符 |
接口說明
開發者可透過該介面設置 tag 和 alias,注意該介面是覆蓋邏輯,設置為空字串即刪除已有的 tag 和 alias。
設置通知語言
MTpushInterface.setLan(lan)
MTpushInterface.setLan(lan, (err) => {
alert(err ? "設置通知語言失敗:" + err : "設置通知語言成功");
});
參數說明
| 參數名稱 | 參數類型 | 參數說明 |
|---|---|---|
| 參數一 | string | 必填,語言參數,格式為 ISO 639-1 語言代碼,例如中文為 "cn",英文為 "en",日文為 "ja" 等 |
| 參數二 | Function | 可選,回調函數,設置完成後會被調用,形參 err 為錯誤資訊(如果有的話),不存在形參則是成功 |
接口說明
開發者可透過該接口手動設置通知語言。設置成功後,SDK 會保存該語言;下次初始化未傳 userLang 時會優先使用本地保存的語言。
多次顯示類別提示
window.MTpushInterface.promptPushCategories();
接口說明
在用戶訂閱推送後,開發者可以根據需要多次顯示類別提示,需要在初始化SDK完成後調用。
Safari 回調相容性
SDK v3.3.8 及以上版本會根據 Safari 當前的訂閱類型選擇推播通道。回調是否可用取決於訂閱類型、事件發生時的頁面狀態以及監聽器的註冊時機:
| 訂閱方式或頁面狀態 | 展示回調 | 點擊回調 |
|---|---|---|
Legacy Safari Website Push 訂閱(保留舊版 deviceToken) |
不支援可靠的頁面端展示回調 | 不支援可靠的頁面端點擊回調 |
| W3C Push 訂閱,且事件發生時存在已開啟、受 Service Worker 控制的頁面 | 消息到達時可以觸發 | 使用者點擊通知時可以觸發 |
| W3C Push 訂閱,但事件發生時沒有可通訊的頁面 | 不觸發,之後開啟頁面也不會補發 | 不觸發;通知仍可開啟目標頁面,但不會向新頁面補發回調 |
| 事件發生後才註冊監聽器 | 不補發 | 不補發 |
頁面端回調、系統通知展示和服務端統計是彼此獨立的機制。未收到頁面端回調,不代表通知沒有展示,也不代表服務端沒有記錄送達、展示或點擊資料。
推送消息展示回調
接口說明
建議在初始化前調用消息監聽。
調用示例
window.MTpushInterface.onMsgDisplay((msgData) => {});
參數說明
通知消息回調參數 msgData 說明:
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_m_str: string;
engagelab_a_str: string;
type: number;
title: string;
content: string;
msg_id: string;
}
應用內消息回調參數 msgData 說明:
{
title: string;
content: string;
msg_id: string;
ntf_or_msg: number;
type: number;
}
上述型別適用於控制台提供的標準應用程式內範本,其中 type 是數值 0。自訂 HTML 範本的回呼資料由範本實作決定。
注意: 1、應用內消息 HTML 編輯模式下,展示回調的參數 title、content 為空字符串 2、Safari 回調受上方相容性條件限制。請在 SDK 初始化前註冊監聽器,並確保事件發生時存在受 Service Worker 控制的頁面。
推送消息點擊回調
接口說明
建議在初始化前調用消息監聽。
調用示例
window.MTpushInterface.onMsgClick((msgData) => {});
參數說明
通知消息回調參數 msgData 說明:
{
engagelab_ntf_or_msg: number;
engagelab_appkey: string;
engagelab_passwd: string;
engagelab_uid: number;
engagelab_m_str: string;
engagelab_a_str: string;
type: number;
title: string;
content: string;
msg_id: string;
target_event: string | null;
position: string; // 點擊位置,'msgBody' | 按鈕的id
}
應用內消息回調參數 msgData 說明:
{
position: 'msgBody' | 'mainBtn' | 'subBtn' | 'closeBtn';
msg_id: number;
title: string;
content: string;
extras: object | null;
ntf_or_msg: number;
strategy: object | null;
target_event: unknown[];
type: number;
icon: string;
}
注意:
1、應用內消息HTML編輯模式,position 的值由開發者決定,點擊回調的參數 title、content 為空字符串。 2、Safari 回調受上方相容性條件限制。點擊通知時如果沒有可通訊的頁面,開啟目標頁面後不會補發點擊回調。
錯誤碼
下表是初始化回呼的外層 data.code。伺服器初始化的具體失敗原因見 data.content.code,兩者可能使用相同數字,但含義不同。
| code | message | 含義 |
|---|---|---|
| 0 | success | 調用成功 |
| 1000 | unknown error | 未知錯誤;當 content 為 do not support websocket 時,表示瀏覽器不支援 WebSocket。 |
| 1001 | initing , please try again later | 正在初始化,稍後再試 |
| 1002 | invalid config | 初始化配置錯誤 |
| 1003 | init failed | 初始化失敗,詳情請參考回呼中的 content 欄位及主控台輸出;content.code 的含義見伺服器初始化錯誤碼。 |
| 1004 | init timeout | 初始化超時 |
| 1005 | network error | 網路錯誤,無網路或者連接不上 websocket |
| 1006 | failed to get baseUrl and reportUrl | 接口get-webaddr請求失敗,詳情參考回調中的content字段 |
| 1007 | authentication failed | 鑑權失敗,content 為鑑權 API 的錯誤描述或網路異常資訊,詳見鑑權失敗說明。 |
| 1008 | region restricted | 區域受限;鑑權 API 傳回 7017 時,SDK 將其轉換為此錯誤碼,content 為 REGION_RESTRICTED。 |
伺服器初始化錯誤碼
初始化失敗時,SDK 透過 fail 回呼傳回外層錯誤碼(如 data.code === 1003)。當 data.content 為物件時,可透過 data.content.code 取得伺服器傳回的具體錯誤碼,data.content.desc 為伺服器的錯誤描述(如有)。
初始化驗證及服務異常
| content.code | 含義 | 處理建議 |
|---|---|---|
| 4000 | 初始化參數無效 | 檢查 AppKey、user_str 及鑑權參數是否完整;使用 SDK 取得的鑑權資料,避免手動修改。 |
| 4003 | 鑑權簽章已過期或時間戳記超出有效範圍 | 重新取得鑑權資料後初始化;檢查產生鑑權資料的伺服器時鐘,時間戳記與伺服器目前時間的偏差不得超過 30 分鐘。 |
| 4005 | 簽章驗證失敗 | 核對 AppKey 與鑑權資料是否對應;自建鑑權服務時檢查簽章演算法及金鑰設定。 |
| 4006 | 應用程式不存在 | 檢查 AppKey 是否正確、應用程式是否已刪除,以及連線的資料中心是否與應用程式一致。 |
| 4008 | WebPush 應用程式的 VIP 服務已到期,伺服器拒絕初始化 | 檢查目前 AppKey 對應應用程式的 WebPush 方案狀態,續費恢復服務後重新初始化;若主控台顯示服務仍有效,請聯絡技術支援核查該 AppKey 的權益狀態。 |
| 5000 | 伺服器內部錯誤 | 稍後重試;若持續出現,請提供 AppKey、發生時間及完整錯誤資訊,聯絡技術支援。 |
| 5001 | 伺服器忙碌或等待註冊結果逾時 | 延遲後重試,避免頻繁重複初始化;若持續出現,請聯絡技術支援。 |
例如,data.code === 1003 且 data.content.code === 4008 表示本次初始化因 VIP 到期而失敗。排查時需同時查看外層 code 和 content 中的具體原因。
註冊服務透傳錯誤碼
初始化需要註冊使用者時,伺服器還會透傳註冊服務的回傳碼。下表列出伺服器保留的相容性對應,具體回傳取決於註冊服務版本。
| content.code | 含義 | 處理建議 |
|---|---|---|
| 11 | 伺服器內部錯誤 | 稍後重試;若持續出現,請聯絡技術支援。 |
| 999 | 參數無效 | 檢查初始化參數及鑑權資料。 |
| 1002 | 參數無效 | 檢查初始化參數及鑑權資料。 |
| 1005 | 找不到 AppKey | 檢查 AppKey 是否正確及應用程式所屬資料中心。 |
| 1006 | 應用程式不存在 | 檢查 AppKey 及應用程式狀態。 |
| 1008 | 應用程式不存在 | 檢查 AppKey 及應用程式狀態。 |
| 1009 | 應用程式不支援目前平台 | 確認 AppKey 對應的應用程式已設定 WebPush。 |
| 1015 | 超出使用者數上限 | 聯絡技術支援核查應用程式的使用者數限制。 |
| 4001 | AppKey 不存在或簽章驗證失敗 | 核對 AppKey、鑑權資料及簽章設定。 |
| 4002 | 使用者未登入 | 重新執行 SDK 初始化;若持續出現,請聯絡技術支援。 |
| 4004 | 註冊失敗 | 保留完整錯誤資訊,稍後重試;若持續出現,請聯絡技術支援。 |
例如,外層 data.code === 1008 表示區域受限,而外層為 1003、內層 data.content.code === 1008 表示應用程式不存在。
鑑權失敗說明
鑑權 API 失敗時,SDK 將 API 回應中的 message 放入 data.content 字串,不會將 API 原始 code 作為 content.code 傳回。以下原始錯誤碼需從瀏覽器開發者工具的鑑權請求(/v1/auth)回應中查看。
| 鑑權 API 原始 code | SDK 回呼 data.code | 含義及處理建議 |
|---|---|---|
| 400 | 1007 | 業務驗證失敗。APPKEY_NOT_FOUND 表示找不到 AppKey;也可能是尚未設定整合網域、請求缺少 Origin,或請求網域與應用程式設定不一致,需結合 content 的具體描述排查。Chrome 擴充功能整合還需檢查擴充功能 ID 設定。 |
| 2002 | 1007 | 伺服器內部錯誤,回呼 content 為 inner err;稍後重試,持續出現時聯絡技術支援。 |
| 2003 | 1007 | 參數無效,回呼 content 為 param invalid;檢查是否已傳入 AppKey、user_str。 |
| 7017 | 1008 | 區域存取受限,回呼 content 為 REGION_RESTRICTED;聯絡技術支援核查帳號的區域存取限制。 |
訂閱失效通知
伺服器透過 WebSocket 的 expired 命令下發 4107(subscribe expired),表示瀏覽器推送訂閱已失效。它屬於初始化後的系統通知,不作為初始化 fail 回呼中的錯誤碼傳回;SDK 的 mtPush.onExpired 監聽器會收到通知,但回呼不攜帶該錯誤碼。










