بدء استخدام "المراسلة عبر السحابة الإلكترونية من 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، ما يتيح لك تحديد المستلِم لإشعاراتك.

إضافة حزمة تطوير البرامج FCM (SDK) وتهيئتها

1. إذا لم يسبق لك إجراء ذلك، ثبِّت حزمة تطوير البرامج (SDK) لـ Firebase JS وتهيئ 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 للويب وأردت الترقية إلى حزمة تطوير البرامج (SDK) 6.7.0 أو إصدار أحدث، عليك تفعيل FCM Registration API لمشروعك في Google Cloud Console. عند تفعيل واجهة برمجة التطبيقات، تأكَّد من تسجيل الدخول إلى Google Cloud Console باستخدام حساب Google نفسه الذي تستخدِمه لمنصة Firebase، وتأكَّد من اختيار المشروع الصحيح. تكون واجهة برمجة التطبيقات هذه مفعّلة تلقائيًا في المشاريع الجديدة التي تضيف حزمة تطوير البرامج FCM

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

تستخدِم واجهة الويب لخدمة FCM بيانات اعتماد الويب، المعروفة باسم مفاتيح Voluntary Application Server Identification أو VAPID، للسماح بطلبات الإرسال إلى خدمات إشعارات الويب الفورية المتوافقة. للاشتراك في الإشعارات الفورية، عليك ربط زوج من المفاتيح بمشروع Firebase. يمكنك إما إنشاء مفتاحا التشفير جديد أو استيراد مفتاحا التشفير الحالي من خلال Firebase Console.

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

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

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

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

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

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

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

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

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 لاستهداف الرسائل:

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 Console، انتقِل إلى DevOps والتفاعل > المراسلة

4. أنشئ حملة.

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

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

     2. انقر على رسائل إشعارات Firebase ، ثم على إنشاء.

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

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

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

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

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

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

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

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

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

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

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