Questa guida rapida descrive come configurare Firebase Cloud Messaging nelle tue app client web e mobile per poter inviare messaggi in modo affidabile. Per gli ambienti server, vedi Il tuo ambiente server e FCM.

Configurare un'app client Firebase Cloud Messaging su Flutter

A seconda della piattaforma di destinazione, sono necessari alcuni passaggi di configurazione aggiuntivi.

iOS+

Attivare le funzionalità dell'app in Xcode

Prima che la tua applicazione possa iniziare a ricevere messaggi, devi attivare le notifiche push e le modalità in background nel progetto Xcode.

1. Apri lo spazio di lavoro del progetto Xcode (`ios/Runner.xcworkspace`).
2. Attiva le notifiche push.
3. Attiva Recupero in background e le notifiche remote modalità di esecuzione in background.

Carica la chiave di autenticazione del servizio APN

Prima di utilizzare FCM, carica la chiave di autenticazione APN nella console Firebase. Se non hai già una chiave di autenticazione APN, creane una nel Member Center di Apple Developer.

1. All'interno del progetto nella console Firebase, seleziona l'icona a forma di ingranaggio, seleziona Impostazioni progetto e poi la scheda Cloud Messaging.
2. Seleziona il pulsante Carica per caricare la chiave di autenticazione di sviluppo, la chiave di autenticazione di produzione o entrambe. È obbligatorio indicarne almeno uno.
3. Per ogni chiave di autenticazione, seleziona il file .p8 e fornisci l'ID chiave e l'ID team Apple. Seleziona Salva.

Swizzling del metodo

Per utilizzare il plug-in Flutter FCM sui dispositivi Apple, è necessario lo swizzling dei metodi. Senza, le funzionalità chiave di Firebase come la gestione dei token FCM non funzioneranno correttamente.

Android

Google Play Services

I client FCM richiedono dispositivi con Android 4.4 o versioni successive su cui sia installato Google Play Services oppure un emulatore con Android 4.4 con le API di Google. Tieni presente che non sei limitato all'implementazione delle tue app per Android tramite il Google Play Store.

Le app che si basano sull'SDK Play Services devono sempre controllare che sul dispositivo sia presente un APK di Google Play Services compatibile prima di accedere alle funzionalità di Google Play Services. Ti consigliamo di farlo in due punti: nel metodo onCreate() dell'attività principale e nel metodo onResume(). Il controllo in onCreate() assicura che l'app non possa essere utilizzata senza un controllo riuscito. Il controllo onResume() garantisce che, se l'utente torna all'app in esecuzione in altro modo, ad esempio tramite il pulsante Indietro, il controllo venga comunque eseguito.

Se il dispositivo non dispone di una versione compatibile di Google Play Services, la tua app può chiamare GoogleApiAvailability.makeGooglePlayServicesAvailable() per consentire agli utenti di scaricare Google Play Services dal Play Store.

Web

Configurare le credenziali web con FCM

L'interfaccia web FCM utilizza credenziali web chiamate Voluntary Application Server Identification o chiavi "VAPID" per autorizzare le richieste di invio ai servizi push web supportati. Per iscrivere la tua app alle notifiche push, devi associare una coppia di chiavi al tuo progetto Firebase. Puoi generare una nuova coppia di chiavi o importare quella esistente tramite la console Firebase.

Genera una nuova coppia di chiavi

1. Apri la scheda Cloud Messaging del riquadro Impostazioni della console Firebase e vai alla sezione Configurazione web.
2. Nella scheda Certificati web push, fai clic su Genera coppia di chiavi. La console mostra un avviso che indica che la coppia di chiavi è stata generata e visualizza la stringa della chiave pubblica e la data di aggiunta.

Importare una coppia di chiavi esistente

Se disponi di una coppia di chiavi esistente che utilizzi già con la tua app web, puoi importarla in FCM per poter raggiungere le istanze dell'app web esistenti tramite le API FCM. Per importare le chiavi, devi disporre dell'accesso a livello di proprietario al progetto Firebase. Importa la chiave pubblica e quella privata esistenti in formato con codifica Base64 sicura per gli URL:

1. Apri la scheda Cloud Messaging del riquadro Impostazioni della console Firebase e vai alla sezione Configurazione web.
2. Nella scheda Certificati push web, seleziona Importa una coppia di chiavi esistente.
3. Nella finestra di dialogo Importa una coppia di chiavi, fornisci le chiavi pubblica e privata nei campi corrispondenti e fai clic su Importa. La console mostra la stringa della chiave pubblica e la data di aggiunta.

Per ulteriori informazioni sul formato delle chiavi e su come generarle, vedi Chiavi del server delle applicazioni.

Installare il plug-in FCM

1. Installa e inizializza i plug-in Firebase per Flutter, se non l'hai ancora fatto.

2. Dalla radice del progetto Flutter, esegui il seguente comando per installare il plug-in:

   flutter pub add firebase_messaging
   

3. Al termine, ricompila l'applicazione Flutter:

   flutter run
   

Accedere al token di registrazione

Per inviare un messaggio a un dispositivo specifico, devi conoscere il token di registrazione del dispositivo. Per recuperare il token di registrazione per un'istanza dell'app, chiama getToken(). Se l'autorizzazione alle notifiche non è stata concessa, questo metodo chiederà all'utente le autorizzazioni alle notifiche. In caso contrario, restituisce un token o rifiuta il futuro a causa di un errore.

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, make sure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

Sulle piattaforme web, passa la tua chiave pubblica VAPID a getToken():

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

Per ricevere una notifica ogni volta che il token viene aggiornato, iscriviti allo stream onTokenRefresh:

FirebaseMessaging.instance.onTokenRefresh
    .listen((fcmToken) {
      // TODO: If necessary send token to application server.

      // Note: This callback is fired at each app startup and whenever a new
      // token is generated.
    })
    .onError((err) {
      // Error getting token.
    });

Impedisci l'inizializzazione automatica

Quando viene generato un token di registrazione FCM, la libreria carica l'identificatore e i dati di configurazione su Firebase. Se preferisci impedire la generazione automatica dei token, disattiva l'inizializzazione automatica in fase di compilazione.

iOS

Su iOS, aggiungi un valore dei metadati al tuo Info.plist:

FirebaseMessagingAutoInitEnabled = NO

Android

Su Android, disattiva la raccolta di Analytics e l'inizializzazione automatica di FCM (devi disattivarle entrambe) aggiungendo questi valori dei metadati al tuo AndroidManifest.xml:

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

Riattiva l'inizializzazione automatica di FCM al runtime

Per attivare l'avvio automatico per un'istanza di app specifica, chiama setAutoInitEnabled():

await FirebaseMessaging.instance.setAutoInitEnabled(true);

Una volta impostato, questo valore viene mantenuto anche dopo il riavvio dell'app.

Inviare un messaggio di notifica di prova

1. Installa ed esegui l'app sul dispositivo di destinazione. Sui dispositivi Apple, dovrai accettare la richiesta di autorizzazione per ricevere notifiche da remoto.
2. Assicurati che l'app sia in background sul dispositivo.
3. Nella console Firebase, apri la pagina Messaggistica.
4. Se questo è il tuo primo messaggio, seleziona Crea la tua prima campagna.
   1. Seleziona Messaggi di notifica Firebase e poi Crea.
5. In alternativa, nella scheda Campagne, seleziona Nuova campagna e poi Notifiche.
6. Inserisci il testo del messaggio.
7. Seleziona Invia messaggio di prova dal riquadro a destra.
8. Nel campo etichettato Aggiungi un token di registrazione FCM, inserisci il token di registrazione.
9. Seleziona Testa.

Dopo aver selezionato Testa, il dispositivo client di destinazione, con l'app in background, dovrebbe ricevere la notifica.

Per informazioni sulla distribuzione dei messaggi alla tua app, consulta la dashboard dei report FCM, che registra il numero di messaggi inviati e aperti su dispositivi Apple e Android, nonché i dati sulle impressioni per le app per Android.

Gestione dell'interazione

Quando gli utenti toccano una notifica, il comportamento predefinito sia su Android che su iOS è aprire l'applicazione. Se l'applicazione viene terminata, verrà avviata e, se è in background, verrà portata in primo piano.

A seconda del contenuto di una notifica, potresti voler gestire l'interazione dell'utente all'apertura dell'applicazione. Ad esempio, se viene inviato un nuovo messaggio di chat utilizzando una notifica e l'utente lo seleziona, potresti voler aprire la conversazione specifica quando l'applicazione si apre.

Il pacchetto firebase-messaging offre due modi per gestire questa interazione:

1. getInitialMessage(): Se l'applicazione viene aperta da uno stato di terminazione, questo metodo restituisce un Future contenente un RemoteMessage. Una volta consumato, RemoteMessage verrà rimosso.
2. onMessageOpenedApp: un Stream che pubblica un RemoteMessage quando l'applicazione viene aperta da uno stato in background.

Per garantire un'esperienza ottimale ai tuoi utenti, devi gestire entrambi gli scenari. Il seguente esempio di codice mostra come eseguire questa operazione:

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

Il modo in cui gestisci l'interazione dipende dalla tua configurazione. L'esempio mostrato in precedenza è un esempio di base di utilizzo di un StatefulWidget.

Passaggi successivi

Dopo aver completato i passaggi di configurazione, ecco alcune opzioni per procedere con FCM per Flutter:

• Inviare messaggi ai dispositivi
• Ricevere messaggi in un'app Flutter
• Inviare messaggi agli argomenti