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

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

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

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

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

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

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

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

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

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

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

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

3. في علامة التبويب شهادات إشعارات الويب المستنِدة إلى Push API ، انقر على إنشاء زوج من المفاتيح.

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

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

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

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

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

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

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

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

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

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

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

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

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

الوصول إلى رمز التسجيل المميز

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

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

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 & Engagement > المراسلة.

4. أنشئ حملة.

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

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

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

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

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

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

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

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

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

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

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

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

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

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