تلقّي الرسائل في برنامج JavaScript

يختلف سلوك الرسائل استنادًا إلى ما إذا كانت الصفحة في المقدّمة (مميّزة) أو في الخلفية أو مخفية خلف علامات تبويب أخرى أو مغلقة تمامًا. في جميع الحالات، يجب أن تعالج الصفحة onMessage مكالمة الطلب، ولكن في حالات التشغيل في الخلفية، قد تحتاج أيضًا إلى معالجة onBackgroundMessage أو ضبط الإشعار المعروض للسماح للمستخدم بعرض تطبيق الويب في المقدّمة.

يوضّح نموذج البدء السريع لـ JavaScript جميع الرموز البرمجية المطلوبة لتلقّي الرسائل.

معالجة الرسائل عندما يكون تطبيق الويب في المقدّمة

لتلقّي الحدث onMessage، يجب أن يحدِّد تطبيقك عامل firebase-messaging-sw.js في خدمة المراسلة في Firebase. بدلاً من ذلك، يمكنك توفير عامل خدمة حالي لحزمة تطوير البرامج (SDK) من خلال getToken(): Promise<string>.

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

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

عندما يكون تطبيقك في المقدّمة (يعرض المستخدم حاليًا صفحة الويب)، يمكنك تلقّي بيانات وحمولات إعلام مباشرةً في الصفحة.

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

// 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 استخدام المفتاح 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، ننصحك بإضافة حمولة إشعار إلى جميع رسائل البيانات. بدلاً من ذلك، يمكنك التعامل مع الإشعارات باستخدام الخدمة العاملة.

للحصول على تفسير للفرق بين إشعارات الرسائل ورسائل البيانات، يُرجى الاطّلاع على أنواع الرسائل.

ضبط خيارات الإشعارات في الخدمة العاملة

بالنسبة إلى رسائل البيانات، يمكنك ضبط خيارات الإشعارات في الخدمة العاملة. أولاً، عليك إعداد تطبيقك في الخدمة العاملة:

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

// 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. في هذا المثال، ننشئ إشعارًا يتضمّن حقلَي العنوان والنص والرمز.

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

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، عادةً لإعادة ربط المستخدِم بتطبيق الويب وشدّ انتباهه إليه في المتصفّح. في الحالات النادرة التي يمكن فيها تضمين كل المعلومات التي تحتاج إلى إرسالها في الإشعار، قد لا تحتاج إلى رابط.