يختلف سلوك الرسائل استنادًا إلى
ما إذا كانت الصفحة في المقدّمة (مميّزة) أو في الخلفية أو مخفية
خلف علامات تبويب أخرى أو مغلقة تمامًا. في جميع الحالات، يجب أن تعالج الصفحة onMessage
مكالمة الطلب، ولكن في حالات التشغيل في الخلفية، قد تحتاج أيضًا إلى معالجة onBackgroundMessage
أو ضبط الإشعار المعروض للسماح للمستخدم بعرض
تطبيق الويب في المقدّمة.
حالة التطبيق | إشعار | البيانات | كلاهما |
---|---|---|---|
لون الواجهة | onMessage |
onMessage |
onMessage |
في الخلفية (مشغّل الخدمات) | onBackgroundMessage (يتم عرض الإشعار تلقائيًا) |
onBackgroundMessage |
onBackgroundMessage (يتم عرض الإشعار تلقائيًا) |
يوضّح نموذج البدء السريع لـ JavaScript جميع الرموز البرمجية المطلوبة لتلقّي الرسائل.
معالجة الرسائل عندما يكون تطبيق الويب في المقدّمة
لتلقّي الحدث onMessage
، يجب أن يحدِّد تطبيقك عامل firebase-messaging-sw.js
في
خدمة المراسلة في Firebase.
بدلاً من ذلك، يمكنك توفير عامل خدمة حالي لحزمة تطوير البرامج (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);
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();
عندما يكون تطبيقك في المقدّمة (يعرض المستخدم حاليًا صفحة الويب)، يمكنك تلقّي بيانات وحمولات إعلام مباشرةً في الصفحة.
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); // ... });
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); // ... });
معالجة الرسائل عندما يكون تطبيق الويب في الخلفية
تؤدي جميع الرسائل الواردة عندما يكون التطبيق في الخلفية إلى عرض إشعار في المتصفّح. يمكنك تحديد خيارات لهذا الإشعار، مثل العنوان أو إجراء النقر، إما في طلب الإرسال من خادم تطبيقك، أو باستخدام منطق الخدمة العاملة على العميل.
ضبط خيارات الإشعار في طلب الإرسال
بالنسبة إلى رسائل الإشعارات المُرسَلة من خادم التطبيق، تتيح 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);
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();
لضبط الخيارات، يُرجى الاتصال على 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); });
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); });
أفضل الممارسات المتعلّقة بالإشعارات
إذا كنت على دراية بالرسائل الفورية على الويب، من المحتمل أنّك اطّلعت من قبل على الإرشادات العامة حول العوامل التي تجعل الإشعار جيدًا. بالنسبة إلى المطوّرين الذين يرسلون الإشعارات من خلال FCM للويب، فإنّ أهم العوامل التي يجب مراعاتها هي الدقة والصلة بالموضوع. في ما يلي بعض الاقتراحات المحدّدة للحفاظ على دقة إشعاراتك ومدى ملاءمتها:
- استخدِم حقل الرمز لإرسال صورة ذات معنى. في العديد من حالات الاستخدام، يجب أن يكون هذا الشعار هو شعار الشركة أو التطبيق الذي يتعرّف عليه المستخدمون على الفور. أمّا في حالة تطبيق محادثة، فقد تكون صورة الملف الشخصي للمستخدم المُرسِل.
- استخدِم حقل العنوان للتعبير عن طبيعة الرسالة بدقة. على سبيل المثال، ينقل الحدث "ردّ جمال" معلومات أكثر دقة من الحدث "رسالة جديدة". لا تستخدِم هذه المساحة القيّمة لاسم شركتك أو تطبيقك، بل استخدِم الرمز للقيام بهذا الغرض.
- لا تستخدِم عنوان الإشعار أو نصه لعرض اسم موقعك الإلكتروني أو نطاقك، لأنّ الإشعارات تتضمّن اسم نطاقك.
- أضِف
fcm_options.link
، عادةً لإعادة ربط المستخدِم بتطبيق الويب وشدّ انتباهه إليه في المتصفّح. في حالات نادرة يمكن فيها تضمين كل المعلومات التي تحتاج إلى إرسالها في الإشعار، قد لا تحتاج إلى رابط.