Odbieraj wiadomości w kliencie JavaScript

Zachowanie wiadomości różni się w zależności od tego, czy strona znajduje się na pierwszym planie (jest skupiona), czy w tle, ukryta za innymi zakładkami, czy też całkowicie zamknięta. We wszystkich przypadkach strona musi obsługiwać wywołanie zwrotne onMessage , ale w przypadkach działających w tle może być konieczna obsługa onBackgroundMessage lub skonfigurowanie powiadomienia wyświetlania, aby umożliwić użytkownikowi przeniesienie aplikacji internetowej na pierwszy plan.

Stan aplikacji Powiadomienie Dane Obydwa
Pierwszoplanowy onMessage onMessage onMessage
Tło (pracownik serwisu) onBackgroundMessage (powiadomienie wyświetlane automatycznie) onBackgroundMessage onBackgroundMessage (powiadomienie wyświetlane automatycznie)

Przykładowy przewodnik szybkiego startu JavaScript demonstruje cały kod wymagany do odbierania komunikatów.

Obsługuj wiadomości, gdy aplikacja internetowa jest na pierwszym planie

Aby otrzymać zdarzenie onMessage , aplikacja musi zdefiniować pracownika usługi przesyłania wiadomości Firebase w firebase-messaging-sw.js . Alternatywnie możesz udostępnić istniejącego procesu roboczego usługi do zestawu SDK za pomocą getToken(): Promise<string> .

Web modular API

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
const firebaseApp = initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = getMessaging(firebaseApp);

Web namespaced API

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here. Other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

Gdy Twoja aplikacja znajduje się na pierwszym planie (użytkownik aktualnie przegląda Twoją stronę internetową), możesz odbierać dane i powiadomienia bezpośrednio na stronie.

Web modular API

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.onBackgroundMessage` handler.
import { getMessaging, onMessage } from "firebase/messaging";

const messaging = getMessaging();
onMessage(messaging, (payload) => {
  console.log('Message received. ', payload);
  // ...
});

Web namespaced API

// Handle incoming messages. Called when:
// - a message is received while the app has focus
// - the user clicks on an app notification created by a service worker
//   `messaging.onBackgroundMessage` handler.
messaging.onMessage((payload) => {
  console.log('Message received. ', payload);
  // ...
});

Obsługuj wiadomości, gdy aplikacja internetowa działa w tle

Wszystkie wiadomości otrzymane, gdy aplikacja działa w tle, powodują wyświetlenie powiadomienia w przeglądarce. Możesz określić opcje tego powiadomienia, takie jak tytuł lub akcja kliknięcia, w żądaniu wysłania z serwera aplikacji lub przy użyciu logiki procesu roboczego usługi na kliencie.

Ustawianie opcji powiadomień w żądaniu wysłania

W przypadku komunikatów powiadomień wysyłanych z serwera aplikacji interfejs API JavaScript FCM obsługuje klucz fcm_options.link . Zazwyczaj jest to ustawione na stronę w aplikacji internetowej:

https://fcm.googleapis.com//v1/projects/<YOUR-PROJECT-ID>/messages:send
Content-Type: application/json
Authorization: bearer <YOUR-ACCESS-TOKEN>

{
  "message": {
    "token": "eEz-Q2sG8nQ:APA91bHJQRT0JJ...",
    "notification": {
      "title": "Background Message Title",
      "body": "Background message body"
    },
    "webpush": {
      "fcm_options": {
        "link": "https://dummypage.com"
      }
    }
  }
}

Jeśli wartość linku wskazuje stronę, która jest już otwarta w karcie przeglądarki, kliknięcie powiadomienia powoduje wyświetlenie tej karty na pierwszym planie. Jeśli strona nie jest jeszcze otwarta, kliknięcie powiadomienia otwiera stronę w nowej karcie.

Ponieważ wiadomości danych nie obsługują fcm_options.link , zaleca się dodanie ładunku powiadomienia do wszystkich wiadomości danych. Alternatywnie możesz obsługiwać powiadomienia za pomocą Service Workera.

Aby poznać różnicę między powiadomieniami a wiadomościami z danymi, zobacz Typy wiadomości .

Ustawianie opcji powiadomień w service workerze

W przypadku wiadomości zawierających dane możesz ustawić opcje powiadomień w procesie roboczym usługi. Najpierw zainicjuj aplikację w Service Worker:

Web modular API

import { initializeApp } from "firebase/app";
import { getMessaging } from "firebase/messaging/sw";

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
const firebaseApp = initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = getMessaging(firebaseApp);

Web namespaced API

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here. Other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/8.10.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
  apiKey: 'api-key',
  authDomain: 'project-id.firebaseapp.com',
  databaseURL: 'https://project-id.firebaseio.com',
  projectId: 'project-id',
  storageBucket: 'project-id.appspot.com',
  messagingSenderId: 'sender-id',
  appId: 'app-id',
  measurementId: 'G-measurement-id',
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

Aby ustawić opcje, wywołaj onBackgroundMessage w firebase-messaging-sw.js . W tym przykładzie tworzymy powiadomienie z polami tytułu, treści i ikony.

Web modular API

import { getMessaging } from "firebase/messaging/sw";
import { onBackgroundMessage } from "firebase/messaging/sw";

const messaging = getMessaging();
onBackgroundMessage(messaging, (payload) => {
  console.log('[firebase-messaging-sw.js] Received background message ', payload);
  // Customize notification here
  const notificationTitle = 'Background Message Title';
  const notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  self.registration.showNotification(notificationTitle,
    notificationOptions);
});

Web namespaced API

messaging.onBackgroundMessage((payload) => {
  console.log(
    '[firebase-messaging-sw.js] Received background message ',
    payload
  );
  // Customize notification here
  const notificationTitle = 'Background Message Title';
  const notificationOptions = {
    body: 'Background Message body.',
    icon: '/firebase-logo.png'
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});

Najlepsze praktyki dotyczące powiadomień

Jeśli znasz wiadomości push w Internecie, być może zapoznałeś się już z ogólnymi wytycznymi dotyczącymi dobrego powiadomienia . Dla programistów wysyłających powiadomienia za pośrednictwem FCM for Web najważniejsze są precyzja i trafność. Oto kilka konkretnych zaleceń dotyczących dbałości o precyzję i trafność powiadomień:

  • Użyj pola ikony, aby wysłać znaczący obraz. W wielu przypadkach powinno to być logo firmy lub aplikacji, które użytkownicy natychmiast rozpoznają. Lub w przypadku aplikacji do czatu może to być zdjęcie profilowe użytkownika wysyłającego.
  • Użyj pola tytułu, aby wyrazić dokładny charakter wiadomości. Na przykład „Jimmy odpowiedział” przekazuje bardziej precyzyjne informacje niż „Nowa wiadomość”. Nie używaj tego cennego miejsca na nazwę swojej firmy lub aplikacji — użyj w tym celu ikony.
  • Nie używaj tytułu ani treści powiadomienia do wyświetlania nazwy witryny lub domeny; powiadomienia zawierają już nazwę Twojej domeny.
  • Dodaj fcm_options.link , zwykle po to, aby połączyć użytkownika z powrotem z aplikacją internetową i ustawić jej ostrość w przeglądarce. W rzadkich przypadkach, gdy w powiadomieniu mieszczą się wszystkie informacje, które należy przekazać, link może nie być potrzebny.