Odbieranie wiadomości w kliencie JavaScript

Sposób działania wiadomości różni się w zależności od tego, czy strona znajduje się na pierwszym planie (jest zaznaczona), w tle, ukryta za innymi kartami czy całkowicie zamknięta. We wszystkich przypadkach strona musi obsługiwać wywołanie zwrotne onMessage, ale w tle może być również konieczne obsługi onBackgroundMessage lub skonfigurowanie powiadomienia o wyświetlaniu tak, aby użytkownik mógł przenieść Twoją aplikację internetową na pierwszy plan.

Stan aplikacji Powiadomienie Dane Oba rodzaje
Pierwszy plan onMessage onMessage onMessage
Tło (skrypt service) 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ługuj wiadomości, gdy aplikacja internetowa działa na pierwszym planie

Aby można było odbierać zdarzenie onMessage, aplikacja musi definiować skrypt usługi przesyłania wiadomości Firebase w firebase-messaging-sw.js. Możesz też udostępnić do pakietu SDK istniejący skrypt service worker za pomocą 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.
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();
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ługuj wiadomości, gdy aplikacja internetowa działa w tle

Wszystkie wiadomości odebrane, gdy aplikacja działa w tle, powodują wyświetlenie w przeglądarce powiadomienia. Możesz określić opcje tego powiadomienia, takie jak tytuł lub działanie kliknięcia, w żądaniu wysyłania z serwera aplikacji lub za pomocą logiki service worker po stronie klienta.

Ustawianie opcji powiadomień w żądaniu wysłania

W przypadku komunikatów 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 w karcie przeglądarki, kliknięcie powiadomienia spowoduje wyświetlenie tej karty na pierwszym planie. Jeśli strona nie jest jeszcze otwarta, kliknięcie powiadomienia spowoduje otwarcie strony na nowej karcie.

Wiadomości z danymi nie obsługują fcm_options.link, dlatego zalecamy dodanie ładunku powiadomień do wszystkich wiadomości z danymi. Możesz też obsługiwać powiadomienia za pomocą skryptu service worker.

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

Ustawianie opcji powiadomień w mechanizmie Service Worker

W przypadku wiadomości dotyczących danych możesz ustawić opcje powiadomień w mechanizmie Service Worker. Najpierw zainicjuj aplikację w skrypcie service worker:

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

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

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 dotyczące dobierania odpowiednich powiadomień. W przypadku deweloperów wysyłających powiadomienia przez FCM w przeglądarkach najważniejsza jest precyzja i trafność. Oto kilka zaleceń, dzięki którym powiadomienia będą trafne i dokładne:

  • Użyj pola ikony, aby przesłać odpowiedni obraz. W wielu przypadkach powinno to być logo firmy lub aplikacji, które użytkownicy od razu rozpoznają. W przypadku komunikatora może to być też zdjęcie profilowe użytkownika wysyłającego.
  • W polu tytułu określ dokładny charakter wiadomości. Na przykład: „Janek odpowiedział na wiadomość” pozwala przekazać dokładniejsze informacje niż „Nowa wiadomość”. Nie wykorzystuj tej cennej przestrzeni na nazwę firmy czy aplikacji – w tym celu użyj ikony.
  • 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 w powiadomieniu zmieści się wszystkie informacje, które musisz przekazać, link może nie być potrzebny.