Shopify独立站WebPush SDK接入指南

概述

本文档介绍如何在基于 Shopify 搭建的独立站中集成 WebPush SDK，实现浏览器推送功能。

前提条件

• Shopify 店铺管理员权限
• 已获取 WebPush SDK 文件（webSdk.produce.min.3.3.4.js、sw.produce.min.3.3.4.js）
• 了解 Shopify 主题编辑的基本操作

接入步骤

通过 Shopify 主题编辑器添加（推荐）

1. 上传 SDK 文件到 Shopify

1. 登录 Shopify 后台
2. 进入「在线商店」>「主题」
3. 点击当前使用主题的「操作」按钮，选择「编辑代码」
4. 在「Assets」文件夹中，点击「添加新资源」
5. 上传 webSdk.produce.min.3.3.4.js（主 SDK 文件）
6. 上传 sw.produce.min.3.3.4.js（Service Worker 文件，SDK 依赖此文件实现推送功能）
7. 上传后，记下文件的 URL（格式如：{{ 'webSdk.produce.min.3.3.4.js' | asset_url }} 和 {{ 'sw.produce.min.3.3.4.js' | asset_url }}）

重要提示：sw.produce.min.3.3.4.js 是 Service Worker 文件，用于在后台处理推送消息。SDK 初始化时必须正确配置此文件的路径。

2. 添加 SDK 引用，初始化 SDK

1. 在主题编辑器中，找到并打开 theme.liquid 文件
2. 在 </head> 标签前添加以下代码：

              
              <script>
  // 初始化SDK
  (function() {
    function initializeSDK() {
      // 略：Canvas、WebGL、插件指纹采集代码（保持不变）
      const visitorId = getFingerprint();

      if (typeof window.MTpushInterface !== 'undefined') {
        // 请在初始化前注册事件监听

        // 极光通道断开连接时的回调
        MTpushInterface.mtPush.onDisconnect(function () {
          console.log("onDisconnect");
        });

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

        //  推送初始化
        MTpushInterface.init({
          appkey: "", // 必填
          user_str: visitorId, // 必填，用户识别符，用来标识用户
          fail(err) {
            console.log("在线推送创建失败", err);
          },
          success(data) {
            console.log("在线推送创建成功", data);
          },
          webPushcallback(code, tip) {
            console.log("用户得到的状态码及提示", code, tip);
          },
          swUrl: '{{ "sw.produce.min.3.3.4.js" | asset_url }}', // Service Worker 文件地址，必须配置，域名必须为当前域名，且路径必须可访问
        });
      }
    }

    window.MTpushInterfaceReady = initializeSDK;
  })();
</script>
{{ 'webSdk.produce.min.3.3.4.js' | asset_url | script_tag }}

            

验证安装

1. 检查 SDK 是否加载

1. 打开网站页面
2. 右键点击，选择「检查」或按F12
3. 在 Console（控制台）中检查是否有 SDK 相关的加载信息
4. 输入 window.MTpushInterface 查看是否已定义

2. 测试功能

1. 确保网站已通过 HTTPS 访问（Web 推送要求 HTTPS）
2. 检查浏览器是否显示推送权限请求（如果配置了自动请求）

3. 检查 Service Worker 注册

1. 打开浏览器开发者工具（F12）
2. 切换到「Application」（应用程序）标签
3. 在左侧菜单中找到「Service Workers」
4. 确认 sw.produce.min.3.3.4.js 已成功注册
5. 如果显示错误，检查控制台中的错误信息

故障排除

常见问题及解决方案

Q1: SDK未加载

• 检查文件路径：确认 asset_url 是否正确生成
• 查看网络面板：检查 JS 文件是否成功下载
• 文件权限：确保文件在 Shopify Assets 中可访问

Q2: 初始化失败

• 加载顺序：确保 SDK 在初始化代码前已加载
• HTTPS要求：Web推送必须在 HTTPS 环境下工作
• 浏览器兼容性：检查浏览器是否支持 Web推送
• Service Worker 配置：确保 swUrl 参数已正确配置，且 Service Worker 文件路径可访问
• Service Worker 文件：检查 sw.produce.min.3.3.4.js 是否已上传到 Assets 文件夹

Q4: Service Worker 注册失败

• 文件路径：确认 swUrl 配置的路径是否正确，使用 {{ 'sw.produce.min.3.3.4.js' | asset_url }} 确保路径正确
• 文件访问：在浏览器中直接访问 Service Worker 文件 URL，确认文件可以正常下载
• 控制台检查：在浏览器控制台的 Application > Service Workers 中查看注册状态
• HTTPS 要求：Service Worker 必须在 HTTPS 环境下才能注册（localhost 除外）