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; //开发者在 URORA 平台注册的应用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; //开发者在 URORA 平台注册的应用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)

        
此代码块在浮窗中显示

参数说明

参数名称 参数类型 参数说明
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
  • 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:'成功'
      }
    }
    
            
    此代码块在浮窗中显示

    获取浏览器通知权限

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

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

    接口说明

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

    调用示例:

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

    错误码

    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
    在文档中心打开
    icon
    联系销售