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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. في علامة التبويب شهادات Web Push، ابحث عن نص الرابط التالي وانقر عليه: استيراد مفتاحَي تشفير حاليَّين.

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 Installation ID

لتسجيل نسخة التطبيق واسترداد معرّف تثبيت 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 Installation ID.
3. يتم تنشيط حدث pushsubscriptionchange.

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

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

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

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، انتقِل إلى DevOps & Engagement > المراسلة

4. أنشئ حملة.

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

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

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

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

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

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

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

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

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

8. اختَر اختبار.

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

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

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

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