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

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

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

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

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

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

3. در برگه گواهی‌های Web Push، روی تولید جفت کلید کلیک کنید.

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

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

اگر جفت کلید موجودی دارید که قبلاً با برنامه وب خود استفاده می‌کنید، می‌توانید آن را به 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 و تعامل > پیام‌رسانی بروید

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

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

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

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

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

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

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

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

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

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

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

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

مراحل بعدی

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

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