Google is committed to advancing racial equity for Black communities. See how.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

Configura un'app client Firebase Cloud Messaging su Android

Per scrivere la tua app client Firebase Cloud Messaging Android, utilizza l'API FirebaseMessaging e Android Studio 1.4 o versioni successive con Gradle. Le istruzioni in questa pagina presuppongono che tu abbia completato i passaggi per aggiungere Firebase al tuo progetto Android .

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

Configura l'SDK

Questa sezione tratta le attività che potresti aver completato se hai già abilitato altre funzionalità di Firebase per la tua app.

Prima di iniziare

  • Installa o aggiorna Android Studio alla sua ultima versione.

  • Assicurati che il tuo progetto soddisfi questi requisiti:

    • Ha come target il livello API 16 (Jelly Bean) o successivo
    • Utilizza Gradle 4.1 o successivo
    • Utilizza Jetpack (AndroidX) , che include la soddisfazione di questi requisiti di versione:
      • com.android.tools.build:gradle v3.2.1 o successiva
      • compileSdkVersion 28 o successivo
  • Configura un dispositivo fisico o usa un emulatore per eseguire la tua app.
    Tieni presente che gli SDK Firebase con una dipendenza dai servizi di Google Play richiedono che il dispositivo o l'emulatore abbia installato i servizi di Google Play.

  • Accedi a Firebase utilizzando il tuo account Google.

Se non hai già un progetto Android e vuoi solo provare un prodotto Firebase, puoi scaricare uno dei nostri esempi di avvio rapido .

Crea un progetto Firebase

Prima di poter aggiungere Firebase alla tua app Android, devi creare un progetto Firebase per connetterti alla tua app Android. Visita Comprendere i progetti Firebase per ulteriori informazioni sui progetti Firebase.

Registra la tua app con Firebase

Per utilizzare Firebase nella tua app Android, devi registrare la tua app con il tuo progetto Firebase. La registrazione della tua app viene spesso chiamata "aggiunta" della tua app al tuo progetto.

  1. Vai alla console Firebase .

  2. Al centro della pagina di panoramica del progetto, fai clic sull'icona Android ( ) o su Aggiungi app per avviare il flusso di lavoro di configurazione.

  3. Inserisci il nome del pacchetto della tua app nel campo del nome del pacchetto Android .

  4. (Facoltativo) Immettere altre informazioni sull'app: nickname app e certificato di firma di debug SHA-1 .

  5. Fare clic su Registra app .

Aggiungi un file di configurazione Firebase

  1. Aggiungi il file di configurazione Android di Firebase alla tua app:

    1. Fai clic su Scarica google-services.json per ottenere il tuo file di configurazione Android di Firebase ( google-services.json ).

    2. Sposta il tuo file di configurazione nella directory del modulo (a livello di app) della tua app.

  2. Per abilitare i prodotti Firebase nella tua app, aggiungi il plug-in dei servizi Google ai tuoi file Gradle.

    1. Nel tuo file Gradle a livello di root (a livello di progetto) ( build.gradle ), aggiungi regole per includere il plug-in Gradle di Google Services. Verifica di avere anche il repository Maven di Google.

      buildscript {
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
        }
      
        dependencies {
          // ...
      
          // Add the following line:
          classpath 'com.google.gms:google-services:4.3.5'  // Google Services plugin
        }
      }
      
      allprojects {
        // ...
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
          // ...
        }
      }
      
    2. Nel file Gradle del modulo (a livello di app) (solitamente app/build.gradle ), applica il plug-in Gradle dei servizi di Google:

      apply plugin: 'com.android.application'
      // Add the following line:
      apply plugin: 'com.google.gms.google-services'  // Google Services plugin
      
      android {
        // ...
      }
      

Aggiungi gli SDK Firebase alla tua app

  1. Utilizzando Firebase Android BoM , dichiara la dipendenza per la libreria Firebase Cloud Messaging Android nel file Gradle del modulo (a livello di app) (solitamente app/build.gradle ).

    Per un'esperienza ottimale con Firebase Cloud Messaging, ti consigliamo di abilitare Google Analytics nel tuo progetto. Inoltre, come parte della configurazione di Analytics, devi aggiungere l'SDK Firebase per Google Analytics alla tua app.

    Giava

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:27.0.0')
    
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging'
        implementation 'com.google.firebase:firebase-analytics'
    }
    

    Utilizzando Firebase Android BoM , la tua app utilizzerà sempre versioni compatibili delle librerie Firebase Android.

    (Alternativa) Dichiara le dipendenze della libreria Firebase senza utilizzare BoM

    Se scegli di non utilizzare Firebase BoM, devi specificare ciascuna versione della libreria Firebase nella relativa riga di dipendenza.

    Tieni presente che se utilizzi più librerie Firebase nella tua app, ti consigliamo vivamente di utilizzare BoM per gestire le versioni delle librerie, il che garantisce che tutte le versioni siano compatibili.

    dependencies {
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging:21.1.0'
        implementation 'com.google.firebase:firebase-analytics:18.0.3'
    }
    

    Kotlin + KTX

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:27.0.0')
    
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging-ktx'
        implementation 'com.google.firebase:firebase-analytics-ktx'
    }
    

    Utilizzando Firebase Android BoM , la tua app utilizzerà sempre versioni compatibili delle librerie Firebase Android.

    (Alternativa) Dichiara le dipendenze della libreria Firebase senza utilizzare BoM

    Se scegli di non utilizzare Firebase BoM, devi specificare ciascuna versione della libreria Firebase nella relativa riga di dipendenza.

    Tieni presente che se utilizzi più librerie Firebase nella tua app, ti consigliamo vivamente di utilizzare BoM per gestire le versioni delle librerie, il che garantisce che tutte le versioni siano compatibili.

    dependencies {
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging-ktx:21.0.1'
        implementation 'com.google.firebase:firebase-analytics-ktx:18.0.3'
    }
    

  2. Sincronizza la tua app per assicurarti che tutte le dipendenze abbiano le versioni necessarie.

Modifica il manifesto dell'app

Aggiungi quanto segue al manifest della tua app:

  • Un servizio che estende FirebaseMessagingService . Ciò è necessario se desideri gestire i messaggi oltre a ricevere notifiche sulle app in background. Per ricevere notifiche nelle app in primo piano, per ricevere il payload dei dati, per inviare messaggi a monte e così via, è necessario estendere questo servizio.
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (Opzionale) 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) A partire da Android 8.0 (livello API 26) e versioni successive, icanali di notifica sono supportati e consigliati. FCM fornisce un canale di notifica predefinito con le 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 in modo esplicito un canale di notifica. Per saperne di più, vediGestire i canali di notifica .
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

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 e sovrascrivendo onNewToken .

Questa sezione descrive come recuperare il token e come monitorare le modifiche al token. Poiché il token potrebbe essere ruotato dopo l'avvio iniziale, si consiglia vivamente di recuperare l'ultimo token di registrazione aggiornato.

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

Giava

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

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

Monitorare la generazione di token

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

Giava

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

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

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

Controlla i servizi di Google Play

Le app che si basano sull'SDK dei servizi di riproduzione dovrebbero sempre controllare il dispositivo per un APK dei servizi di Google Play compatibile prima di accedere alle funzioni dei servizi di Google Play. Si consiglia di farlo in due punti: nel metodo onCreate() dell'attività principale e nel metodo onResume() . Il check in onCreate() garantisce che l'app non possa essere utilizzata senza un controllo riuscito. Il check 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 di Google Play Services, la tua app può chiamare GoogleApiAvailability.makeGooglePlayServicesAvailable() per consentire agli utenti di scaricare Google Play Services dal Play Store.

Impedisci 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 del token, disabilita la raccolta di Analytics e l'inizializzazione automatica di FCM (devi disabilitarli entrambi) 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 riattivare l'avvio automatico FCM, effettuare una chiamata in runtime:

Giava

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin + KTX

Firebase.messaging.isAutoInitEnabled = true

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

setAnalyticsCollectionEnabled(true);

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

Prossimi passi

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

Per aggiungere un altro comportamento più avanzato alla tua app, puoi dichiarare un filtro di intento e implementare un'attività per rispondere ai messaggi in arrivo. Per i dettagli, vedere 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 server procotols (HTTP o XMPP), o un'implementazione dell'Admin SDK .