Logo Site EngageLab Mark Colored Transparent文档
搜索

Web SDK 集成指南

本文是 MTpush Web SDK 标准的集成指南文档。

各通道海外用户支持说明

通道类型 其他地区用户 中国大陆用户 说明
EngageLab通道 支持触达 支持触达 SDK默认支持
W3C通道 支持触达 支持触达 /

快速测试

Engagelab WebPush 集成demo及示例

集成前准备

  • 准备一个能访问的 https web 服务域名,集成后的页面需在该域名下进行测试与调试。web 离线推送不支持本地调试、不支持 http。
  • 访问 Engagelab WebPush,在【集成设定】-【 网站域名】页面,填写 https web 服务域名。

截屏2022-11-29 11.08.16.png

产品说明

Web SDK 为 web 应用提供一个基于各个浏览器内核通知和 websocket 的推送开发框架,对外提供较为简洁的 API 接口,方便第三方应用快速集成推送功能。浏览器内核通知支持 Edge、Chrome、 Safari 、Firefox 、Opera 等主流浏览器,websocket 支持绝大部分主流浏览器。

EngageLab WebPush服务支持PWA推送,您需要使用EngageLab WebPush提供的Web SDK将Web Push功能集成到您的PWA应用程序中,并按照文档中提供的示例代码来注册Service Worker并初始化Web Push功能。一旦集成完成,您就可以使用EngageLab WebPush的API来向您的PWA应用程序用户发送推送通知了。 具体参见文档说明

主要场景:

通知推送消息,自定义推送消息。

jpush-p-web-example.zip 集成压缩包内容

  • example
    • 是一个 web 页面,通过这个演示了 MTpush SDK 的基本用法,可以用来做参考。

获取应用信息

在控制台上创建应用,创建成功后自动生成 AppKey 用以标识该应用,详情参考 应用设置文档

SDK 接入

进入 控制台,下载 SDK,在每个页面接入 js:

<script type="text/javascript" src="./webPushSdk.min.2.1.2.js"></script>
              
              <script type="text/javascript" src="./webPushSdk.min.2.1.2.js"></script>

            
此代码块在浮窗中显示

tips

随包包含sw.xxx.js该文件是service worker文件,用于接收消息。 SDK默认会从根目下加载该文件。 service worker 最大的作用域是worker所在位置,(按句话说,如果脚本sw.js位于/js/sw.js中,默认情况下它只能控制/js/下的url)。 所以请尽可能使用默认配置,放在网站根目录。 如果有特殊情况,存放在第三方cdn,请在服务端使用 Service-Worker-Allowed 标头指定 worker的最大作用域。
              
              随包包含sw.xxx.js该文件是service worker文件,用于接收消息。
SDK默认会从根目下加载该文件。
service worker 最大的作用域是worker所在位置,(按句话说,如果脚本sw.js位于/js/sw.js中,默认情况下它只能控制/js/下的url)。
所以请尽可能使用默认配置,放在网站根目录。
如果有特殊情况,存放在第三方cdn,请在服务端使用 Service-Worker-Allowed 标头指定 worker的最大作用域。

            
此代码块在浮窗中显示

引入该 js 后,就可以使用 Window 上的全局对象 MTpushInterface。

SDK 初始化

生成 user_str

建议使用浏览器指纹生成唯一 user_str,防止无效用户注册:

// 略:Canvas、WebGL、插件指纹采集代码(保持不变) const visitorId = getFingerprint(); console.log('user_str', visitorId);
              
              // 略:Canvas、WebGL、插件指纹采集代码(保持不变)
const visitorId = getFingerprint();
console.log('user_str', visitorId);

            
此代码块在浮窗中显示

示例代码

// 请在初始化前注册事件监听 // 极光通道断开连接时的回调 MTpushInterface.mtPush.onDisconnect(function () { console.log("onDisconnect"); }); // 得到推送消息(Web 推送、浏览器厂商通道) MTpushInterface.onMsgReceive((msgData) => { // msgData 数据结构:{ data: { xxx }, type: 0 },type: 0 是极光通道,1 是系统通道 console.log("得到推送消息:", msgData); }); function initWebPush() { const appkey = "your_appkey"; const userStr = visitorId; if (!(appkey && userStr)) { console.log("appkey 与 user_str 都不能为空"); return; } // 推送初始化 MTpushInterface.init({ appkey: appkey, user_str: userStr, fail(err) { console.log("在线推送创建失败", err); }, success(data) { console.log("在线推送创建成功", data); }, webPushcallback(code, tip) { console.log("状态码及提示", code, tip); }, canGetInfo(data) { // 此时可以得到 RegId,也可以在 data 中取得初始化配置数据 console.log("初始化配置", data); console.log("得到 RegId", MTpushInterface.getRegistrationID()); }, custom: (requestPermission) => { // 使用自定义提示配置时,在合适的用户操作时机调用 requestPermission 请求通知权限 document.getElementById("subscribe")?.addEventListener("click", () => { if (Notification.permission === "default") { requestPermission(); } else if (Notification.permission === "denied") { console.log("通知权限已禁用,无法申请权限"); } else { console.log("已有通知权限,无需重复申请"); } }); }, }); } initWebPush();
              
                // 请在初始化前注册事件监听
  // 极光通道断开连接时的回调
  MTpushInterface.mtPush.onDisconnect(function () {
    console.log("onDisconnect");
  });

  // 得到推送消息(Web 推送、浏览器厂商通道)
  MTpushInterface.onMsgReceive((msgData) => {
    // msgData 数据结构:{ data: { xxx }, type: 0 },type: 0 是极光通道,1 是系统通道
    console.log("得到推送消息:", msgData);
  });

  function initWebPush() {
    const appkey = "your_appkey";
    const userStr = visitorId;

    if (!(appkey && userStr)) {
      console.log("appkey 与 user_str 都不能为空");
      return;
    }

    // 推送初始化
    MTpushInterface.init({
      appkey: appkey,
      user_str: userStr,
      fail(err) {
        console.log("在线推送创建失败", err);
      },
      success(data) {
        console.log("在线推送创建成功", data);
      },
      webPushcallback(code, tip) {
        console.log("状态码及提示", code, tip);
      },
      canGetInfo(data) {
        // 此时可以得到 RegId,也可以在 data 中取得初始化配置数据
        console.log("初始化配置", data);
        console.log("得到 RegId", MTpushInterface.getRegistrationID());
      },
      custom: (requestPermission) => {
        // 使用自定义提示配置时,在合适的用户操作时机调用 requestPermission 请求通知权限
        document.getElementById("subscribe")?.addEventListener("click", () => {
          if (Notification.permission === "default") {
            requestPermission();
          } else if (Notification.permission === "denied") {
            console.log("通知权限已禁用,无法申请权限");
          } else {
            console.log("已有通知权限,无需重复申请");
          }
        });
      },
    });
  }

  initWebPush();

            
此代码块在浮窗中显示

更多 API

其他 API 的使用方法请参考接口文档:Web SDK API

运行 demo

压缩包附带的 example 是一个 API 演示例子。你可以直接在浏览器运行测试。

Icon Solid Transparent White Qiyu
联系销售