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

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

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

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

إضافة حزمة تطوير البرامج (SDK) لنظام التشغيل FCM وإعدادها

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

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

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

إنشاء مفتاحَي تشفير جديدَين

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

استيراد مفتاحَي تشفير حاليَين

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

1. افتح علامة التبويب الرسائل عبر السحابة الإلكترونية في لوحة الإعدادات لوحدة تحكّم Firebase وانتقِل إلى قسم إعدادات الويب.
2. في علامة التبويب شهادات Web Push، ابحث عن نص الرابط واختَره، وهو "استيراد مفتاحَي تشفير حاليين".
3. في مربّع الحوار استيراد مفتاحَي تشفير، أدخِل مفتاحَي التشفير العام والخاص في الحقول المقابلة وانقر على استيراد. تعرض وحدة التحكّم سلسلة المفتاح العام وتاريخ إضافته.

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

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

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

لاسترداد الرمز المميّز الحالي:

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

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

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

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

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