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

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

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

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

لتلقي حدث onMessage ، يجب أن يحدد تطبيقك عامل خدمة مراسلة Firebase في firebase-messaging-sw.js . بدلاً من ذلك ، يمكنك توفير عامل خدمة موجود لـ 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.
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

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

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

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

تحديد خيارات الإخطار في عامل الخدمة

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

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.
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 . في هذا المثال ، نقوم بإنشاء إشعار به حقول العنوان والجسم والأيقونة.

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