تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

حالة التطبيق	الإشعار	البيانات	كلاهما
لون الواجهة	`onMessage`	`onMessage`	`onMessage`
الخلفية (مشغّل الخدمات)	`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.
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-messaging.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": {
    "token": "eEz-Q2sG8nQ:APA91bHJQRT0JJ...",
    "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.
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-messaging.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، وعادةً ما يتم ربط المستخدم بتطبيق الويب وجلب موضع التركيز في المتصفح. في حالات نادرة يمكن فيها تضمين كل المعلومات التي تحتاج إلى إرسالها في الإشعار، قد لا تحتاج إلى رابط.