Logo Site EngageLab Mark Colored Transparent文档
搜索

Web SDK API

鉴权

开发者在执行初始化的时候,需要传入必要信息,该数据结构由开发者服务端生成并传回浏览器,用于开发者授权此浏览器运行的 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 { 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 的页面路径 }
              
              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 {
  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)
              
              window.MTpushInterface.init(Object:InitType)

            
此代码块在浮窗中显示

参数说明

参数名称 参数类型 参数说明
code number 返回码,0 代表成功,其他失败,详见 错误码
message string 结果描述
content string 注册失败 1003 时返回失败信息

调用示例

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("已有通知权限,无需重复申请"); } }); }, });
              
              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()
              
              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
  • 0 : Engagelab 通道消息
  • 1 :系统通道消息
  • 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:'成功'
      }
    }
    
                
    此代码块在浮窗中显示

    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()
                  
                  window.MTpushInterface.getWebPermission()
    
                
    此代码块在浮窗中显示

    返回参数说明

    • granted :可用
    • denied :禁用
    • default:权限没确认

    自定义消息打点

    自定义消息如需上报做数据统计,请使用自定义上报接口。

    展示上报:

    window.MTpushInterface.customDisplayReport('msg_id');//msg_id为自定义消息的msg_id
                  
                  window.MTpushInterface.customDisplayReport('msg_id');//msg_id为自定义消息的msg_id
    
                
    此代码块在浮窗中显示

    点击上报:

    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({})

    MTpushInterface.setTagsAlias({ tags: ["test1", "test2"], alias: "aliass" });
                  
                  
    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 : "设置通知语言成功"); });
                  
                  MTpushInterface.setLan(lan, (err) => {
      alert(err ? "设置通知语言失败:" + err : "设置通知语言成功");
    });
    
                
    此代码块在浮窗中显示

    参数说明

    参数名称 参数类型 参数说明
    参数一 string 必填,语言参数,格式为 ISO 639-1 语言代码,例如中文为 "cn",英文为 "en",日语为 "ja" 等
    参数二 Function 可选,回调函数,设置完成后会被调用,形参 err 为错误信息(如果有的话),不存在形参则是成功

    接口说明

    开发者可通过该接口手动设置通知语言。设置成功后,SDK 会保存该语言;下次初始化未传 userLang 时会优先使用本地保存的语言。

    多次显示类别提示

    window.MTpushInterface.promptPushCategories()

    接口说明

    在用户订阅推送后,开发者可以根据需要多次显示类别提示,需要在初始化SDK完成后调用。

    调用示例:

    MTpushInterface.promptPushCategories();
                  
                  MTpushInterface.promptPushCategories();
    
                
    此代码块在浮窗中显示

    推送消息展示回调

    接口说明

    建议在初始化前调用消息监听。

    调用示例

    window.MTpushInterface.onMsgDisplay((msgData) => {});
                  
                  window.MTpushInterface.onMsgDisplay((msgData) => {});
    
                
    此代码块在浮窗中显示

    参数说明

    通知消息回调参数 msgData 说明:

    { engagelab_ntf_or_msg: number; engagelab_appkey: string; engagelab_passwd: string; engagelab_uid: number; engagelab_mesg_type: string; engagelab_m_str: string; engagelab_a_str: string; type: number; title: string; content: string; msg_id: string; }
                  
                  {
      engagelab_ntf_or_msg: number;
      engagelab_appkey: string;
      engagelab_passwd: string;
      engagelab_uid: number;
      engagelab_mesg_type: string;
      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: string; }
                  
                  {
      title: string;
      content: string;
      msg_id: string;
      ntf_or_msg: number;
      type: string;
    }
    
                
    此代码块在浮窗中显示

    注意:

    1、应用内消息 HTML 编辑模式下,展示回调的参数 title、content 为空字符串

    2、safari 浏览器使用系统通道下发消息,无法得到消息的展示回调

    推送消息点击回调

    接口说明

    建议在初始化前调用消息监听。

    调用示例

    window.MTpushInterface.onMsgClick((msgData) => {});
                  
                  window.MTpushInterface.onMsgClick((msgData) => {});
    
                
    此代码块在浮窗中显示

    参数说明

    通知消息回调参数 msgData 说明:

    { engagelab_ntf_or_msg: number; engagelab_appkey: string; engagelab_passwd: string; engagelab_uid: number; engagelab_mesg_type: string; 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 }
                  
                  {
      engagelab_ntf_or_msg: number;
      engagelab_appkey: string;
      engagelab_passwd: string;
      engagelab_uid: number;
      engagelab_mesg_type: string;
      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; }
                  
                  {
      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 浏览器使用系统通道下发消息,无法得到消息的点击回调。

    错误码

    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
    1006 failed to get baseUrl and reportUrl 接口get-webaddr请求失败,详情参考回调中的content字段
    1007 authentication failed 鉴权失败,详情参考回调中的content字段
    1008 region restricted 区域受限
    Icon Solid Transparent White Qiyu
    联系销售