شروع به کار با «پیام‌رسانی ابریِ Firebase» در برنامه‌های وب

این راهنما نحوه شروع به کار با Firebase Cloud Messaging در برنامه‌های مشتری وب را شرح می‌دهد تا بتوانید پیام‌ها را به‌طور مطمئن ارسال کنید.

FCM JavaScript API به شما امکان می‌دهد پیام‌های اعلان را در برنامه‌های وب که در مرورگرهای پشتیبانی‌کننده Push API اجرا می‌شوند دریافت کنید. این شامل نسخه‌های مرورگر فهرست‌شده در این ماتریس پشتیبانی و افزونه‌های Chrome بااستفاده از Push API می‌شود.

«کیت توسعه نرم‌افزار» FCM فقط در صفحه‌هایی که ازطریق HTTPS ارائه می‌شوند پشتیبانی می‌شود. این امر به‌دلیل استفاده از کارگزاران خدمات است که فقط در سایت‌های HTTPS دردسترس هستند. اگر به ارائه‌دهنده نیاز دارید، Firebase App Hosting توصیه می‌شود و سطحی بدون هزینه برای میزبانی HTTPS در دامنه خودتان ارائه می‌دهد.

برای شروع کار با FCM JavaScript API، باید Firebase را به برنامه وب خود اضافه کنید و منطقی برای دسترسی به شناسه‌های نصب Firebase اضافه کنید که به شما امکان می‌دهد گیرنده اعلان‌هایتان را تعیین کنید.

افزودن و مقداردهی اولیه کیت توسعه نرم‌افزار FCM

1. اگر قبلاً این کار را نکرده‌اید، «کیت توسعه نرم‌افزار Firebase JS» را نصب کنید و Firebase را مقداردهی اولیه کنید.

2. ‫Firebase Cloud Messaging JS SDK را اضافه کنید و 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 برای وب استفاده می‌کنید و می‌خواهید به کیت توسعه نرم‌افزار ۶.۷.۰ یا جدیدتر ارتقا دهید، باید FCM Registration API را برای پروژه‌تان در کنسول Google Cloud فعال کنید. وقتی میانای برنامه‌سازی کاربردی را فعال می‌کنید، مطمئن شوید که با همان «حساب Google» که برای Firebase استفاده می‌کنید به سیستم کنسول Google Cloud وارد شده باشید و پروژه صحیح را انتخاب کنید. پروژه‌های جدید که FCM SDK را اضافه می‌کنند به‌طور پیش‌فرض این API را فعال دارند.

پیکربندی اطلاعات اعتباری وب با FCM

واسط وب FCM از اطلاعات اعتباری وب به نام «شناسایی سرور برنامه داوطلبانه» یا کلیدهای VAPID برای مجاز کردن درخواست‌های ارسال به سرویس‌های پشتیبانی‌شده اعلان‌های لحظه‌ای وب استفاده می‌کند. برای مشترک کردن برنامه‌تان در اعلان‌های لحظه‌ای، باید یک جفت کلید را با پروژه Firebase خودتان مرتبط کنید. می‌توانید یا جفت کلید جدیدی تولید کنید یا جفت کلید موجودتان را ازطریق کنسول Firebase وارد کنید.

تولید جفت کلید جدید

1. در کنسول Firebase، به settings تنظیمات > کلی بروید. سپس، روی زبانه پیام‌رسانی ابری کلیک کنید

2. به بخش پیکربندی وب بروید.

3. در برگه گواهینامه‌های «اعلان لحظه‌ای وب»، روی تولید جفت کلید کلیک کنید.

   کنسول اعلانی مبنی بر تولید جفت کلید نمایش می‌دهد و رشته کلید عمومی و تاریخ اضافه شدن آن را نمایش می‌دهد.

وارد کردن جفت کلید موجود

اگر جفت کلید موجودی دارید که ازقبل با برنامه وب خودتان استفاده می‌کنید، می‌توانید آن را به FCM وارد کنید تا بتوانید ازطریق میاناهای برنامه‌سازی کاربردی FCM به نمونه‌های برنامه وب موجودتان دسترسی پیدا کنید. برای وارد کردن کلیدها، باید دسترسی سطح مالک به پروژه Firebase داشته باشید. کلید عمومی و خصوصی موجودتان را در قالب کدبندی URL‑safe بااستفاده از Base64 وارد کنید:

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»

برای ثبت نمونه برنامه و بازیابی «شناسه نصب 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» شناسایی می‌شود.
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، به DevOps & Engagement (عملیات توسعه و تعامل) > Messaging (پیام‌رسانی) بروید

4. پویشی ایجاد کنید.

   • اگر این اولین پیام شما است:

     1. ایجاد اولین پویش را انتخاب کنید.

     2. پیام‌های اعلان Firebase را انتخاب کنید و سپس ایجاد را انتخاب کنید.

   • اگر قبلاً پویش‌هایی ایجاد کرده‌اید:

     1. در برگه پویش‌ها، پویش جدید را انتخاب کنید.

     2. روی اعلان‌ها کلیک کنید.

5. نوشتار پیام را وارد کنید.

6. ارسال پیام آزمایشی را از قاب سمت راست انتخاب کنید.

7. در فیلد برچسب‌گذاری‌شده افزودن کد ثبت FCM، کد ثبت خود را وارد کنید.

8. آزمایش را انتخاب کنید.

پس‌از انتخاب آزمایش، دستگاه مشتری هدف، با برنامه در پس‌زمینه، باید اعلان را دریافت کند.

مراحل بعدی

پس‌از تکمیل مراحل راه‌اندازی، در اینجا چند گزینه برای پیشبرد کار با FCM برای وب (جاوا اسکریپت) آورده شده است:

• ارسال پیام به دستگاه‌ها
• دریافت پیام‌ها در «کارخواه جاوا اسکریپت»
• ارسال پیام به موضوعات