Configura un'app client Firebase Cloud Messaging su Android

I client FCM richiedono dispositivi con Android 4.4 o versioni successive su cui sia installata anche l'app Google Play Store o un emulatore con Android 4.4 con API Google. Tieni presente che non sei limitato a distribuire le tue app Android tramite Google Play Store.

Configura l'SDK

Questa sezione copre le attività che potresti aver completato se hai già abilitato altre funzionalità Firebase per la tua app. Se non l'hai già fatto, aggiungi Firebase al tuo progetto Android

Modifica il manifest dell'app

Aggiungi quanto segue al manifest della tua app:

  • Un servizio che estende FirebaseMessagingService . Ciò è necessario se desideri eseguire qualsiasi gestione dei messaggi oltre alla ricezione di notifiche sulle app in background. Per ricevere notifiche nelle app in primo piano, per ricevere il payload dei dati, per inviare messaggi upstream e così via, 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>
  • (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" />
  • (Facoltativo) 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 canale di notifica come mostrato; FCM utilizzerà questo valore ogni volta che i messaggi in arrivo non impostano esplicitamente un canale di notifica. Per ulteriori informazioni, 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" />

Richiedi l'autorizzazione per la notifica di runtime su Android 13+

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

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

Per richiedere la nuova autorizzazione di runtime:

Kotlin+KTX

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

Java

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

In genere, dovresti visualizzare un'interfaccia utente che spieghi all'utente le funzionalità che verranno abilitate se concedono all'app le autorizzazioni per pubblicare notifiche. Questa interfaccia utente dovrebbe fornire all'utente le opzioni per accettare o negare, ad esempio i pulsanti OK e No, grazie . Se l'utente seleziona OK , richiede direttamente l'autorizzazione. Se l'utente seleziona No, grazie , consenti all'utente di continuare senza notifiche.

Vedi Autorizzazione di runtime di notifica per ulteriori best practice su quando la tua app dovrebbe richiedere l'autorizzazione POST_NOTIFICATIONS all'utente.

Autorizzazioni di notifica per app destinate ad Android 12L (livello API 32) o versioni precedenti

Android chiede automaticamente l'autorizzazione all'utente la prima volta che l'app crea un canale di notifica, purché l'app sia in primo piano. Tuttavia, ci sono avvertenze importanti riguardanti i tempi di creazione del canale e le richieste di autorizzazione:

  • Se la tua app crea il suo primo canale di notifica quando è in esecuzione in background (cosa che fa l'SDK FCM quando riceve una notifica FCM), Android non consentirà la visualizzazione della notifica e non richiederà all'utente l'autorizzazione alla notifica fino al successivo l'ora in cui l'app viene aperta. Ciò significa che tutte le notifiche ricevute prima che l'app venga aperta e l'utente accetti l'autorizzazione andranno perse .
  • Ti consigliamo vivamente di aggiornare la tua app per scegliere come target Android 13+ per sfruttare le API della piattaforma per richiedere l'autorizzazione. Se ciò non è possibile, la tua app dovrebbe creare canali di notifica prima di inviare qualsiasi notifica all'app per attivare la finestra di dialogo di autorizzazione delle notifiche e garantire che nessuna notifica vada persa. Per ulteriori informazioni, consulta le best practice sulle autorizzazioni di notifica .

Facoltativo: rimuovi l'autorizzazione POST_NOTIFICATIONS

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

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

Accedi al token di registrazione del dispositivo

All'avvio iniziale della tua app, l'SDK FCM genera un token di registrazione per l'istanza dell'app client. Se desideri scegliere come target singoli dispositivi o creare gruppi di dispositivi, dovrai accedere a questo token estendendo FirebaseMessagingService ed eseguendo l'override di onNewToken .

In questa sezione viene descritto come recuperare il token e come monitorare le modifiche apportate al token. Poiché il token potrebbe essere ruotato dopo l'avvio iniziale, si consiglia 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() :

Kotlin+KTX

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()
})

Java

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();
        }
    });

Monitorare la generazione dei token

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

Kotlin+KTX

/**
 * 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)
}

Java

/**
 * 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);
}

Dopo aver ottenuto il token, puoi inviarlo al server dell'app e archiviarlo utilizzando il metodo preferito.

Controlla i servizi Google Play

Le app che si basano sull'SDK di Play Services devono sempre verificare se sul dispositivo è presente un APK di Google Play Services compatibile prima di accedere alle funzionalità di Google Play Services. Si consiglia di farlo in due posti: nel metodo onCreate() dell'attività principale e nel relativo metodo onResume() . Il check-in onCreate() garantisce che l'app non possa essere utilizzata senza un controllo positivo. Il controllo in onResume() garantisce che se l'utente ritorna all'app in esecuzione tramite altri mezzi, ad esempio tramite il pulsante Indietro, il controllo viene comunque eseguito.

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

Prevenire 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, disabilita la raccolta di Analytics e l'inizializzazione automatica di FCM (devi disabilitarle entrambe) aggiungendo questi valori di 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" />

Per riabilitare l'avvio automatico di FCM, effettuare una chiamata di runtime:

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

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

setAnalyticsCollectionEnabled(true);

Questi valori persistono tra i riavvii dell'app una volta impostati.

Prossimi passi

Dopo aver configurato l'app client, sei pronto per iniziare a inviare messaggi downstream con il compositore di notifiche . Questa funzionalità è illustrata nell'esempio di avvio rapido , che è possibile scaricare, eseguire ed esaminare.

Per aggiungere altri comportamenti più avanzati alla tua app, puoi dichiarare un filtro di intenti e implementare un'attività per rispondere ai messaggi in arrivo. Per i dettagli, consulta le guide per l'invio di messaggi da un server app:

Tieni presente che, per sfruttare queste funzionalità, avrai bisogno di un'implementazione del server e dei protocolli del server (HTTP o XMPP) oppure di un'implementazione dell'Admin SDK .