Ricevere messaggi in un client JavaScript

Il comportamento dei messaggi varia a seconda se la pagina è in primo piano (è attivo) oppure in background, è nascosta dietro altre schede o completamente chiusi. In tutti i casi, la pagina deve gestire il callback onMessage , ma in caso di esecuzione in background potrebbe essere necessario gestire anche onBackgroundMessage o configurare la notifica di visualizzazione per consentire all'utente di portare la tua app web in primo piano.

Stato dell'app	Notifica	Dati	Entrambe
Primo piano	onMessage	onMessage	onMessage
In background (service worker)	onBackgroundMessage (la notifica viene visualizzata automaticamente)	onBackgroundMessage	onBackgroundMessage (la notifica viene visualizzata automaticamente)

L'esempio della guida rapida JavaScript illustra tutto il codice necessario per ricevere i messaggi.

Gestire i messaggi quando l'app web è in primo piano

Per ricevere l'evento onMessage, la tua app deve definire il worker del servizio di messaggistica Firebase in firebase-messaging-sw.js. In alternativa, puoi fornire un service worker esistente all'SDK tramite getToken(): Promise<string>

Web

Impara Scopri di più sull'API web modulare con gestione ad albero e eseguire l'upgrade dall'API con spazio dei nomi.

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

Quando l'app è in primo piano (l'utente sta visualizzando la tua pagina web), puoi ricevere i payload di dati e notifiche direttamente nella pagina.

Web

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

// 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

Gestire i messaggi quando l'app web è in background

Tutti i messaggi ricevuti quando l'app è in background attivano una notifica nel browser. Puoi specificare le opzioni per questa notifica, come il titolo o l'azione di clic, nella richiesta di invio dal server dell'app o utilizzando la logica del service worker sul client.

Le azioni di clic supportano solo gli URL HTTPS protetti.

Impostazione delle opzioni di notifica nella richiesta di invio

Per i messaggi di notifica inviati dal server delle app, FCM L'API JavaScript supporta fcm_options.link chiave. In genere è impostata su una pagina nell'app web:

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"
      }
    }
  }
}

Se il valore del link rimanda a una pagina già aperta in una scheda del browser, un clic sulla notifica porta la scheda in primo piano. Se la pagina non è già aperta, il clic di una notifica la apre in una nuova .

Poiché i messaggi di dati non supportano fcm_options.link, ti consigliamo di aggiungere un payload di notifica a tutti i messaggi di dati. In alternativa, puoi gestire utilizzando il service worker.

Per una spiegazione della differenza tra i messaggi di notifica e di dati, vedi Tipi di messaggi.

Nota: per inviare messaggi agli argomenti, utilizza SDK Admin per sottoscrivere un abbonamento per le istanze di app agli argomenti. Per utilizzare l'API Admin FCM, devi prima seguire la procedura Aggiungi l'SDK Admin Firebase al tuo server per inizializzare l'SDK.

Impostazione delle opzioni di notifica nel service worker

Per i messaggi di dati, puoi impostare le opzioni di notifica nel Service worker. Per prima cosa, inizializza la tua app nel service worker:

Web

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

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

Per impostare le opzioni, chiama il numero onBackgroundMessage tra firebase-messaging-sw.js. In questo esempio, creiamo una notifica con i campi del titolo, del corpo e dell'icona.

Web

Scopri di più sull'API web modulare tree-shakeable e sull'upgrade dall'API con nome.

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

Nota: se vuoi definire un comportamento personalizzato nel servizio worker quando viene fatto clic sulla notifica, assicurati di gestire notificationclick prima di importare funzioni o librerie FCM. In caso contrario, FCM potrebbe sovrascrivere il comportamento personalizzato.

Best practice per le notifiche

Se hai familiarità con i messaggi push per il Web, potresti aver già letto le linee guida generali su cosa rende una notifica valida. Per gli sviluppatori che inviano notifiche tramite FCM per il web, le considerazioni più importanti sono precisione e pertinenza. Ecco alcuni consigli specifici per mantenere le notifiche precise e pertinenti:

• Utilizza il campo dell'icona per inviare un'immagine significativa. Per molti casi d'uso, deve essere il logo di un'azienda o di un'app che gli utenti riconoscono immediatamente. Oppure, per un'applicazione di chat, potrebbe essere l'immagine del profilo dell'utente che invia il messaggio.
• Utilizza il campo del titolo per esprimere la natura precisa del messaggio. Ad esempio: "Jimmy ha risposto" trasmette informazioni più precise rispetto a "Nuovo messaggio". Non utilizzare questo spazio prezioso per il nome della tua azienda o della tua app: utilizza l'icona per questo scopo.
• Non utilizzare il titolo o il corpo della notifica per visualizzare il nome del tuo sito web o dominio; le notifiche contengono già il tuo nome di dominio.
• Aggiungi fcm_options.link, in genere per ricollegare l'utente alla tua app web e portare e mettere a fuoco la creatività nel browser. In rari casi, se tutte le informazioni che devi comunicare possono essere inserite nella notifica, potresti non aver bisogno di un link.