根據網頁是在前景 (焦點)、在背景、隱藏在其他分頁後方,或完全關閉,訊息行為會有所不同。在一切情況下,網頁必須處理 onMessage
回呼,但在背景中,您可能也需要處理 onBackgroundMessage
或設定顯示通知,讓使用者將網頁應用程式導向前景。
應用程式狀態 | 通知 | 資料 | 兩者並用 |
---|---|---|---|
前景 | onMessage |
onMessage |
onMessage |
背景 (服務工作處理程序) | onBackgroundMessage (自動顯示通知) |
onBackgroundMessage |
onBackgroundMessage (自動顯示通知) |
JavaScript 快速入門導覽課程範例示範了接收訊息所需的所有程式碼。
在網頁應用程式在前景運作時處理訊息
如要接收 onMessage
事件,您的應用程式必須在 firebase-messaging-sw.js
中定義 Firebase 訊息傳遞服務工作站。或者,您也可以透過 getToken(): Promise<string>
將現有的 Service Worker 提供給 SDK。
Web
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);
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();
當應用程式在前景運作時 (使用者目前正在瀏覽您的網頁),您可以直接在該頁面中接收資料和通知酬載。
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. import { getMessaging, onMessage } from "firebase/messaging"; const messaging = getMessaging(); onMessage(messaging, (payload) => { console.log('Message received. ', payload); // ... });
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); // ... });
在網頁應用程式在背景執行時處理訊息
當應用程式在背景執行時收到的所有訊息,都會觸發瀏覽器顯示通知。您可以在應用程式伺服器的傳送要求中,或在用戶端上使用 Service Worker 邏輯,指定此通知的選項,例如標題或點擊動作。
在傳送要求中設定通知選項
針對從應用程式伺服器傳送的通知訊息,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 處理通知。
如需通知與資料訊息之間的差異,請參閱「訊息類型」。
在 Service Worker 中設定通知選項
針對資料訊息,您可以在 Service Worker 中設定通知選項。首先,請在 Service Worker 中初始化應用程式:
Web
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);
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();
如要設定選項,請在 firebase-messaging-sw.js
中呼叫 onBackgroundMessage
。在此範例中,我們建立含有標題、內文和圖示欄位的通知。
Web
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); });
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); });
通知的最佳做法
如果您已熟悉網頁版推送訊息功能,則已經閱讀過廣泛指南,瞭解什麼是優質通知。對於透過網頁版 FCM 傳送通知的開發人員,最重要的考量重點是精確度和關聯性。請參考以下具體建議, 讓通知保持精確且切合需求:
- 使用圖示欄位傳送有意義的圖片。在許多用途中,這應該是使用者能立即認出的公司或應用程式標誌。或者,如果是即時通訊應用程式,它可能是傳送使用者的個人資料圖片。
- 使用標題欄位來表示郵件的精確性質。例如,「小傑已回覆」比「新訊息」更能精準傳達相關資訊。請勿將此寶貴空間用在公司或應用程式名稱中,請使用圖示達成此目的。
- 請勿使用通知標題或內文顯示網站名稱或網域;通知已包含網域名稱。
- 新增
fcm_options.link
,通常用於將使用者返回網頁應用程式,並在瀏覽器中聚焦。在極少數情況下,您需要傳達的所有資訊都可以放入通知中,您可能就不需要連結。