偵測

您可以偵測使用者是否在瀏覽器或獨立模式下使用 PWA。在以 Chromium 為基礎的瀏覽器 (Android 和電腦版) 上,您也可以偵測下列事件:

  • 安裝邀請對話方塊狀態和結果。
  • 安裝完成。
  • 從瀏覽器切換到 PWA 視窗,反之亦然。
  • PWA 安裝狀態。
  • 從應用程式商店安裝的相關應用程式。

您可以將這類資料用於數據分析,瞭解使用者的偏好設定,並提供個人化體驗。如要擷取這些事件,您可以使用各種工具,例如媒體查詢、window 的事件,或使用此處列出的功能 API

正在偵測顯示模式

如要追蹤使用者啟動 PWA 的方式,您可以使用 matchMedia() 測試 display-mode 媒體查詢。

function getPWADisplayMode() {
  if (document.referrer.startsWith('android-app://'))
    return 'twa';
  if (window.matchMedia('(display-mode: browser)').matches)
    return 'browser';
  if (window.matchMedia('(display-mode: standalone)').matches)
    return 'standalone';
  if (window.matchMedia('(display-mode: minimal-ui)').matches)
    return 'minimal-ui';
  if (window.matchMedia('(display-mode: fullscreen)').matches)
    return 'fullscreen';
  if (window.matchMedia('(display-mode: window-controls-overlay)').matches)
    return 'window-controls-overlay';

  return 'unknown';
}

window.addEventListener('DOMContentLoaded', () => {
  // Log launch display mode to analytics
  console.log('DISPLAY_MODE_LAUNCH:', getPWADisplayMode());
});

如果您使用這個範例,請務必與網頁應用程式資訊清單中的顯示模式相符,例如 standaloneminimal-uifullscreen。您也可以使用逗號分隔的條件,在媒體查詢字串中比對多個查詢。

您也可以在資訊清單的 start_url 中加入查詢參數,透過數據分析追蹤相關統計資料,瞭解 PWA 的使用時間、方式和使用方式。

應用程式安裝

使用者在瀏覽器中接受安裝提示時,以 Chromium 為基礎的瀏覽器會觸發 appinstalled 事件。這個事件處理常式的一個好處,就是能移除您新增的所有應用程式內安裝促銷活動。

window.addEventListener('appinstalled', () => {
  // If visible, hide the install promotion
  hideInAppInstallPromotion();
  // Log install to analytics
  console.log('INSTALL: Success');
});

請注意,在搭載 WebAPK 的 Android 裝置上,事件會在使用者接受對話方塊時觸發,而非在 WebAPK 鑄造及安裝後觸發。應用程式可能需要幾秒的時間才能完全安裝。

安裝提示章節說明如何偵測是否有可用的安裝提示,以及使用者選擇的選擇。

工作階段轉移

使用者可以在瀏覽器和已安裝的獨立應用程式中使用 PWA。在電腦版瀏覽器中,您可以使用徽章或選單項目在這些情境之間轉移目前導覽,如下圖所示。

瀏覽器分頁與 PWA 視窗之間的導覽轉移。

在 Android 裝置上,會有與電腦版瀏覽器類似的選單項目,將導航轉移至應用程式。在這種情況下,系統會開啟目前的網址,但會在應用程式中改為瀏覽新的頁面。

在下圖中,您可以看到已安裝應用程式的 Android 裝置中的選單項目。

Android 版 Chrome 會顯示選單項目,可在 PWA 視窗中開啟新的導覽。

安裝後轉移

在電腦版瀏覽器中,當安裝應用程式時,目前的導覽會立即轉移至應用程式。瀏覽器分頁會關閉,並開啟新安裝的應用程式,繼續執行使用者先前的工作。

在行動瀏覽器上,安裝應用程式時,目前的導覽會保留在瀏覽器中。如果使用者想切換至應用程式,必須手動開啟應用程式,這會是新的導覽。

偵測轉乘

如要偵測瀏覽器和視窗之間的轉移,您可以使用媒體查詢:

window.addEventListener('DOMContentLoaded', () => {
  // Replace "standalone" with the display mode used in your manifest
  window.matchMedia('(display-mode: standalone)')
    .addEventListener('change', () => {
      // Log display mode change to analytics
      console.log('DISPLAY_MODE_CHANGED', getPWADisplayMode());
    });
});

iOS 和 iPadOS 儲存空間隔離

在 iOS 和 iPadOS 上,瀏覽器與安裝的圖示之間無法進行瀏覽或網址轉移。即使是相同的 PWA,使用者安裝的每個 PWA 圖示都會有專屬的儲存空間,與 Safari 的分頁和其他圖示隔離開來。使用者開啟已安裝的圖示時,系統不會與 Safari 共用任何儲存空間。如果您的 PWA 需要登入,使用者就必須重新登入。如果應用程式已多次新增至主畫面,則每個 PWA 例項都會產生不同的工作階段。

瀏覽器支援

  • Chrome:不支援。
  • Edge:不支援。
  • Firefox:不支援。
  • Safari:不支援。

資料來源

網站會透過資訊清單表明與應用程式的關係。方法是使用 Web App 資訊清單規格的 related_applications 成員related_applications 鍵是代表各個相關應用程式的物件陣列。每個項目都包含 platformurl 和選用的 id

以下是可能的平台值

  • chrome_web_store:Google Chrome 線上應用程式商店。
  • play:Google Play 應用程式 (Android 和 ChromeOS)。
  • chromeos_play:ChromeOS Play。
  • webapp:網頁應用程式。
  • windows:Microsoft Store (Windows 10 和 11)。
  • f-droid:F-droid。
  • amazon:Amazon AppStore (FireOS)。

當使用者安裝應用程式時,如果您在資訊清單中將 prefer_related_applications 欄位設為 true,您可以將他們重新導向至相關的應用程式。進行這項設定後,在相容的瀏覽器中,安裝流程不會安裝 PWA,而是從 related_applications 項目中指定的 urlid 觸發商店安裝作業。

相關的應用程式可以是 PWA,且會透過應用程式商店安裝。這項設定的其中一個優點是,目前只有透過應用程式商店安裝的應用程式,才會在備份或切換至新裝置時復原。

{
  ...
  "related_applications:" [
     {
       "platform": "play",
       "url": "https://play.google.com/..."
     }
  ],
  "prefer_related_applications": true
}

Apple 智慧型應用程式橫幅廣告

Safari 不支援 related_applications 成員,但可為 App Store 中的應用程式提供智慧型應用程式橫幅廣告。因此,如果您想宣傳在 App Store 中發布的 PWA 或其他應用程式,可以在 PWA 的 HTML 中加入中繼標記,邀請使用者安裝應用程式 (請參閱剛才提供的連結),或在使用者已安裝應用程式時轉移導覽。

getInstalledRelatedApps() 方法可讓網站檢查使用者的裝置是否已安裝您的 iOS/Android/電腦版應用程式或 PWA。

檢查是否已安裝相關應用程式,有助於您導入功能,例如隱藏自訂安裝提示,或將使用者直接重新導向至已安裝的應用程式,而非前往一般用途網站。如要使用 getInstalledRelatedApps() 方法,已安裝的應用程式和網站都必須設定彼此的連線。每個應用程式 (視其平台而定) 都會在資訊清單的 related_applications 欄位中,提供可辨識網站的中繼資料,也會在應用程式的 related_applications 欄位中列出預計安裝的應用程式。

可讓您將 PWA 發布到應用程式商店的 BubbleWrapPWA 建構工具 (PWA),已經新增必要中繼資料,讓網站能夠立即使用 getInstalledRelatedApps()。 如要使用 getInstalledRelatedApps() 偵測是否已安裝 PWA,請在資訊清單 related_applications 欄位中定義 webapp,並附上資訊清單的網址:

...
"related_applications": [{
   "platform": "webapp",
   "url": "https://example.com/manifest.json",
}],
...

getInstalledRelatedApps() 會傳回應用程式物件的陣列。如果陣列為空白,表示未安裝相關應用程式。

const relatedApps = await navigator.getInstalledRelatedApps();
const PWAisInstalled = relatedApps.length > 0;

偵測 PWA 範圍外的安裝作業

從 Android 89 版 Chrome 開始,你可以偵測是否已安裝 PWA,即使不在 PWA 範圍內也沒問題。您的 PWA 必須在 /.well-known/ 資料夾中設定 JSON 檔案,授予其他範圍的權限,如本文所述。

資源