常見問題

關於 User_string 使用者唯一識別碼的說明

1. 在初始化過程中，開發者必須提供一個唯一字串（user_str），用於生成使用者的唯一識別碼（UID）。此 UID 用於推播通知的身分識別，且與使用者的裝置無關。
   

2. 若使用者在多個瀏覽器或裝置上使用相同的 user_str 進行訂閱，系統會認定其為同一位使用者。新的訂閱資訊將取代舊的資訊，確保使用者在最後一次訂閱的裝置／瀏覽器上接收訊息。藉此可避免同一位使用者在多個裝置／瀏覽器上收到重複訊息。系統後台會為每個 UID 僅保留最新的訂閱資訊。
   

3. 使用者可以隨時取消訂閱，我們的 SDK 提供了相應的介面來實作此功能。取消訂閱操作將解除 UID 與訂閱資訊之間的綁定，但不會改變瀏覽器的通知權限設定。
   

4. 理論上，user_str 應與使用者帳戶一一對應。在某些情境下，使用者可能處於訪客模式，此時開發者需要根據實際情況生成一個唯一的 user_str。我們的 SDK 不會自動處理這一步驟，以避免因 user_str 處理不當而導致統計資料不準確。
   

對於訪客模式的使用者，開發者可以使用以下範例函式來生成一個基於使用者瀏覽器唯一性的 user_str。但請注意，這種處理方式可能導致使用者在更換瀏覽器、裝置或清除快取後，生成新的 user_str。
範例函式

              
              function randomUid() {
 const keyStr = 'mtWebPushRandomUid';
 let uid = window.localStorage.getItem(keyStr);
 if (!uid) {
     uid = new Date().getTime().toString(36) + Math.floor(Math.random() * 10000000).toString(36);
     window.localStorage.setItem(keyStr, uid);
 }
 return uid;
}
var user_str = randomUid();

            

哪些平台支援 WebPush？

依作業系統分類的瀏覽器支援

註 1： Microsoft Edge（2019 年更新）、Opera、Samsung Browser、Yandex 和 UC Browser 等都是基於 Chromium 的瀏覽器，在 EngageLab 中會被標記為 Chrome。
註 2： Internet Explorer 不再接受功能更新。微軟已將瀏覽器開發轉向 Edge 平台。
註 3： 無痕模式、私人瀏覽模式和訪客瀏覽器模式不支援網頁推播。

依瀏覽器版本支援

Safari 瀏覽器的 Web 推播通知相關問題

Safari 瀏覽器上的 Web 推播通知支援 macOS（V11.1+）以及 iOS／iPadOS 16.4+。

Safari 推播支援哪些功能特性？

iOS 和 iPadOS 上的使用者如何收到 Safari 網頁推播通知？

1. 開發者如何設定才能讓使用者在 iOS/iPadOS 16.4+ 中接收 web 通知？

在 iOS/iPadOS 16.4+ 中，可以使用 Web 推播通知。但是，網站必須具有適當的 manifest 檔案，並設定正確的屬性，才能讓通知正常運作。請在對應整合頁面的 HTML 中加入以下程式碼：「」

引入 manifest 檔案：

              
              {
    "$schema": "https://json.schemastore.org/web-manifest-combined.json",
    "display": "standalone",
    "start_url": "/webpush/index.html",
    "name": "Engagelab WebPush Example",
    "short_name": "Engagelab",
    "icons": [
        {
            "src": "/icon-large-cb438cac.png",
            "type": "image/png",
            "sizes": "1024x1024"
        }
    ]
}

            

2. 為了讓使用者訂閱並接收行動版 Safari Web 推播通知，他們必須將 Web 應用加入主畫面

發送行動版 Safari Web 推播通知（適用於 iOS 和 iPadOS 16.4+）需要通知接收者執行以下操作：

• 在 16.4+ 的行動 Apple 裝置上使用 Safari 瀏覽器造訪您的網站。
• 點擊行動裝置上 Safari 瀏覽器的分享按鈕。
• 點擊「加入主畫面」選項。
• 將應用程式儲存至裝置。
• 從主畫面開啟應用程式。
• 訂閱通知（在顯示原生權限提示之前，必須先點擊訂閱按鈕）。這些步驟是接收行動 Web 推播通知所必需的。
  由於這種互動體驗對終端使用者來說較為複雜，因此您需要協助終端使用者了解訂閱通知的好處。

3. 在您的網站上新增橫幅通知，引導使用者將應用「加入主畫面」

您可以在網站上新增橫幅，告知終端使用者行動 Web 推播通知的價值，以及如何引導他們完成訂閱。
我們建議您在網站上新增橫幅，於行動 Apple 裝置上顯示，引導訪客點擊分享按鈕和「加入主畫面」選項。
另外還有一個熱門的開源專案可以協助您為使用者提供這些指引：
底部橫幅範例 Github 連結：https://github.com/rajatsehgal/add-to-home-screen

如果關閉瀏覽器，使用者還能收到通知嗎？

• 走 EngageLab 通道時，需要開啟網站才能收到通知。
• 走系統通道時，即使關閉瀏覽器仍可能收到通知，但不同平台上的行為不同，詳情請參見下表：

在 Windows 上，所有視窗都關閉後，若瀏覽器仍在背景執行，即可收到系統通知；若瀏覽器程序已被關閉，則不會收到系統通知。
在 macOS 上，即使所有視窗都被關閉，大部分瀏覽器程序仍會在背景執行，因此可以收到系統通知；若瀏覽器程序被強制結束，則不會收到系統通知。Safari 無需執行即可接收通知，因為通知會直接發送到作業系統。使用者需要先註冊 Safari 通知，之後即使 Safari 完全關閉也能收到通知。

通知授權提示相關問題

在使用者關閉網頁推播提示後，何時會再次顯示提示？

如果使用者在原生權限提示上點擊 "Block"（Chrome）、"Don't Allow"（Safari）或 "Never Allow"（Firefox），則該網站將無法再次向其顯示提示，除非使用者透過瀏覽器設定執行多步驟操作來訂閱或重設權限。這就是為什麼建議使用 EngageLab 提示（前往設定）的原因。

原生權限提示

Web 推播訂閱需要瀏覽器原生權限提示，且原生權限提示不可自訂。它會使用使用者瀏覽器設定中的語言。只有 HTTPS 網站可以顯示瀏覽器原生提示。

Chrome：您有 3 次機會讓使用者訂閱，當使用者在原生權限提示上第 3 次點擊「X」後，使用者將在一週內不再收到提示。關於此 Chrome 功能的更多資訊，請參閱此處。
Firefox：從 Firefox 70 開始，當使用者點擊「關閉」按鈕後，需要點擊瀏覽器中的小通知圖示才能再次收到提示。此外，對於 Firefox 72+，原生瀏覽器提示已被阻止顯示，詳細資訊請參閱此處。
Safari：與 Firefox 一樣，加入了更安靜的 UI，用於提示通常拒絕權限的使用者，並自動提示被拒絕推播的網站，Safari 12.1+

EngageLab 軟提示

因為原生彈窗只有一次機會，如果被使用者拒絕，網站將無法再次向使用者取得授權，因此 EngageLab 建議您使用「軟提示」的方式來取得使用者授權：
如果使用者在 EngageLab 提示（前往設定Guide to apply）上點擊「允許」或「取消」，並且仍未透過原生提示彈窗完成訂閱，EngageLab 提示可以再次彈出。

• 使用者在 EngageLab 提示上點擊 "允許Allow" 後，會呼叫出原生彈窗，但若使用者此時在原生提示上點擊 "取消"，則使用者下次進入網站時，EngageLab 提示仍會彈出詢問使用者是否允許授權該網站通知。
  
• 使用者在 EngageLab 提示上點擊 "允許Allow" 後，會呼叫出原生彈窗，若使用者此時在原生提示上點擊「允許」，則使用者就授權了該網站進行 Web 通知的權限；若使用者此時在原生提示上點擊「拒絕」，網站將無法再次向使用者取得授權。
  
• 使用者在 EngageLab 提示上點擊「取消」時，則可以判斷為使用者此時沒有接收該網站通知的意願。如果此時詢問使用者是否接收網站通知訊息，很可能會被拒絕，所以我們此時不會呼叫原生彈窗，待下次使用者造訪時可再次透過 EngageLab 提示詢問使用者接收通知的意願。

通知收不到的排查方式

1. 檢查網頁通知欄權限是否開啟

2. 檢查瀏覽器應用通知權限是否開啟
Windows 通知設定：

• 關閉專注輔助，詳情請參考 微軟官方文件。
• 檢查「設定 > 通知與動作 > 開啟從應用程式和其他寄件者取得通知」。請確認您的網站和瀏覽器也已啟用。本文中的更多詳細資訊請參考 微軟官方文件。

macOS 通知設定：

• 在「系統偏好設定」>「通知」>「Chrome」或所選瀏覽器中，請確認「允許通知」已開啟。
• 在「系統偏好設定」>「通知」>「專注模式」>「請勿打擾與睡眠」中，請確認此模式未開啟，或您位於允許通知的時段內。
• macOS 在右上角選單 > 向上捲動中也有暫時性的「請勿打擾」通知設定。

3. 瀏覽器廠商通道不穩定，切換為 EngageLab 通道優先下發

              
              {
    "from":"web_push",
    "to":{
        "registration_id":[
            "xxx"
        ]
    },
    "body":{
        "platform":"web",
        "notification":{
            "web":{
                "title":"web_push",
                "alert":"Hi,MTPush !",
                "url":"http://www.google.com",
                "extras":{
                    "web-key1":"web-value1"
                }
            }
        },
        "options":{
            "time_to_live":30,
            "third_party_channel":{
                "w3push":{
                    "distribution":"mtpush"
                }
            }
        },
        "request_id":"12345678",
        "custom_args":"business info"
    }
}

            

Safari 瀏覽器無法彈出通知？

第一步：請檢查 Safari 瀏覽器權限，注意允許開關是否已開啟，正常情況如下圖：

第二步：點擊檢查推播服務狀態與瀏覽器通知權限，正常情況如下圖：

第三步：點擊 Safari 瀏覽器 - 偏好設定

點擊網站 - 點擊通知，查看通知中心網站是否允許，正常情況如下圖：

特別注意： 1、點擊停止推播，將會收不到極光推送訊息，需要重新整理頁面 2、一個網域名稱配置了多個 HTML 頁面時，請不要移除通知中心的網站權限，移除後所有 HTML 頁面都將收不到通知（需由使用者找到主頁面，重新取得網站通知權限）

如果同一位使用者同時使用多個瀏覽器，向該使用者下發一則訊息，使用者裝置會如何顯示？

如果選擇的下發策略是系統通道優先，則這則訊息只會透過該使用者最近一次使用的瀏覽器廠商通道下發。如果選擇僅透過極光通道下發，則會下發多則。

如果使用者清除瀏覽器快取和 Cookie，還能接收到這個網站的 WebPush 嗎？

使用者在線上時，極光通道仍然可以收到推播。
對於瀏覽器廠商通道來說，當使用者清除瀏覽器的 Cookie 和快取時，將會取消訂閱通知。這是因為訂閱使用者資料儲存在瀏覽器的 IndexedDB 中。移除該資料會使瀏覽器「忘記」訂閱者。但是清除這些資料並不會移除使用者已經授權在該瀏覽器中接收通知的權限，此時需要重新初始化 SDK，讓使用者在返回網站時自動重新訂閱。
但如果使用者將瀏覽器的通知權限更改為「詢問」或「封鎖」，則不會被自動重新訂閱。
如果使用者從瀏覽器的通知設定中清除通知，也不會被自動重新訂閱。

各瀏覽器清除通知的方式：

• Chrome：chrome://settings/content/notifications
  

• Firefox：about:preferences#privacy > 權限 > 通知
  

• Safari：偏好設定 > 網站 > 通知 > 刪除

當使用者重新訂閱時，將獲得一筆新的 Registration ID 記錄。您可以使用 window.MTpushInterface.getRegistrationID() 來取得 rid。

同一時間向同一位使用者發送多則訊息，訊息都會顯示嗎？

不同推播通道的訊息顯示機制會有所差異：
EngageLab 通道：無覆蓋機制。同一時間向同一位使用者發送多則訊息，多則訊息會同時顯示給使用者。通知中心會保留多則訊息，除最近一則訊息外，其他訊息會折疊。
Safari：無覆蓋機制。同一時間向同一位使用者發送多則訊息，多則訊息會同時顯示給使用者。通知中心會保留多則訊息，除最近一則訊息外，其他訊息會折疊。
Chrome：有覆蓋機制。同一時間向同一位使用者發送多則訊息，每個通知將被更新的通知取代，僅會顯示最後一則發出的訊息。
Edge：有覆蓋機制。同一時間向同一位使用者發送多則訊息，每個通知將被更新的通知取代，僅會顯示最後一則發出的訊息。
Firefox：有覆蓋機制。同一時間向同一位使用者發送多則訊息，每個通知將被更新的通知取代，僅會顯示最後一則發出的訊息。

EngageLab WebPush 支援更換網域名稱嗎？

瀏覽器已經以將訂閱者綁定到特定來源（網域名稱／網站 URL）的方式設定 Web Push。
出於安全原因和瀏覽器的同源政策，瀏覽器不允許將訂閱者移動到其他來源。這不是 EngageLab 的限制，任何聲稱可以將訂閱者從一個網站移動到另一個網站的服務商，請務必確認他們訂閱的是您的網站。
如果您更改了網站，最佳解決方案是為新網站設定一個新的 WebPush 應用，並讓您的使用者在此新應用下重新訂閱網站，您無法將訂閱者從一個來源匯入到另一個來源。
您可以繼續向舊網站（舊 WebPush 應用）的訂閱者發送推播通知，但您的使用者需要重新訂閱新網站，才能從新網域名稱接收推播。建議的遷移步驟如下：

• 為新站點網域名稱設定一個新的 WebPush 應用。
  
• 使用舊站點網域名稱，繼續從舊 WebPush 應用發送推播。在通知的「啟動 URL」中，使用新站點網域名稱。
  
• 在 2 週到 2 個月之後（具體取決於您每天發送多少通知，以及在新網站上獲得多少訂閱者），您可以停止使用舊的 WebPush 應用，僅使用新的 WebPush 應用。
  
• 如果您從舊的 WebPush 應用和新的 WebPush 應用發送相同的訊息，那麼同時訂閱兩者的訂閱者將收到重複訊息。這就是為什麼我們建議遵循這些時間框架。
  
• 您可以發送幾則「我們已經搬遷，點擊這裡造訪我們的新網站並重新訂閱以保持最新資訊」的訊息。這將有助於提醒使用者，如果不返回重新訂閱，可能無法再從您的網站收到推播。建議在搬遷開始時，以及從應用發送的最後一則訊息時發送此類通知。
  
• 很遺憾，所有網站和使用者群體都有所不同。請做好短期內可能流失訂閱者的準備。
  在執行上述遷移步驟時，請務必注意使用者體驗，以免造成使用者不便。

EngageLab WebPush 支援 PWA 推播嗎？

1. 什麼是 PWA?

PWA 推播是指在漸進式 Web 應用程式（Progressive Web App，簡稱 PWA）中，使用 Web Push 技術向使用者推送通知的過程。PWA 是一種使用 Web 技術建構的應用程式，具備類似原生應用程式的功能與使用者體驗，同時可透過瀏覽器存取，無需安裝。
PWA 推播是透過瀏覽器提供的 Web Push 技術實現的。Web Push 技術使 Web 應用程式可以像原生應用程式一樣發送推播通知，即使應用程式不在啟用狀態或已完全關閉。
與傳統應用程式不同，PWA 不需要從應用商店下載與安裝，可以透過 URL 直接在瀏覽器中存取。同時，PWA 推播可向使用者提供即時訊息提醒，增強使用者體驗與參與度。
總之，PWA 推播是一種使用 Web Push 技術向漸進式 Web 應用程式使用者發送通知的方法，可以提高使用者參與度與互動性，為 Web 應用程式提供更接近原生應用程式的使用體驗。

2. EngageLab WebPush 支援 PWA 推播嗎？

EngageLab WebPush 服務支援 PWA 推播，您需要使用 EngageLab WebPush 提供的 Web SDK 將 Web Push 功能整合到您的 PWA 應用程式中，並按照文件中提供的範例程式碼註冊 Service Worker 並初始化 Web Push 功能。一旦整合完成，您就可以使用 EngageLab WebPush 的 API 向您的 PWA 應用程式使用者發送推播通知。

註：Web SDK 支援 PWA 的兩個必要條件：
1. 程式執行於瀏覽器中，且瀏覽器支援 W3C Notifications；2. 具有具體的網域名稱，且為 HTTPS 協定。

3. PWA 的 server work 會不會和 EngageLab WebPush 的 server work 衝突？

PWA（Progressive Web App）的 service worker 和 EngageLab WebPush 的 service worker 有可能會衝突，因為兩者都在瀏覽器背景中執行，且對於同一個來源（origin）來說，通常只能有一個 service worker 處於啟用狀態。

Service workers 是一種由網站安裝在瀏覽器中的指令碼，可以支援離線體驗、訊息推播和背景同步等功能。因為 service worker 會在其作用域內控制頁面，所以在同一個作用域下不能有多個 service workers 同時控制頁面。

如果您嘗試在同一個應用／網域下註冊多個 service workers，後面註冊的可能會取代前面的；或者當兩個 service workers 的作用域有重疊時，可能會出現衝突。這種衝突可能導致非預期行為，例如訊息推播可能只能透過其中一個 channel 正常運作。

為了避免這種衝突，您可以：

1. 確保您只在應用中使用一個 service worker。如果 EngageLab 提供的 WebPush 功能和您的 PWA 功能可以透過同一個 service worker 實現，那麼最好將它們合併到一個 service worker 指令碼中。

2. 如果需要使用兩個獨立的 service workers，您應當確保它們的作用域不重疊。這可以透過在註冊 service worker 時指定不同的作用域路徑來實現。

在實施之前，建議仔細閱讀相關文件，並在開發與正式環境中進行充分測試，以確保 service workers 能夠和平共存，不會互相干擾。

4. iOS 和 Android 裝置上 PWA 應用通知權限彈窗行為的差異

• iOS 系統限制（Safari/WebKit 策略）：
  · 出於隱私考量，iOS 要求必須存在使用者手勢（如點擊）才能觸發權限彈窗
  · 這是 WebKit 的強制策略，適用於所有 PWA 和網頁應用
  · 首次安裝 PWA 後，也需要使用者主動互動才能請求權限

• Android 系統特性：
  · Chrome/WebView 允許在頁面載入時自動請求權限
  · 遵循較寬鬆的權限請求模型
  · 部分 Android 版本甚至支援漸進式權限提示

為什麼不同瀏覽器的 registration ID 會相同？

答：同一個應用配置的整合網域名稱、同一位使用者 userStr，會生成同一個 rid，與是否為同一個瀏覽器無關。

• 檢查是否為同一位使用者的方法如下：查看 HTML 原始碼，找到初始化函式查看。

              
              // 請在初始化前註冊事件監聽
// 極光通道斷開連線時的回呼
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.min." + sdkEnv.version + ".js"。此配置項為server worker檔案位址，網域名稱必須為目前網域名稱，且路徑決定server worker作用域。
  canGetInfo(data) {
    // 此時可以取得通知的一些配置資料，在此回呼函式之後可以取得RegId
    console.log(data); // 相關配置信息
    console.log("取得RegId", MTpushInterface.getRegistrationID());
  },
  custom: (fuc) => {
    // 當使用自訂提示配置時，需手動呼叫fuc()來請求通知權限。只能透過custom取得請求通知權限函式。
    // fuc() 呼叫時會請求通知權限
  },
});

            

如果您在使用過程中遇到本文檔未涵蓋的問題，歡迎隨時聯絡客服，我們將為您提供專業支援與解答。