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() {
      const visitorId = getFingerprint();

      if (typeof window.MTpushInterface !== 'undefined') {
        MTpushInterface.mtPush.onDisconnect(function () {
          console.log("onDisconnect");
        });

        MTpushInterface.onMsgReceive((msgData) => {
          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 }}',
        });
      }
    }

    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 除外）