קבלת הודעות בלקוח JavaScript

ההתנהגות של ההודעות משתנה בהתאם למיקום הדף: בחזית (במיקוד), ברקע, מוסתר מאחורי כרטיסיות אחרות או סגור לחלוטין. בכל המקרים, הדף צריך לטפל בקריאה החוזרת (callback) של onMessage, אבל במקרים של אירועים ברקע יכול להיות שתצטרכו לטפל גם בקריאה החוזרת של onBackgroundMessage או להגדיר את ההתראה כך שהמשתמש יוכל להעביר את אפליקציית האינטרנט לחזית.

מצב האפליקציה	התראה	נתונים	שניהם
חזית	`onMessage`	`onMessage`	`onMessage`
ברקע (service worker)	`onBackgroundMessage` (התראה מוצגת באופן אוטומטי)	`onBackgroundMessage`	`onBackgroundMessage` (התראה מוצגת באופן אוטומטי)

קוד לדוגמה למתחילים ב-JavaScript מציג את כל הקוד הנדרש לקבלת הודעות.

טיפול בהודעות כשאפליקציית האינטרנט בחזית

כדי לקבל את האירוע onMessage, האפליקציה צריכה להגדיר את העובד של שירות ההודעות של Firebase ב-firebase-messaging-sw.js. לחלופין, אפשר לספק ל-SDK שירות פעיל קיים דרך getToken(): Promise<string>.

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);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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.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

// 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

טיפול בהודעות כשאפליקציית האינטרנט פועלת ברקע

כל ההודעות שמתקבלות בזמן שהאפליקציה פועלת ברקע מפעילות התראה בדפדפן. אפשר לציין אפשרויות להודעה הזו, כמו כותרת או פעולת לחיצה, בבקשת השליחה משרת האפליקציה או באמצעות לוגיקה של שירות עובד בצד הלקוח.

הגדרת אפשרויות ההתראות בבקשה לשליחה

בהודעות התראה שנשלחות משרת האפליקציה, ה-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);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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.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

כדי להגדיר אפשרויות, צריך להתקשר למספר onBackgroundMessage ב-firebase-messaging-sw.js. בדוגמה הזו, אנחנו יוצרים התראה עם שדות של כותרת, גוף וסמלים.

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);
});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

שיטות מומלצות לשימוש בהתראות

אם אתם מכירים את התכונה 'הודעות דחיפה לאינטרנט', יכול להיות שכבר קראתם את ההנחיות הכלליות לגבי מהי התראה טובה. למפתחים ששולחים התראות דרך FCM לאינטרנט, השיקולים החשובים ביותר הם דיוק ורלוונטיות. ריכזנו כאן כמה המלצות ספציפיות שיעזרו לכם לוודא שההתראות שלכם מדויקות ורלוונטיות:

משתמשים בשדה הסמל כדי לשלוח תמונה בעלת משמעות. בתרחישים רבים, התמונה הזו צריכה להיות לוגו של החברה או האפליקציה שהמשתמשים שלכם מזהים מיד. לחלופין, באפליקציית צ'אט יכולה להופיע תמונת הפרופיל של המשתמש השולח.
כדאי להשתמש בשדה הכותרת כדי לתאר את אופי ההודעה בצורה מדויקת. לדוגמה, 'ג'ימי ענה' מעביר מידע מדויק יותר מאשר 'הודעה חדשה'. אל תשתמשו במרחב החשוב הזה בשביל שם החברה או האפליקציה – השתמשו בסמל למטרה הזו.
אל תשתמשו בכותרת או בגוף ההתראה כדי להציג את שם האתר או הדומיין שלכם. ההתראות כבר מכילות את שם הדומיין.
מוסיפים את fcm_options.link, בדרך כלל כדי לקשר את המשתמש בחזרה לאפליקציית האינטרנט ולהעביר את המיקוד לדף שלה בדפדפן. במקרים נדירים שבהם כל המידע שרוצים להעביר נכנס להודעה, יכול להיות שלא תצטרכו קישור.