Odbieranie wiadomości w kliencie JavaScript

Działania wiadomości różnią się w zależności od tego, czy strona jest na pierwszym planie (czyli jest aktywna), czy w tle, ukryta za innymi kartami, czy całkowicie zamknięta. W każdym przypadku strona musi obsługiwać wywołanie onMessage, ale w przypadku działania w tle może być też konieczne obsłużenie wywołania onBackgroundMessage lub skonfigurowanie powiadomienia wyświetlanego w celu umożliwienia użytkownikowi przeniesienia aplikacji internetowej na pierwszy plan.

Stan aplikacji Powiadomienie Dane Oba rodzaje
Pierwszy plan onMessage onMessage onMessage
W tle (worker) onBackgroundMessage (powiadomienie wyświetlane automatycznie) onBackgroundMessage onBackgroundMessage (powiadomienie wyświetlane automatycznie)

Krótkie wprowadzenie do JavaScriptu pokazuje cały kod wymagany do odbierania wiadomości.

.

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

Aby otrzymywać zdarzenie onMessage, aplikacja musi definiować skrypt usługi przesyłania wiadomości Firebase w firebase-messaging-sw.js. Możesz też podać istniejącemu pracownikowi usługi do użycia przez SDK za pomocą interfejsu getToken(): Promise<string>.

Web

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);
messaging_init_in_sw.js

Web

// 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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.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();
service-worker.js

Gdy aplikacja działa na pierwszym planie (użytkownik aktualnie przegląda Twoją stronę internetową), możesz otrzymywać dane i ładunki powiadomień bezpośrednio na stronie.

Web

// 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);
  // ...
});
messaging_receive_message.js

Web

// 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);
  // ...
});
index.js

Obsługa 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. Opcje powiadomienia, takie jak tytuł lub działanie po kliknięciu, możesz określić w żądaniu wysłania z serwera aplikacji lub za pomocą logiki usługi w ramach klienta.

Ustawianie opcji powiadomień w żądaniu wysyłania

W przypadku wiadomości z powiadomieniami wysyłanych z serwera aplikacji interfejs FCM JavaScript API obsługuje klucz fcm_options.link. Zwykle jest to strona 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 na karcie przeglądarki, kliknięcie powiadomienia spowoduje wyświetlenie tej karty na pierwszym planie. Jeśli strona nie jest jeszcze otwarta, po kliknięciu powiadomienia otworzy się ona w nowej karcie.

Wiadomości danych nie obsługują fcm_options.link, dlatego zalecamy dodanie do wszystkich wiadomości danych treści powiadomienia. Możesz też obsługiwać powiadomienia za pomocą service workera.

Wyjaśnienie różnicy między powiadomieniami a komunikatami z danymi znajdziesz w artykule Typy wiadomości.

Ustawianie opcji powiadomień w usługach działających w tle

W przypadku wiadomości danych możesz ustawić opcje powiadomień w usługach workera. Najpierw zainicjuj aplikację w usługowym pliku workera:

Web

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);
messaging_init_in_sw.js

Web

// 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.
// Replace 10.13.2 with latest version of the Firebase JS SDK.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.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();
service-worker.js

Aby ustawić opcje, zadzwoń pod numer onBackgroundMessage w firebase-messaging-sw.js. W tym przykładzie tworzymy powiadomienie z polami tytuł, treść i ikona.

Web

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);
});
messaging_on_background_message.js

Web

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);
});
service-worker.js

Sprawdzone metody dotyczące powiadomień

Jeśli znasz już funkcję przesyłania wiadomości push w przeglądarce, być może znasz już ogólne wskazówki, jakie typy powiadomień powinny być dobre. W przypadku deweloperów wysyłających powiadomienia za pomocą usługi FCM w internecie najważniejsze są dokładność i trafność. Oto kilka konkretnych zaleceń dotyczących dokładności i trafności powiadomień:

  • Aby przesłać obraz, użyj pola ikony. W wielu przypadkach powinno to być logo firmy lub aplikacji, które użytkownicy rozpoznają od razu. W przypadku aplikacji do czatu może to być zdjęcie profilowe użytkownika, który wysyła wiadomość.
  • W polu „Title” (Tytuł) podaj dokładny charakter wiadomości. Na przykład wiadomość „Jimmy odpowiedział” zawiera bardziej precyzyjne informacje niż „Nowa wiadomość”. Nie używaj tego cennego miejsca na nazwę firmy ani aplikacji – do tego celu służy ikona.
  • Nie używaj tytułu ani treści powiadomienia do wyświetlania nazwy witryny lub domeny – powiadomienia już zawierają nazwę Twojej domeny.
  • Dodaj atrybut fcm_options.link, zwykle aby połączyć użytkownika z Twoją aplikacją internetową i skupić ją w przeglądarce. W rzadkich przypadkach, gdy wszystkie informacje, które chcesz przekazać, mieszczą się w powiadomieniu, link może nie być potrzebny.