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

בחירת פלטפורמה: iOS+‎ Android אינטרנט Flutter Unity C++‎


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

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

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

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

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

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

  2. מוסיפים את ה-JS SDK של Firebase Cloud Messaging ומפעילים את Firebase Cloud Messaging:

Web 

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

Web 

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, ולוודא שאתם בוחרים את הפרויקט הנכון. בפרויקטים חדשים שמוסיפים את ה-SDK של FCM, ה-API הזה מופעל כברירת מחדל.

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

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

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

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

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

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

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

ייבוא של זוג מפתחות קיים

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

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

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

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

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

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

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

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

ה-method‏ register(): Promise<void> מאפשרת ל-FCM להשתמש בפרטי הכניסה של מפתח ה-VAPID כשנשלחות בקשות להודעות לשירותי התראות שונים. משתמשים במפתח שיצרתם או ייבאתם לפי ההוראות במאמר הגדרת אישורים לאתרים באמצעות 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, צרו קובץ ריק עם השם הזה והציבו אותו ברמה הבסיסית (root) של הדומיין לפני הרישום. אפשר להוסיף תוכן משמעותי לקובץ בהמשך, בתהליך ההגדרה של הלקוח.

גישה למזהה ההתקנה ב-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);
});

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

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

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

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

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

Web

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

Web

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

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

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

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

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

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

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

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

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

      2. בוחרים באפשרות Firebase Notification messages (הודעות התראה של Firebase) ואז באפשרות Create (יצירה).

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

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

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

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

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

  7. בשדה הוספת טוקן רישום של FCM, מזינים את טוקן הרישום.

  8. לוחצים על בדיקה.

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

השלבים הבאים

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