تلقّي الرسائل في تطبيقات الويب

اختيار المنصة:

iOS+ Android Web Flutter Unity C++

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

حالة التطبيق	إشعار	البيانات	كلاهما
المقدّمة	`onMessage`	`onMessage`	`onMessage`
الخلفية (مشغّل الخدمات)	`onBackgroundMessage` (يظهر إشعار العرض تلقائيًا)	`onBackgroundMessage`	`onBackgroundMessage` (يظهر إشعار العرض تلقائيًا)

يعرض نموذج التشغيل السريع في JavaScript كل الرموز المطلوبة لتلقّي الرسائل.

ملاحظة مهمة: يشير هذا الدليل إلى تهيئة Firebase في مشغّل خدمات. لاستخدام حزمة تطوير البرامج (SDK) النمطية في مشغّل خدمات، عليك تجميع ملف مشغّل الخدمات، لأنّ وحدات ES جديدة نسبيًا وغير متاحة على نطاق واسع (راجِع وحدات ES في مشغّلات الخدمات). إذا كنت لا تريد تجميع ملف مشغّل الخدمات، يمكنك استخدام واجهة برمجة التطبيقات المستندة إلى مساحة الاسم التي توفّرها حِزم التوافق. لمعرفة كيفية استخدام أدوات تجميع الوحدات مع Firebase، راجِع مقالة استخدام أدوات تجميع الوحدات مع Firebase.

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

لتلقّي حدث 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 fcm_options.link المفتاح. عادةً ما يتم ضبط هذا المفتاح على صفحة في تطبيق الويب:

    https://fcm.googleapis.com/v1/projects/<YOUR-PROJECT-ID>/messages:send
    Content-Type: application/json
    Authorization: bearer <YOUR-ACCESS-TOKEN>

    {
      "message": {
        ,
        "notification": {
          "title": "Background Message Title",
          "body": "Background message body"
        },
        "webpush": {
          "fcm_options": {
            "link": "https://dummypage.com"
          }
        }
      }
    }

إذا كانت قيمة الرابط تشير إلى صفحة مفتوحة حاليًا في علامة تبويب متصفّح، يؤدي النقر على الإشعار إلى عرض علامة التبويب هذه في المقدّمة. إذا لم تكن الصفحة مفتوحة من قبل، يؤدي النقر على الإشعار إلى فتح الصفحة في علامة تبويب جديدة.

بما أنّ رسائل البيانات لا تتيح fcm_options.link، ننصحك بإضافة حمولة إشعار إلى جميع رسائل البيانات. بدلاً من ذلك، يمكنك معالجة الإشعارات باستخدام برنامج الخدمة.

للحصول على شرح عن الفرق بين رسائل الإشعارات ورسائل البيانات، راجِع مقالة أنواع الرسائل.

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

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

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

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 للويب، أهم الاعتبارات هي الدقة والملاءمة. في ما يلي بعض التوصيات المحدّدة للحفاظ على دقة إشعاراتك وملاءمتها:

استخدِم الحقل icon لإرسال صورة ذات معنى. في العديد من حالات الاستخدام، يجب أن يكون هذا شعار شركة أو تطبيق يتعرّف عليه المستخدمون على الفور. أو، بالنسبة إلى تطبيق محادثة، قد تكون صورة الملف الشخصي للمستخدم المُرسِل.
استخدِم الحقل title للتعبير عن طبيعة الرسالة بدقة. على سبيل المثال، تنقل الرسالة "ردّ أحمد" معلومات أكثر دقة من "رسالة جديدة". لا تستخدِم هذه المساحة القيّمة لاسم شركتك أو تطبيقك، بل استخدِم الرمز لهذا الغرض.
لا تستخدِم عنوان الإشعار أو محتواه لعرض اسم موقعك الإلكتروني أو نطاقه، لأنّ الإشعارات تتضمّن اسم نطاقك.
أضِف fcm_options.link، وعادةً ما يكون ذلك لإعادة توجيه المستخدم إلى تطبيق الويب وعرضه في المقدّمة في المتصفح. في حالات نادرة يمكن فيها تضمين جميع المعلومات التي تحتاج إلى نقلها في الإشعار، قد لا تحتاج إلى رابط.