在 JavaScript 用戶端中接收訊息

根據網頁是在前景 (焦點)、在背景、隱藏在其他分頁後方，或完全關閉，訊息行為會有所不同。在一切情況下，網頁必須處理 onMessage 回呼，但在背景中，您可能也需要處理 onBackgroundMessage 或設定顯示通知，讓使用者將網頁應用程式導向前景。

應用程式狀態	通知	資料	兩者並用
前景	onMessage	onMessage	onMessage
背景 (服務工作處理程序)	onBackgroundMessage (自動顯示通知)	onBackgroundMessage	onBackgroundMessage (自動顯示通知)

JavaScript 快速入門導覽課程範例示範了接收訊息所需的所有程式碼。

在網頁應用程式在前景運作時處理訊息

如要接收 onMessage 事件，您的應用程式必須在 firebase-messaging-sw.js 中定義 Firebase 訊息傳遞服務工作站。或者，您也可以透過 getToken(): Promise<string> 將現有的 Service Worker 提供給 SDK。

Web

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
const firebaseApp = initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = getMessaging(firebaseApp);
messaging_init_in_sw.js

Web

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here. Other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();
service-worker.js

當應用程式在前景運作時 (使用者目前正在瀏覽您的網頁)，您可以直接在該頁面中接收資料和通知酬載。

Web

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.onBackgroundMessage` handler.
import { getMessaging, onMessage } from "firebase/messaging";

const messaging = getMessaging();
onMessage(messaging, (payload) => {
  console.log('Message received. ', payload);
  // ...
});
messaging_receive_message.js

Web

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.onBackgroundMessage` handler.
messaging.onMessage((payload) => {
  console.log('Message received. ', payload);
  // ...
});
index.js

在網頁應用程式在背景執行時處理訊息

當應用程式在背景執行時收到的所有訊息，都會觸發瀏覽器顯示通知。您可以在應用程式伺服器的傳送要求中，或在用戶端上使用 Service Worker 邏輯，指定此通知的選項，例如標題或點擊動作。

點擊動作僅支援安全 HTTPS 網址。

在傳送要求中設定通知選項

針對從應用程式伺服器傳送的通知訊息，FCM JavaScript API 支援 fcm_options.link 鍵。這通常是您網頁應用程式中的網頁：

https://fcm.googleapis.com//v1/projects/<YOUR-PROJECT-ID>/messages:send
Content-Type: application/json
Authorization: bearer <YOUR-ACCESS-TOKEN>

{
  "message": {
    "token": "eEz-Q2sG8nQ:APA91bHJQRT0JJ...",
    "notification": {
      "title": "Background Message Title",
      "body": "Background message body"
    },
    "webpush": {
      "fcm_options": {
        "link": "https://dummypage.com"
      }
    }
  }
}

如果連結值指向已在瀏覽器分頁中開啟的網頁，則按一下通知會將該分頁移至前景。如果頁面尚未開啟，則通知點擊會在新分頁中開啟頁面。

由於資料訊息不支援 fcm_options.link，建議您在所有資料訊息中新增通知酬載。或者，您也可以使用 Service Worker 處理通知。

如需通知與資料訊息之間的差異，請參閱「訊息類型」。

注意： 如要傳送訊息至主題，請使用 Admin SDK 訂閱應用程式執行個體至主題。如要使用 Admin FCM API，您必須先按照「將 Firebase Admin SDK 新增至伺服器」一文中的步驟初始化 SDK。

在 Service Worker 中設定通知選項

針對資料訊息，您可以在 Service Worker 中設定通知選項。首先，請在 Service Worker 中初始化應用程式：

Web

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
const firebaseApp = initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = getMessaging(firebaseApp);
messaging_init_in_sw.js

Web

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here. Other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();
service-worker.js

如要設定選項，請在 firebase-messaging-sw.js 中呼叫 onBackgroundMessage。在此範例中，我們建立含有標題、內文和圖示欄位的通知。

Web

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { getMessaging } from "firebase/messaging/sw";
import { onBackgroundMessage } from "firebase/messaging/sw";

const messaging = getMessaging();
onBackgroundMessage(messaging, (payload) => {
  console.log('[firebase-messaging-sw.js] Received background message ', payload);
  // Customize notification here
  const notificationTitle = 'Background Message Title';
  const notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  self.registration.showNotification(notificationTitle,
    notificationOptions);
});
messaging_on_background_message.js

Web

messaging.onBackgroundMessage((payload) => {
  console.log(
    '[firebase-messaging-sw.js] Received background message ',
    payload
  );
  // Customize notification here
  const notificationTitle = 'Background Message Title';
  const notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});
service-worker.js

注意： 如要在點選通知時定義服務工作站中的自訂行為，請務必先處理 notificationclick，再匯入 FCM 函式或程式庫。否則 FCM 可能會覆寫自訂行為。

通知的最佳做法

如果您已熟悉網頁版推送訊息功能，則已經閱讀過廣泛指南，瞭解什麼是優質通知。對於透過網頁版 FCM 傳送通知的開發人員，最重要的考量重點是精確度和關聯性。請參考以下具體建議， 讓通知保持精確且切合需求：

• 使用圖示欄位傳送有意義的圖片。在許多用途中，這應該是使用者能立即認出的公司或應用程式標誌。或者，如果是即時通訊應用程式，它可能是傳送使用者的個人資料圖片。
• 使用標題欄位來表示郵件的精確性質。例如，「小傑已回覆」比「新訊息」更能精準傳達相關資訊。請勿將此寶貴空間用在公司或應用程式名稱中，請使用圖示達成此目的。
• 請勿使用通知標題或內文顯示網站名稱或網域；通知已包含網域名稱。
• 新增 fcm_options.link，通常用於將使用者返回網頁應用程式，並在瀏覽器中聚焦。在極少數情況下，您需要傳達的所有資訊都可以放入通知中，您可能就不需要連結。