איך מתחילים להשתמש בהעברת הודעות בענן ב-Firebase באפליקציות אינטרנט

במדריך הזה מוסבר איך להתחיל להשתמש ב-Firebase Cloud Messaging באפליקציות של לקוחות אינטרנט כדי לשלוח הודעות בצורה מהימנה.

‫FCM JavaScript API מאפשר לקבל הודעות התראה באפליקציות אינטרנט שפועלות בדפדפנים שתומכים ב-Push API. התמיכה כוללת את גרסאות הדפדפן שמפורטות בטבלת התמיכה ואת תוספי Chrome שמשתמשים ב-Push API.

ערכת ה-SDK‏ FCM נתמכת רק בדפים שמוצגים באמצעות HTTPS. הסיבה לכך היא השימוש ב-service workers, שזמינים רק באתרים עם HTTPS. אם אתם צריכים ספק, מומלץ להשתמש ב-Firebase App Hosting, שמספק רמה ללא עלות לאירוח HTTPS בדומיין שלכם.

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

הוספה ואתחול של FCM SDK

1. אם עדיין לא עשיתם זאת, תצטרכו להתקין את Firebase JS SDK ולהפעיל את Firebase.

2. מוסיפים את Firebase Cloud Messaging JS SDK ומאתחלים את Firebase Cloud Messaging:

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

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);


// Initialize Firebase Cloud Messaging and get a reference to the service
const messaging = getMessaging(app);

import firebase from "firebase/compat/app";
import "firebase/compat/messaging";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);


// Initialize Firebase Cloud Messaging and get a reference to the service
const messaging = firebase.messaging();

אם אתם משתמשים ב-FCM לאתרים ורוצים לשדרג ל-SDK בגרסה 6.7.0 ואילך, אתם צריכים להפעיל את FCM Registration API בפרויקט שלכם במסוף Google Cloud. כשמפעילים את ה-API, צריך לוודא שאתם מחוברים למסוף Google Cloud באמצעות אותו חשבון Google שבו אתם משתמשים ב-Firebase, ולוודא שבחרתם את הפרויקט הנכון. בפרויקטים חדשים שמוסיפים את FCM SDK, ה-API הזה מופעל כברירת מחדל.

הגדרת פרטי כניסה לאתרים באמצעות FCM

ממשק האינטרנט של FCM משתמש בפרטי כניסה לאינטרנט שנקראים Voluntary Application Server Identification (זיהוי שרת אפליקציה מרצון), או מפתחות VAPID, כדי לאשר בקשות שליחה לשירותי הודעות פוש נתמכים באינטרנט. כדי להירשם לקבלת הודעות פוש באפליקציה, צריך לשייך זוג מפתחות לפרויקט Firebase. אפשר ליצור זוג מפתחות חדש או לייבא זוג מפתחות קיים דרך מסוף Firebase.

יצירת זוג מפתחות חדש

1. במסוף Firebase, עוברים אל settings הגדרות > כללי. ואז לוחצים על הכרטיסייה העברת הודעות בענן.

2. עוברים לקטע הגדרת אינטרנט.

3. בכרטיסייה Web Push certificates, לוחצים על Generate Key Pair.

   במסוף מוצגת הודעה שזוג המפתחות נוצר, ומוצגת מחרוזת המפתח הציבורי והתאריך שבו הוא נוסף.

ייבוא של צמד מפתחות קיים

אם יש לכם צמד מפתחות קיים שאתם כבר משתמשים בו באפליקציית האינטרנט, אתם יכולים לייבא אותו אל FCM כדי שתוכלו להגיע למופעים הקיימים של אפליקציית האינטרנט באמצעות ממשקי ה-API של FCM. כדי לייבא מפתחות, צריכה להיות לכם גישה ברמת הבעלים לפרויקט Firebase. מייבאים את המפתח הציבורי והמפתח הפרטי הקיימים בפורמט מקודד מסוג Base64 שמתאים לכתובות URL:

1. במסוף Firebase, עוברים אל settings הגדרות > כללי. ואז לוחצים על הכרטיסייה העברת הודעות בענן.

2. עוברים לקטע הגדרת אינטרנט.

3. בכרטיסייה Web Push certificates (אישורים של הודעות פוש באינטרנט), מאתרים את טקסט הקישור import an existing key pair (ייבוא של צמד מפתחות קיים) ולוחצים עליו.

4. בתיבת הדו-שיח Import a key pair (ייבוא זוג מפתחות), מזינים את המפתחות הציבורי והפרטי בשדות המתאימים ולוחצים על Import (ייבוא).

   במסוף מוצגים מחרוזת המפתח הציבורי והתאריך שבו הוא נוסף.

הוראות להוספת המפתח לאפליקציה מופיעות במאמר בנושא הגדרת פרטי כניסה לאתר באפליקציה. מידע נוסף על פורמט המפתחות ועל אופן היצירה שלהם מופיע במאמר בנושא מפתחות של שרת האפליקציה.

הגדרת פרטי כניסה לאתר באפליקציה

השיטה register(): Promise<void> מאפשרת ל-FCM להשתמש בפרטי הכניסה של מפתח VAPID כששולחים בקשות להודעות לשירותי Push שונים. משתמשים במפתח שיצרתם או ייבאתם בהתאם להוראות שבמאמר הגדרת פרטי כניסה לאינטרנט באמצעות FCM, ומוסיפים אותו לקוד אחרי שליפת אובייקט ההודעות:

import { getMessaging, register } from "firebase/messaging";

const messaging = getMessaging();
// Add the public key generated from the Firebase console here.
register(messaging, {vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu"});

בקשת הרשאה לשליחת התראות והגדרת קובץ השירות (service worker)

כשרוצים לטרגט מופע של אפליקציה באמצעות FCM, קודם צריך לבקש מהמשתמש הרשאות לשליחת התראות באמצעות Notification.requestPermission(). כשקוראים לפונקציה כמו שמוצג, היא מחזירה את מצב ההרשאה אם היא ניתנה:

function requestPermission() {
  console.log('Requesting permission...');
  Notification.requestPermission().then((permission) => {
    if (permission === 'granted') {
      console.log('Notification permission granted.');
    }
  });
}

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

גישה למזהה ההתקנה ב-Firebase

כדי לרשום את מופע האפליקציה ולאחזר את מזהה ההתקנה ב-Firebase‏ (FID) לצורך טירגוט הודעות:

import { getMessaging, onRegistered, register } from "firebase/messaging";

const messaging = getMessaging();

// 1. Implement callback to receive the Firebase installation ID upon registration.
// This is triggered every time a manual register() finishes, a FID change
// is detected, or a pushsubscriptionchange event is fired.
onRegistered(messaging, (installationId) => {
  console.log('Registered installation ID:', installationId);

  // Send the Firebase Installation ID to your app server and update the UI if needed.
  sendRegistrationToServer(installationId);
});

// 2. You can also manually trigger registration (recommended on app startup)
register(messaging, {
  vapidKey: '<YOUR_PUBLIC_VAPID_KEY_HERE>'
}).then(() => {
  // Success! The Firebase Installation ID can be used to target messages to this app
  // instance and will be delivered asynchronously to your onRegistered() callback.
}).catch((err) => {
  console.error('An error occurred while registering', err);
});
messaging_register.js

הקריאה החוזרת onRegistered מופעלת בשלושה תרחישים:

1. בכל פעם ששיחה ידנית register() מסתיימת.
2. זוהה שינוי במזהה ההתקנה של Firebase.
3. מופעל אירוע pushsubscriptionchange.

אחרי שמקבלים את מזהה ההתקנה של Firebase, שולחים אותו לשרת האפליקציה ומאחסנים אותו בשיטה המועדפת.

גישה לטוקן הרישום (יצא משימוש)

כדי לאחזר את הטוקן הנוכחי:

import { getMessaging, getToken } from "firebase/messaging";

// Get registration token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
const messaging = getMessaging();
getToken(messaging, { vapidKey: '<YOUR_PUBLIC_VAPID_KEY_HERE>' }).then((currentToken) => {
  if (currentToken) {
    // Send the token to your server and update the UI if necessary
    // ...
  } else {
    // Show permission request UI
    console.log('No registration token available. Request permission to generate one.');
    // ...
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  // ...
});
messaging_get_token.js

// Get registration token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
messaging.getToken({ vapidKey: '<YOUR_PUBLIC_VAPID_KEY_HERE>' }).then((currentToken) => {
  if (currentToken) {
    // Send the token to your server and update the UI if necessary
    // ...
  } else {
    // Show permission request UI
    console.log('No registration token available. Request permission to generate one.');
    // ...
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  // ...
});
index.js

אחרי שמקבלים את הטוקן, שולחים אותו לשרת האפליקציה ומאחסנים אותו בשיטה המועדפת.

שליחת הודעת בדיקה

1. מתקינים את האפליקציה ומפעילים אותה במכשיר היעד. במכשירי אפל, צריך לאשר את בקשת ההרשאה לקבלת התראות מרחוק.

2. בודקים שהאפליקציה פועלת ברקע במכשיר.

3. במסוף Firebase, עוברים אל DevOps & Engagement > Messaging.

4. יוצרים קמפיין.

   • אם זו ההודעה הראשונה שלכם:

     1. לוחצים על יצירת הקמפיין הראשון.

     2. בוחרים באפשרות הודעות התראה של Firebase ואז באפשרות יצירה.

   • אם יצרתם בעבר קמפיינים:

     1. בכרטיסייה קמפיינים, לוחצים על קמפיין חדש.

     2. לוחצים על התראות.

5. מזינים את הטקסט של ההודעה.

6. בחלונית השמאלית, לוחצים על שליחת הודעת בדיקה.

7. בשדה עם התווית Add an FCM registration token (הוספת טוקן רישום של FCM), מזינים את טוקן הרישום.

8. בוחרים באפשרות בדיקה.

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

השלבים הבאים

אחרי שמסיימים את שלבי ההגדרה, יש כמה אפשרויות להמשך השימוש ב-FCM לאתרים (JavaScript):

• שליחת הודעות למכשירים
• קבלת הודעות בלקוח JavaScript
• שליחת הודעות לנושאים