شروع به کار با «پیام‌رسانی ابریِ 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. در برگه گواهی‌های 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 & Engagement (عملیات توسعه و تعامل) > Messaging (پیام‌رسانی) بروید

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

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

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

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

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

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

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

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

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

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

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

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

مراحل بعدی

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

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