Inizia a utilizzare Firebase Cloud Messaging nelle app per Android

Questa guida descrive come iniziare a utilizzare Firebase Cloud Messaging nelle app client Android in modo da poter inviare messaggi in modo affidabile.

FCM client richiedono dispositivi con Android 6.0 o versioni successive su cui sia installata l'app Google Play Store oppure un emulatore con Android 6.0 con le API di Google. Tieni presente che non sei limitato al deployment delle tue app Android tramite Google Play Store.

Configura l'SDK

Se non l'hai già fatto, aggiungi Firebase al tuo progetto Android project.

Per un'esperienza ottimale con FCM, ti consigliamo vivamente di attivare Google Analytics nel tuo progetto. Google Analytics è un requisito per report di pubblicazione dei messaggi per FCM.

Modifica il manifest dell'app

Aggiungi quanto segue al manifest dell'app:

• Un servizio che estende FirebaseMessagingService. È necessario se vuoi gestire i messaggi oltre a ricevere notifiche sulle app in background. Per ricevere notifiche nelle app in primo piano, ricevere payload di dati e altro ancora, devi estendere questo servizio.

<service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
AndroidManifest.xml

• (Facoltativo) All'interno del componente dell'applicazione, elementi di metadati per impostare un'icona e un colore di notifica predefiniti. Android utilizza questi valori ogni volta che i messaggi in arrivo non impostano esplicitamente l'icona o il colore.

<!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
     See README(https://goo.gl/l4GJaQ) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_ic_notification" />
<!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more. -->
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/colorAccent" />
AndroidManifest.xml

• (Facoltativo) A partire da Android 8.0 (livello API 26) e versioni successive, i canali di notifica sono supportati e consigliati. FCM fornisce un canale di notifica predefinito con impostazioni di base. Se preferisci creare e utilizzare il tuo canale predefinito, imposta default_notification_channel_id sull'ID dell'oggetto del canale di notifica come mostrato; FCM utilizzerà questo valore ogni volta che i messaggi in arrivo non impostano esplicitamente un canale di notifica. Per saperne di più, consulta Gestire i canali di notifica.

<meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />
AndroidManifest.xml

Richiedi l'autorizzazione di notifica di runtime su Android 13 e versioni successive

Android 13 introduce una nuova autorizzazione di runtime per la visualizzazione delle notifiche. Ciò influisce su tutte le app in esecuzione su Android 13 o versioni successive che utilizzano le FCM notifiche.

Per impostazione predefinita, l'FCM SDK (versione 23.0.6 o successive) include l' POST_NOTIFICATIONS autorizzazione definita nel manifest. Tuttavia, la tua app dovrà anche richiedere la versione di runtime di questa autorizzazione utilizzando la costante android.permission.POST_NOTIFICATIONS. La tua app non potrà mostrare le notifiche finché l'utente non avrà concesso questa autorizzazione.

Per richiedere la nuova autorizzazione di runtime:

// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission(),
) { isGranted: Boolean ->
    if (isGranted) {
        // FCM SDK (and your app) can post notifications.
    } else {
        // TODO: Inform user that that your app will not show notifications.
    }
}

private fun askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED
        ) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}
MainActivity.kt

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // FCM SDK (and your app) can post notifications.
            } else {
                // TODO: Inform user that that your app will not show notifications.
            }
        });

private void askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}
MainActivity.java

In genere, dovresti mostrare un'interfaccia utente che spieghi all'utente le funzionalità che verranno attivate se concede le autorizzazioni all'app per pubblicare le notifiche. Questa UI deve fornire all'utente opzioni per accettare o rifiutare, ad esempio i pulsanti OK e No, grazie. Se l'utente seleziona OK, richiedi direttamente l'autorizzazione. Se l'utente seleziona No, grazie, consenti all'utente di continuare senza notifiche.

Per ulteriori best practice su quando la tua app deve richiedere all'utente l'autorizzazione POST_NOTIFICATIONS , consulta Autorizzazione di runtime per le notifiche.

Autorizzazioni di notifica per le app che hanno come target Android 12L (livello API 32) o versioni precedenti

Android chiede automaticamente all'utente l'autorizzazione la prima volta che la tua app crea un canale di notifica, a condizione che l'app sia in primo piano. Tuttavia, esistono importanti avvertenze relative alla tempistica della creazione del canale e delle richieste di autorizzazione:

• Se la tua app crea il suo primo canale di notifica quando è in esecuzione in background, come fa l'SDK FCM quando riceve una notifica FCM, Android non consentirà la visualizzazione della notifica e non chiederà all'utente l'autorizzazione di notifica fino alla prossima apertura dell'app. Ciò significa che tutte le notifiche ricevute prima dell'apertura dell'app e dell'accettazione dell'autorizzazione da parte dell'utente andranno perse.
• Ti consigliamo vivamente di aggiornare la tua app in modo che abbia come target Android 13 e versioni successive per sfruttare le API della piattaforma per richiedere l'autorizzazione. Se non è possibile, la tua app deve creare canali di notifica prima di inviare notifiche all'app per attivare la finestra di dialogo dell'autorizzazione di notifica e assicurarsi che non vadano perse notifiche. Per saperne di più, consulta le best practice per l'autorizzazione di notifica.

(Facoltativo) Rimuovi l'autorizzazione POST_NOTIFICATIONS

Per impostazione predefinita, l'SDK FCM include l'autorizzazione POST_NOTIFICATIONS. Se la tua app non utilizza i messaggi di notifica (tramite le FCM notifiche, un altro SDK o pubblicati direttamente dalla tua app) e non vuoi che l'app includa l'autorizzazione, puoi rimuoverla utilizzando il marcatore remove dell'unione del manifest. Tieni presente che la rimozione di questa autorizzazione impedisce la visualizzazione di tutte le notifiche, non solo FCM notifiche. Aggiungi quanto segue al file manifest dell'app:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

Accedi all'ID di installazione di Firebase

Al primo avvio dell'app, l'FCM SDK registra l'istanza dell'app con FCM e restituisce un identificatore per l'istanza dell'app. Se vuoi avere come target singole istanze dell'app, devi accedere a questo identificatore estendendo FirebaseMessagingService ed eseguendo l'override di onRegistered(). Come best practice, recupera l'identificatore aggiornato più recente, poiché l'identificatore può essere ruotato dopo l'avvio iniziale.

Attiva la registrazione tramite l'ID di installazione di Firebase

<meta-data
    android:name="firebase_messaging_installation_id_enabled"
    android:value="true" />

Implementa il callback onRegistered()

Le istanze dell'app hanno come target l'ID di installazione di Firebase (FID) una volta registrate con FCM. Per recuperare l'FID al momento della registrazione, implementa il onRegistered() callback. Una volta registrata un'istanza dell'app, l'FCM SDK monitora automaticamente le modifiche dell'FID e richiama il callback quando viene rilevata una modifica. Quando l'inizializzazione automatica è attivata, l'FCM SDK si sincronizza automaticamente con il backend FCM per mantenere aggiornata la registrazione e richiama il callback per assicurarsi che il server dell'app abbia l'identificatore corrente. Per proteggerti dalla perdita dell'FID o dagli FID obsoleti, devi inviare l'FID al server dell'app ogni volta che viene attivato questo callback.

  /**
   * There are three scenarios when `onRegistered` is called:
   * 1) Every time a manual `register()` call finishes successfully
   * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID.
   * 3) Automatically on app startup or routine sync when auto-initialization is enabled.
   * Under #2, there are three scenarios when the existing FID is changed:
   * A) App is restored to a new device
   * B) User uninstalls/reinstalls the app
   * C) User clears app data
   */
  override fun onRegistered(installationId: String) {
      Log.d(TAG, "Registered installation ID: $installationId")

      // Send the Firebase Installation ID to your app server.
      sendRegistrationToServer(installationId)
  }
    

  /**
   * There are three scenarios when `onRegistered` is called:
   * 1) Every time a manual `register()` call finishes successfully
   * 2) Whenever the FID is changed and the app is re-registered with FCM via the new FID
   * 3) Automatically on app startup or routine sync when auto-initialization is enabled.
   * Under #2, there are three scenarios when the existing FID is changed:
   * A) App is restored to a new device
   * B) User uninstalls/reinstalls the app
   * C) User clears app data
   */
  @Override
  public void onRegistered(@NonNull String installationId) {
      Log.d(TAG, "Registered installation ID: " + installationId);

      // Send the Firebase Installation ID to your app server.
      sendRegistrationToServer(installationId);
  }
    

Registra manualmente quando l'inizializzazione automatica è disattivata

Se devi disattivare l'inizializzazione automatica, l'FCM SDK non si sincronizzerà automaticamente né attiverà il onRegistered() callback all'avvio. Ti consigliamo vivamente di riattivare l'inizializzazione automatica dopo aver concesso le autorizzazioni di notifica. Per saperne di più, consulta Riattivare l'inizializzazione automatica.

Se l'inizializzazione automatica deve rimanere disattivata, chiama FirebaseMessaging.getInstance().register() all'avvio dell'app per attivare la registrazione e la pubblicazione dell'FID tramite il onRegistered() callback. Puoi eseguire questa chiamata all'interno del onCreate() metodo della tua Activity principale.

  // Trigger manual registration if auto-initialization is turned off.
  // Consider calling this every time the app starts to guarantee sync status.
  FirebaseMessaging.getInstance().register()
      .addOnCompleteListener(this) { task ->
        if (!task.isSuccessful()) {
          // Registration failed. Consider retrying the registration with exponential backoff.
          Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception)
        }
        // Success! The Firebase Installation ID can be used to target messages to this app
        // instance and will be delivered asynchronously to your `onRegistered()` callback.
      }
    

  // Trigger manual registration if auto-initialization is turned off.
  // Consider calling this every time the app starts to guarantee sync status.
  FirebaseMessaging.getInstance().register()
      .addOnCompleteListener(task -> {
        if (!task.isSuccessful()) {
          // Registration failed. Consider retrying the registration with exponential backoff.
          Log.w(TAG, "Failed to register with Firebase Cloud Messaging", task.exception)
        }
        // Success! The Firebase Installation ID can be used to target messages to this app
        // instance and will be delivered asynchronously to your `onRegistered()` callback.
      });
    

Accedi al token di registrazione FCM (obsoleto)

Al primo avvio dell'app, l'FCM SDK genera un token di registrazione per l'istanza dell'app client. Se vuoi avere come target singole istanze dell'app o creare gruppi di dispositivi, devi accedere a questo token estendendo FirebaseMessagingService ed eseguendo l'override di onNewToken. Poiché il token potrebbe essere ruotato dopo l'avvio iniziale, ti consigliamo vivamente di recuperare il token di registrazione aggiornato più recente.

Il token di registrazione può cambiare quando:

• L'app viene ripristinata su un nuovo dispositivo
• L'utente disinstalla/reinstalla l'app
• L'utente cancella i dati dell'app.

Recupera il token di registrazione corrente

Quando devi recuperare il token corrente, chiama FirebaseMessaging.getInstance().getToken():

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

Monitora la generazione del token

Il callback onNewToken viene attivato ogni volta che viene generato un nuovo token.

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}
MyFirebaseMessagingService.kt

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(@NonNull String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}
MyFirebaseMessagingService.java

Dopo aver ottenuto il token, puoi inviarlo al server dell'app e memorizzarlo utilizzando il metodo che preferisci.

Verifica la presenza di Google Play Services

Le app che si basano sull'SDK Play Services devono sempre verificare la presenza di un APK di Google Play Services compatibile sul dispositivo prima di accedere alle funzionalità di Google Play Services. Per saperne di più, consulta Configurare Google Play Services. Ti consigliamo di eseguire questa operazione in due punti: nel metodo onCreate() dell'attività principale e nel metodo onResume(). Il controllo in onCreate() garantisce che l'app non possa essere utilizzata senza un controllo riuscito. Il controllo in onResume() garantisce che, se l'utente torna all'app in esecuzione tramite altri mezzi, ad esempio il pulsante Indietro, il controllo venga comunque eseguito.

Se il dispositivo non ha 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.

Impedisci l'inizializzazione automatica

Quando viene generata una registrazione FCM, la libreria carica l' identificatore e i dati di configurazione su Firebase. Se preferisci impedire la registrazione automatica, disattiva la raccolta di Analytics e l'inizializzazione automatica di FCM (devi disattivarle entrambe) aggiungendo questi valori di metadati a 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" />
AndroidManifest.xml

Riattiva l'inizializzazione automatica

Per riattivare l'inizializzazione automatica di FCM, effettua una chiamata di runtime:

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

FirebaseMessaging.getInstance().setAutoInitEnabled(true);
MainActivity.java

Per riattivare la raccolta di Analytics, chiama il setAnalyticsCollectionEnabled() metodo della FirebaseAnalytics classe. Ad esempio:

setAnalyticsCollectionEnabled(true);

Una volta impostati, questi valori vengono mantenuti anche dopo il riavvio dell'app.

Invia un messaggio di notifica

Per assicurarti che il client Android sia configurato correttamente, puoi inviare un messaggio di notifica di test seguendo queste istruzioni:

1. Installa ed esegui l'app sul dispositivo di destinazione.

2. Assicurati che l'app sia in background sul dispositivo.

3. Nella console Firebase, vai a DevOps e coinvolgimento > Messaggistica

4. Crea una campagna.

   • Se è il tuo primo messaggio:

     1. Seleziona Crea la tua prima campagna.

     2. Seleziona Messaggi di notifica Firebase e poi Crea.

   • Se hai già creato campagne:

     1. Nella scheda Campagne, seleziona Nuova campagna.

     2. Fai clic su Notifiche.

5. Inserisci il testo del messaggio. Tutti gli altri campi sono facoltativi.

6. Seleziona Invia messaggio di test nel riquadro a destra.

7. Nel campo con l'etichetta Aggiungi un token di registrazione FCM, inserisci il token di registrazione che hai ottenuto in una sezione precedente di questa guida.

8. Seleziona Testa.

Il dispositivo client di destinazione, con l'app in background, dovrebbe ricevere la notifica.

Per informazioni sulla pubblicazione dei messaggi nella tua app, vai alla dashboard DevOps e coinvolgimento > Messaggistica > Report nella console Firebase. Questa dashboard registra il numero di messaggi inviati e aperti su dispositivi Apple e Android, insieme ai dati per le "impressioni" (notifiche visualizzate dagli utenti) per le app Android.

Passaggi successivi

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

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