Invia messaggi a più dispositivi

Per indirizzare un messaggio a più dispositivi, utilizza la messaggistica per argomento . Questa funzione ti consente di inviare un messaggio a più dispositivi che hanno aderito a un particolare argomento.

Questo tutorial si concentra sull'invio di messaggi di argomento dal server dell'app utilizzando Admin SDK o API REST per FCM e sulla loro ricezione e gestione in un'app Android. Tratteremo la gestione dei messaggi sia per le app in background che per quelle in primo piano. Vengono coperti tutti i passaggi per raggiungere questo obiettivo, dalla configurazione alla verifica.

Configura l'SDK

Questa sezione potrebbe coprire i passaggi già completati se hai configurato un'app client Android per FCM o hai seguito i passaggi per inviare il tuo primo messaggio .

Prima di iniziare

  • Installa o aggiorna Android Studio alla versione più recente.

  • Assicurati che il tuo progetto soddisfi questi requisiti:

    • Ha come target il livello API 19 (KitKat) o superiore
    • Utilizza Android 4.4 o versioni successive
    • Utilizza Jetpack (AndroidX) , che include il rispetto di questi requisiti di versione:
      • com.android.tools.build:gradle v7.3.0 o successivo
      • compileSdkVersion 28 o successiva
  • Configura un dispositivo fisico o utilizza un emulatore per eseguire la tua app.
    Tieni presente che gli SDK Firebase con una dipendenza dai servizi Google Play richiedono che sul dispositivo o sull'emulatore siano installati i servizi Google Play.

  • Accedi a Firebase utilizzando il tuo account Google.

Se non disponi già di un progetto Android e desideri semplicemente 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 Nome del pacchetto Android .

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

  5. Fai clic su Registra app .

Aggiungi un file di configurazione Firebase

  1. Scarica e quindi aggiungi il file di configurazione Android Firebase ( google-services.json ) alla tua app:

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

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

  2. Per rendere i valori nel file di configurazione google-services.json accessibili agli SDK Firebase, è necessario il plug-in Gradle dei servizi Google ( google-services ).

    1. Nel file Gradle a livello di root (a livello di progetto) ( <project>/build.gradle.kts o <project>/build.gradle ), aggiungi il plug-in dei servizi Google come dipendenza:

      Kotlin

      plugins {
        id("com.android.application") version "7.3.0" apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id("com.google.gms.google-services") version "4.4.1" apply false
      }
      

      Groovy

      plugins {
        id 'com.android.application' version '7.3.0' apply false
        // ...
      
        // Add the dependency for the Google services Gradle plugin
        id 'com.google.gms.google-services' version '4.4.1' apply false
      }
      
    2. Nel file Gradle del tuo modulo (a livello di app) (solitamente <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle ), aggiungi il plug-in dei servizi Google:

      Kotlin

      plugins {
        id("com.android.application")
      
        // Add the Google services Gradle plugin
        id("com.google.gms.google-services")
        // ...
      }
      

      Groovy

      plugins {
        id 'com.android.application'
      
        // Add the Google services Gradle plugin
        id 'com.google.gms.google-services'
        // ...
      }
      

Aggiungi gli SDK Firebase alla tua app

  1. Nel file Gradle del modulo (a livello di app) (solitamente <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle ), aggiungi la dipendenza per Firebase Cloud Libreria di messaggistica per Android. Ti consigliamo di utilizzare la distinta base Android Firebase per controllare il controllo delle versioni della libreria.

    Per un'esperienza ottimale con Firebase Cloud Messaging, ti consigliamo di abilitare Google Analytics nel tuo progetto Firebase e di aggiungere l'SDK Firebase per Google Analytics alla tua app.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.8.0"))
    
        // Add 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 la distinta base Firebase per Android , la tua app utilizzerà sempre le versioni compatibili delle librerie Firebase Android.

    (Alternativa) Aggiungi le dipendenze della libreria Firebase senza utilizzare la distinta base

    Se scegli di non utilizzare la distinta base Firebase, 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 la distinta base per gestire le versioni della libreria, il che garantisce che tutte le versioni siano compatibili.

    dependencies {
        // Add 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:23.4.1")
        implementation("com.google.firebase:firebase-analytics:21.6.1")
    }
    
    Cerchi un modulo di libreria specifico per Kotlin? A partire da ottobre 2023 (Firebase BoM 32.5.0) , sia gli sviluppatori Kotlin che Java potranno dipendere dal modulo della libreria principale (per i dettagli, vedere le FAQ su questa iniziativa ).

  2. Sincronizza il tuo progetto Android con i file Gradle.

Sottoscrivere l'app client a un argomento

Le app client possono sottoscrivere qualsiasi argomento esistente oppure possono creare un nuovo argomento. Quando un'app client si iscrive a un nuovo nome di argomento (uno che non esiste già per il tuo progetto Firebase), viene creato un nuovo argomento con quel nome in FCM e qualsiasi client può successivamente iscriversi ad esso.

Per sottoscrivere un argomento, l'app client chiama Firebase Cloud subscribeToTopic() con il nome dell'argomento FCM. Questo metodo restituisce un Task , che può essere utilizzato da un ascoltatore di completamento per determinare se la sottoscrizione è riuscita:

Kotlin+KTX

Firebase.messaging.subscribeToTopic("weather")
    .addOnCompleteListener { task ->
        var msg = "Subscribed"
        if (!task.isSuccessful) {
            msg = "Subscribe failed"
        }
        Log.d(TAG, msg)
        Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
    }

Java

FirebaseMessaging.getInstance().subscribeToTopic("weather")
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                String msg = "Subscribed";
                if (!task.isSuccessful()) {
                    msg = "Subscribe failed";
                }
                Log.d(TAG, msg);
                Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
            }
        });

Per annullare l'iscrizione, l'app client chiama Firebase Cloud Messaging unsubscribeFromTopic() con il nome dell'argomento.

Ricevere e gestire messaggi di argomento

FCM consegna i messaggi dell'argomento allo stesso modo degli altri messaggi downstream.

Per ricevere messaggi, utilizza un servizio che estende FirebaseMessagingService . Il tuo servizio dovrebbe sovrascrivere i callback onMessageReceived e onDeletedMessages .

L'intervallo di tempo per la gestione di un messaggio può essere inferiore a 20 secondi a seconda dei ritardi verificatisi prima della chiamata onMessageReceived , inclusi ritardi del sistema operativo, tempo di avvio dell'app, thread principale bloccato da altre operazioni o chiamate onMessageReceived precedenti che impiegano troppo tempo. Dopo tale periodo, vari comportamenti del sistema operativo, come l'interruzione del processo di Android o i limiti di esecuzione in background di Android O, potrebbero interferire con la tua capacità di completare il tuo lavoro.

onMessageReceived viene fornito per la maggior parte dei tipi di messaggio, con le seguenti eccezioni:

  • Messaggi di notifica inviati quando l'app è in background . In questo caso, la notifica viene recapitata nella barra delle applicazioni del dispositivo. Un utente che tocca una notifica apre l'icona di avvio delle app per impostazione predefinita.

  • Messaggi con notifica e payload di dati, se ricevuti in background . In questo caso, la notifica viene recapitata nella barra delle applicazioni del dispositivo e il payload dei dati viene recapitato negli extra dell'intento dell'attività di avvio.

In sintesi:

Stato dell'app Notifica Dati Entrambi
Primo piano onMessageReceived onMessageReceived onMessageReceived
Sfondo Area di notifica onMessageReceived Notifica: barra delle applicazioni
Dati: negli extra dell'intento.
Per ulteriori informazioni sui tipi di messaggi, vedere Notifiche e messaggi di dati .

Modifica il manifest dell'app

Per utilizzare FirebaseMessagingService , devi aggiungere quanto segue nel manifest dell'app:

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

Inoltre, ti consigliamo di impostare valori predefiniti per personalizzare l'aspetto delle notifiche. È possibile specificare un'icona predefinita personalizzata e un colore predefinito personalizzato che vengono applicati ogni volta che non vengono impostati valori equivalenti nel payload della notifica.

Aggiungi queste righe all'interno del tag application per impostare l'icona predefinita personalizzata e il colore personalizzato:

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

Android visualizza l'icona predefinita personalizzata per

  • Tutti i messaggi di notifica inviati dal compositore di notifiche .
  • Qualsiasi messaggio di notifica che non imposta esplicitamente l'icona nel payload della notifica.

Android utilizza il colore predefinito personalizzato per

  • Tutti i messaggi di notifica inviati dal compositore di notifiche .
  • Qualsiasi messaggio di notifica che non imposta esplicitamente il colore nel payload della notifica.

Se non è impostata alcuna icona predefinita personalizzata e non è impostata alcuna icona nel payload delle notifiche, Android visualizza l'icona dell'applicazione resa in bianco.

Sostituisci onMessageReceived

Eseguendo l'override del metodo FirebaseMessagingService.onMessageReceived , puoi eseguire azioni basate sull'oggetto RemoteMessage ricevuto e ottenere i dati del messaggio:

Kotlin+KTX

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: ${remoteMessage.from}")

    // Check if message contains a data payload.
    if (remoteMessage.data.isNotEmpty()) {
        Log.d(TAG, "Message data payload: ${remoteMessage.data}")

        // Check if data needs to be processed by long running job
        if (needsToBeScheduled()) {
            // For long-running tasks (10 seconds or more) use WorkManager.
            scheduleJob()
        } else {
            // Handle message within 10 seconds
            handleNow()
        }
    }

    // Check if message contains a notification payload.
    remoteMessage.notification?.let {
        Log.d(TAG, "Message Notification Body: ${it.body}")
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}

Java

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    // TODO(developer): Handle FCM messages here.
    // Not getting messages here? See why this may be: https://goo.gl/39bRNJ
    Log.d(TAG, "From: " + remoteMessage.getFrom());

    // Check if message contains a data payload.
    if (remoteMessage.getData().size() > 0) {
        Log.d(TAG, "Message data payload: " + remoteMessage.getData());

        if (/* Check if data needs to be processed by long running job */ true) {
            // For long-running tasks (10 seconds or more) use WorkManager.
            scheduleJob();
        } else {
            // Handle message within 10 seconds
            handleNow();
        }

    }

    // Check if message contains a notification payload.
    if (remoteMessage.getNotification() != null) {
        Log.d(TAG, "Message Notification Body: " + remoteMessage.getNotification().getBody());
    }

    // Also if you intend on generating your own notifications as a result of a received FCM
    // message, here is where that should be initiated. See sendNotification method below.
}

Sostituisci onDeletedMessages eliminati

In alcune situazioni, FCM potrebbe non recapitare un messaggio. Ciò si verifica quando ci sono troppi messaggi (>100) in sospeso per la tua app su un particolare dispositivo nel momento in cui si connette o se il dispositivo non si connette a FCM da più di un mese. In questi casi, potresti ricevere una richiamata a FirebaseMessagingService.onDeletedMessages() . Quando l'istanza dell'app riceve questa richiamata, dovrebbe eseguire una sincronizzazione completa con il server dell'app. Se non hai inviato un messaggio all'app su quel dispositivo nelle ultime 4 settimane, FCM non chiamerà onDeletedMessages() .

Gestisci i messaggi di notifica in un'app in background

Quando la tua app è in background, Android indirizza i messaggi di notifica nella barra delle applicazioni. Un tocco dell'utente sulla notifica apre l'avvio delle app per impostazione predefinita.

Sono inclusi i messaggi che contengono sia notifiche che payload di dati (e tutti i messaggi inviati dalla console delle notifiche). In questi casi, la notifica viene recapitata nella barra delle applicazioni del dispositivo e il payload dei dati viene recapitato negli extra dell'intento dell'attività di avvio.

Per informazioni dettagliate sulla consegna dei messaggi alla tua app, consulta il dashboard dei rapporti FCM , che 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.

Crea richieste di invio

Dopo aver creato un argomento, sottoscrivendo le istanze dell'app client all'argomento sul lato client o tramite l' API del server , puoi inviare messaggi all'argomento. Se è la prima volta che crei richieste di invio per FCM, consulta la guida al tuo ambiente server e FCM per importanti informazioni di base e di configurazione.

Nella logica di invio sul backend, specifica il nome dell'argomento desiderato come mostrato:

Node.js

// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Giava

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Pitone

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Andare

// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

RIPOSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

Comando cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Per inviare un messaggio a una combinazione di argomenti, specificare una condizione , ovvero un'espressione booleana che specifica gli argomenti di destinazione. Ad esempio, la seguente condizione invierà messaggi ai dispositivi iscritti a TopicA e TopicB o TopicC :

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

FCM valuta prima le eventuali condizioni tra parentesi, quindi valuta l'espressione da sinistra a destra. Nell'espressione precedente, un utente iscritto a un singolo argomento non riceve il messaggio. Allo stesso modo, un utente che non è iscritto a TopicA non riceve il messaggio. Queste combinazioni lo ricevono:

  • TopicA e TopicB
  • TopicA e TopicC

Puoi includere fino a cinque argomenti nell'espressione condizionale.

Per inviare a una condizione:

Node.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Giava

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Pitone

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Andare

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

RIPOSO

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

Comando cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Prossimi passi