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 查询功能使用指南
同一作用域只能注册一个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:'成功'
}
}
以下状态码用于 getPushAuthority().webPush.code 和 webPushcallback(code, tip),与初始化 fail 回调的错误码独立。
webPush对象的错误码:
| 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完成后调用。
调用示例:
MTpushInterface.promptPushCategories();
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; // 控制台标准应用内模板为 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 为鉴权接口的错误描述或网络异常信息,详见鉴权失败说明 |
| 1008 | region restricted | 区域受限;鉴权接口返回 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 表示应用不存在。
鉴权失败说明
鉴权接口失败时,SDK 将接口响应中的 message 放入 data.content 字符串,不会将接口原始 code 作为 content.code 返回。以下原始错误码需从浏览器开发者工具的鉴权请求(/v1/auth)响应中查看。
| 鉴权接口原始 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 监听会收到通知,但回调不携带该错误码。










