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

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

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

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

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

إذا لم يسبق لك إجراء ذلك، ثبِّت حزمة تطوير البرامج (SDK) لمنصّة Firebase بلغة JavaScript وأعِد تهيئة Firebase.
أضِف حزمة تطوير البرامج (SDK) الخاصة بلغة JavaScript ‏(Firebase Cloud Messaging) وأعِد ضبطها على الوضع الأوّلي (Firebase Cloud Messaging):

Web

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);

Web

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

ضبط Web Credentials باستخدام FCM

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

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

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

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

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

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

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

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

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

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

const messaging = getMessaging();
// Add the public key generated from the 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، أنشئ ملفًا فارغًا بهذا الاسم وضعه في جذر نطاقك قبل استرداد الرمز المميز. يمكنك إضافة محتوى مفيد إلى الملف لاحقًا في عملية إعداد العميل.

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

Web

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

Web

// 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

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

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

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

أضِف وظائف إلى تطبيقك من أجل تلقّي الرسائل.
جرِّب أحد البرامج التعليمية التالية: إرسال رسالتك الأولى إلى تطبيق يعمل في الخلفية أو إرسال رسائل إلى أجهزة متعددة.
راجِع نموذجًا كاملاً على GitHub.
راجِع مرجع JavaScript.
يمكنك مشاهدة فيديو يشرح بالتفصيل كيفية تنفيذ واجهة برمجة التطبيقات.