بدء استخدام "المراسلة عبر السحابة الإلكترونية من Firebase" في تطبيقات الويب

يوضّح هذا الدليل كيفية بدء استخدام Firebase Cloud Messaging في تطبيقات عميل الويب كي تتمكّن من إرسال الرسائل بشكل موثوق.

تتيح لك واجهة برمجة التطبيقات FCM JavaScript API تلقّي رسائل الإشعارات في تطبيقات الويب التي تعمل على المتصفّحات المتوافقة مع Push API. ويشمل ذلك إصدارات المتصفّح المُدرَجة في مصفوفة التوافق هذه وإضافات Chrome التي تستخدم Push API.

لا يتوافق حزمة تطوير البرامج (SDK) الخاصة بـ FCM إلا مع الصفحات التي يتم عرضها عبر بروتوكول HTTPS. ويرجع ذلك إلى استخدامها لبرامج الخدمة التي لا تتوفّر إلا على المواقع الإلكترونية التي تستخدم بروتوكول HTTPS. إذا كنت بحاجة إلى مزوّد خدمة، ننصحك باستخدام Firebase App Hosting الذي يوفّر مستوى مجانيًا لاستضافة HTTPS على نطاقك الخاص.

للبدء في استخدام واجهة برمجة التطبيقات FCM JavaScript API، عليك إضافة Firebase إلى تطبيق الويب وإضافة منطق للوصول إلى معرّفات تثبيت Firebase، ما يتيح لك تحديد المستلِم للإشعارات.

إضافة حزمة تطوير البرامج (SDK) الخاصة بـ FCM وإعدادها

1. إذا لم يسبق لك إجراء ذلك، ثبِّت حزمة تطوير البرامج (SDK) من Firebase لنظام التشغيل JavaScript وأعِد إعداد Firebase.

2. أضِف حزمة تطوير البرامج (SDK) Firebase Cloud Messaging JS وأعِد ضبطها على النحو التالي:Firebase Cloud Messaging

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);


// Initialize Firebase Cloud Messaging and get a reference to the service
const messaging = getMessaging(app);

import firebase from "firebase/compat/app";
import "firebase/compat/messaging";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);


// Initialize Firebase Cloud Messaging and get a reference to the service
const messaging = firebase.messaging();

إذا كنت تستخدم FCM على الويب وأردت الترقية إلى الإصدار 6.7.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK)، عليك تفعيل واجهة برمجة التطبيقات لتسجيل FCM لمشروعك في وحدة تحكّم Google Cloud. عند تفعيل واجهة برمجة التطبيقات، تأكَّد من تسجيل الدخول إلى وحدة تحكّم Google Cloud باستخدام حساب Google نفسه الذي تستخدمه في Firebase، وتأكَّد من اختيار المشروع الصحيح. يتم تفعيل واجهة برمجة التطبيقات هذه تلقائيًا في المشاريع الجديدة التي تضيف حزمة تطوير البرامج (SDK) FCM.

ضبط بيانات اعتماد الويب باستخدام FCM

تستخدم واجهة الويب FCM بيانات اعتماد الويب التي تُعرف باسم "التعريف الطوعي لخادم التطبيق" أو مفاتيح VAPID، وذلك للسماح بإرسال الطلبات إلى خدمات الإشعارات الفورية على الويب المتوافقة. للاشتراك في الإشعارات الفورية، عليك ربط زوج من المفاتيح بمشروعك على Firebase. يمكنك إنشاء زوج مفاتيح جديد أو استيراد زوج المفاتيح الحالي من خلال وحدة تحكّم Firebase.

إنشاء زوج مفاتيح جديد

1. في وحدة تحكّم Firebase، انتقِل إلى settings الإعدادات > الإعدادات العامة. بعد ذلك، انقر على علامة التبويب Cloud Messaging.

2. انتقِل إلى قسم إعدادات الويب.

3. في علامة التبويب شهادات الإشعارات الفورية على الويب، انقر على إنشاء مفتاحَي تشفير.

   تعرض وحدة التحكّم إشعارًا بأنّه تم إنشاء مفتاحَي التشفير، وتعرض سلسلة المفتاح العام وتاريخ الإضافة.

استيراد زوج مفاتيح حالي

إذا كان لديك زوج مفاتيح حالي تستخدمه مع تطبيق الويب، يمكنك استيراده إلى FCM حتى تتمكّن من الوصول إلى مثيلات تطبيق الويب الحالي من خلال واجهات برمجة التطبيقات FCM. لاستيراد المفاتيح، يجب أن يكون لديك إذن وصول على مستوى المالك إلى مشروع Firebase. استورِد المفتاحَين العام والخاص الحاليَين بتنسيق base64 المشفّر الآمن لعناوين URL:

1. في وحدة تحكّم Firebase، انتقِل إلى settings الإعدادات > الإعدادات العامة. بعد ذلك، انقر على علامة التبويب Cloud Messaging.

2. انتقِل إلى قسم إعدادات الويب.

3. في علامة التبويب شهادات الإشعارات الفورية على الويب، ابحث عن نص الرابط استيراد زوج مفاتيح حالي وانقر عليه.

4. في مربّع الحوار استيراد زوج مفاتيح، أدخِل المفتاحَين العام والخاص في الحقلَين المناسبَين، ثم انقر على استيراد.

   تعرض وحدة التحكّم سلسلة المفتاح العام وتاريخ الإضافة.

للحصول على تعليمات حول كيفية إضافة المفتاح إلى تطبيقك، اطّلِع على ضبط بيانات اعتماد الويب في تطبيقك. لمزيد من المعلومات حول تنسيق المفاتيح وكيفية إنشائها، اطّلِع على مفاتيح خادم التطبيق.

ضبط بيانات اعتماد الويب في تطبيقك

تتيح الطريقة register(): Promise<void> لـ FCM استخدام بيانات اعتماد مفتاح VAPID عند إرسال طلبات الرسائل إلى خدمات الإشعارات المختلفة. باستخدام المفتاح الذي أنشأته أو استوردته وفقًا للتعليمات الواردة في إعداد بيانات الاعتماد على الويب باستخدام FCM، أضِفه إلى الرمز بعد استرداد عنصر الرسائل:

import { getMessaging, register } from "firebase/messaging";

const messaging = getMessaging();
// Add the public key generated from the Firebase console here.
register(messaging, {vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu"});

طلب إذن إرسال الإشعارات وإعداد مشغّل الخدمات

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

function requestPermission() {
  console.log('Requesting permission...');
  Notification.requestPermission().then((permission) => {
    if (permission === 'granted') {
      console.log('Notification permission granted.');
    }
  });
}

يتطلّب FCM ملف firebase-messaging-sw.js. إذا لم يكن لديك ملف firebase-messaging-sw.js، أنشئ ملفًا فارغًا بهذا الاسم وضعه في جذر نطاقك قبل التسجيل. يمكنك إضافة محتوى مفيد إلى الملف لاحقًا أثناء عملية إعداد العميل.

الوصول إلى معرّف التثبيت في Firebase

لتسجيل نسخة التطبيق واسترداد رقم تعريف التثبيت في Firebase (FID) لاستهداف الرسائل، اتّبِع الخطوات التالية:

import { getMessaging, onRegistered, register } from "firebase/messaging";

const messaging = getMessaging();

// 1. Implement callback to receive the Firebase installation ID upon registration.
// This is triggered every time a manual register() finishes, a FID change
// is detected, or a pushsubscriptionchange event is fired.
onRegistered(messaging, (installationId) => {
  console.log('Registered installation ID:', installationId);

  // Send the Firebase Installation ID to your app server and update the UI if needed.
  sendRegistrationToServer(installationId);
});

// 2. You can also manually trigger registration (recommended on app startup)
register(messaging, {
  vapidKey: '<YOUR_PUBLIC_VAPID_KEY_HERE>'
}).then(() => {
  // Success! The Firebase Installation ID can be used to target messages to this app
  // instance and will be delivered asynchronously to your onRegistered() callback.
}).catch((err) => {
  console.error('An error occurred while registering', err);
});
messaging_register.js

يتم تشغيل دالة ردّ الاتصال onRegistered في ثلاث حالات:

1. في كل مرة تنتهي فيها مكالمة register() يدوية.
2. تم رصد تغيير في رقم تعريف عملية التثبيت في Firebase.
3. يتم تشغيل حدث pushsubscriptionchange.

بعد الحصول على معرّف تثبيت Firebase، أرسِله إلى خادم تطبيقك وخزِّنه باستخدام طريقتك المفضّلة.

الوصول إلى رمز التسجيل (متوقّف نهائيًا)

لاسترداد الرمز المميّز الحالي، اتّبِع الخطوات التالية:

import { getMessaging, getToken } from "firebase/messaging";

// Get registration token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
const messaging = getMessaging();
getToken(messaging, { vapidKey: '<YOUR_PUBLIC_VAPID_KEY_HERE>' }).then((currentToken) => {
  if (currentToken) {
    // Send the token to your server and update the UI if necessary
    // ...
  } else {
    // Show permission request UI
    console.log('No registration token available. Request permission to generate one.');
    // ...
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  // ...
});
messaging_get_token.js

// Get registration token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
messaging.getToken({ vapidKey: '<YOUR_PUBLIC_VAPID_KEY_HERE>' }).then((currentToken) => {
  if (currentToken) {
    // Send the token to your server and update the UI if necessary
    // ...
  } else {
    // Show permission request UI
    console.log('No registration token available. Request permission to generate one.');
    // ...
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  // ...
});
index.js

بعد الحصول على الرمز المميّز، أرسِله إلى خادم تطبيقك وخزِّنه باستخدام طريقتك المفضّلة.

إرسال رسالة إشعار تجريبية

1. ثبِّت التطبيق وشغِّله على جهاز الاختبار. على أجهزة Apple، عليك قبول طلب الإذن بتلقّي إشعارات عن بُعد.

2. تأكَّد من أنّ التطبيق يعمل في الخلفية على الجهاز.

3. في وحدة تحكّم Firebase، انتقِل إلى عمليات تطوير البرامج وإشراك المستخدمين > المراسلة

4. أنشئ حملة.

   • إذا كانت هذه هي رسالتك الأولى:

     1. انقر على إنشاء حملتك الأولى.

     2. اختَر رسائل إشعارات Firebase، ثمّ اختَر إنشاء.

   • إذا سبق لك إنشاء حملات:

     1. في علامة التبويب الحملات، انقر على حملة جديدة.

     2. انقر على الإشعارات.

5. أدخِل نص الرسالة.

6. انقر على إرسال رسالة اختبار من اللوحة اليمنى.

7. في الحقل الذي يحمل التصنيف إضافة رمز مميّز للتسجيل في FCM، أدخِل رمز التسجيل.

8. انقر على اختبار.

بعد اختيار اختبار، من المفترض أن يتلقّى جهاز العميل المستهدَف الإشعار مع تشغيل التطبيق في الخلفية.

الخطوات التالية

بعد إكمال خطوات الإعداد، إليك بعض الخيارات للمضي قدمًا في استخدام FCM للويب (JavaScript):

• إرسال رسائل إلى الأجهزة
• تلقّي الرسائل في برنامج JavaScript
• إرسال الرسائل إلى المواضيع