تلقي الرسائل في عميل JavaScript

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

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

يوضح نموذج التشغيل السريع لـ JavaScript جميع التعليمات البرمجية المطلوبة لتلقي الرسائل.

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

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

Web modular API

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

Web namespaced API

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

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

Web modular API

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

Web namespaced API

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

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

تؤدي جميع الرسائل المستلمة أثناء وجود التطبيق في الخلفية إلى ظهور إشعار العرض في المتصفح. يمكنك تحديد خيارات لهذا الإشعار، مثل العنوان أو إجراء النقر، إما في طلب الإرسال من خادم التطبيق الخاص بك، أو باستخدام منطق عامل الخدمة على العميل.

ضبط خيارات الإشعارات في طلب الإرسال

بالنسبة لرسائل الإعلام المرسلة من خادم التطبيق، تدعم FCM JavaScript API مفتاح 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 modular API

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

Web namespaced API

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

لتعيين الخيارات، اتصل بـ onBackgroundMessage في firebase-messaging-sw.js . في هذا المثال، قمنا بإنشاء إشعار يحتوي على حقول العنوان والنص والرمز.

Web modular API

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

Web namespaced API

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

أفضل الممارسات للإخطارات

إذا كنت معتادًا على المراسلة الفورية للويب، فربما تكون قد قرأت بالفعل الإرشادات العامة حول ما يقدم إشعارًا جيدًا . بالنسبة للمطورين الذين يرسلون الإشعارات من خلال FCM للويب، فإن أهم الاعتبارات هي الدقة والملاءمة. فيما يلي بعض التوصيات المحددة للحفاظ على دقة إشعاراتك وملاءمتها:

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