Wysyłanie wiadomości na wiele urządzeń

Aby kierować wiadomości na wiele urządzeń, użyj wiadomości tematycznych. Ta funkcja umożliwia wysyłanie wiadomości na wiele urządzeń, które subskrybują określony temat.

W tym samouczku skupimy się na wysyłaniu wiadomości dotyczących tematów z serwera aplikacji za pomocą Admin SDK lub interfejsu REST API dla FCM oraz na odbieraniu i obsłudze tych wiadomości w aplikacji na Androida. Omówimy obsługę wiadomości w przypadku aplikacji działających w tle i na pierwszym planie. Obejmuje to wszystkie czynności, od konfiguracji po weryfikację.

Konfigurowanie pakietu SDK

Ta sekcja może zawierać czynności, które zostały już wykonane, jeśli skonfigurowano aplikację kliencką na Androida na potrzeby FCM lub wykonano czynności opisane w artykule Wysyłanie pierwszej wiadomości.

Zanim zaczniesz

  • Zainstaluj lub zaktualizuj Android Studio do najnowszej wersji.

  • Upewnij się, że Twój projekt spełnia te wymagania (pamiętaj, że niektóre produkty mogą mieć bardziej rygorystyczne wymagania):

    • kierować aplikację co najmniej na poziom API 21 (Lollipop);
    • ma zainstalowanego Androida w wersji 5.0 lub nowszej,
    • Korzysta z Jetpacka (AndroidX), który spełnia te wymagania dotyczące wersji:
      • com.android.tools.build:gradle w wersji 7.3.0 lub nowszej
      • compileSdkVersion 28 lub nowsza
  • Skonfiguruj urządzenie fizyczne lub użyj emulatora, aby uruchomić aplikację.
    Pamiętaj, że pakiety SDK Firebase z zależnością od Usług Google Play wymagają, aby na urządzeniu lub emulatorze były zainstalowane Usługi Google Play.

  • Zaloguj się w Firebase, używając konta Google.

Jeśli nie masz jeszcze projektu na Androida, a chcesz tylko wypróbować usługę Firebase, możesz pobrać jeden z naszych przykładowych projektów szybkiego startu.

Tworzenie projektu Firebase

Zanim dodasz Firebase do aplikacji na Androida, musisz utworzyć projekt Firebase, aby połączyć go z tą aplikacją. Więcej informacji o projektach Firebase znajdziesz w artykule Informacje o projektach Firebase.

Rejestrowanie aplikacji w Firebase

Aby korzystać z Firebase w aplikacji na Androida, musisz zarejestrować aplikację w projekcie Firebase. Rejestracja aplikacji jest często nazywana „dodawaniem” aplikacji do projektu.

  1. Otwórz Firebasekonsolę.

  2. W centrum strony „Opis” projektu kliknij ikonę Android lub Dodaj aplikację, aby uruchomić proces konfiguracji.

  3. Wpisz nazwę pakietu aplikacji w polu Nazwa pakietu na Androida.

  4. (Opcjonalnie) wpisz inne informacje o aplikacji: pseudonim aplikacjiskrót SHA-1 certyfikatu podpisywania do debugowania.

  5. Kliknij Zarejestruj aplikację.

Dodawanie pliku konfiguracyjnego Firebase

  1. Pobierz, a następnie dodaj do bazy kodu plik konfiguracyjny Firebase aplikacji (google-services.json):

    1. Kliknij Pobierz google-services.json, aby uzyskać plik konfiguracyjny Firebase aplikacji.

    2. Przenieś plik konfiguracyjny do głównego katalogu modułu (na poziomie aplikacji) aplikacji.

  2. Aby wartości w pliku konfiguracyjnym google-services.json były dostępne dla pakietów SDK Firebase, potrzebujesz wtyczki Gradle usług Google (google-services).

    1. W pliku Gradle na poziomie głównym (poziomie projektu) (<project>/build.gradle.kts lub <project>/build.gradle) dodaj wtyczkę usług Google jako zależność:

      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.3" 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.3' apply false
      }
    2. W pliku Gradle modułu (na poziomie aplikacji) (zwykle <project>/<app-module>/build.gradle.kts lub <project>/<app-module>/build.gradle) dodaj wtyczkę usług 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'
        // ...
      }

Dodawanie pakietów SDK Firebase do aplikacji

  1. pliku Gradle modułu (na poziomie aplikacji) (zwykle <project>/<app-module>/build.gradle.kts lub <project>/<app-module>/build.gradle) dodaj zależność z biblioteką Firebase Cloud Messaging na Androida. Zalecamy używanie Firebase Android BoM do kontrolowania wersji biblioteki.

    Aby w pełni korzystać z Firebase Cloud Messaging, zalecamy włączenie Google Analytics w projekcie Firebase i dodanie do aplikacji pakietu SDK Firebase dla Google Analytics.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:34.0.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")
    }

    Gdy korzystamy z Firebase Android BoM, aplikacja zawsze używa zgodnych wersji bibliotek Firebase na Androida.

    (Alternatywnie)  Dodaj zależności biblioteki Firebase bez użycia BoM

    Jeśli nie chcesz używać Firebase BoM, musisz określić każdą wersję biblioteki Firebase w wierszu zależności.

    Pamiętaj, że jeśli w aplikacji używasz wielu bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek, co zapewnia zgodność wszystkich wersji.

    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:25.0.0")
        implementation("com.google.firebase:firebase-analytics:23.0.0")
    }

  2. Zsynchronizuj projekt na Androida z plikami Gradle.

Subskrybowanie tematu przez aplikację kliencką

Aplikacje klienckie mogą subskrybować dowolny istniejący temat lub tworzyć nowy. Gdy aplikacja kliencka subskrybuje nową nazwę tematu (która nie istnieje jeszcze w Twoim projekcie Firebase), w FCM tworzony jest nowy temat o tej nazwie i każdy klient może go później subskrybować.

Aby zasubskrybować temat, aplikacja kliencka wywołuje funkcję Firebase Cloud Messaging subscribeToTopic()FCM nazwą tematu. Ta metoda zwraca obiekt Task, którego detektor zakończenia może użyć do określenia, czy subskrypcja została utworzona:

Kotlin

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

Aby anulować subskrypcję, aplikacja kliencka wywołuje funkcję Firebase Cloud Messaging unsubscribeFromTopic() z nazwą tematu.

Odbieranie i obsługa wiadomości dotyczących tematu

FCM dostarcza wiadomości o tematach w taki sam sposób jak inne wiadomości wysyłane do urządzenia.

Aby otrzymywać wiadomości, użyj usługi, która rozszerza FirebaseMessagingService. Usługa powinna zastępować wywołania zwrotne onMessageReceivedonDeletedMessages.

Okres na obsługę wiadomości może być krótszy niż 20 sekund w zależności od opóźnień przed wywołaniem funkcji onMessageReceived, w tym opóźnień systemu operacyjnego, czasu uruchamiania aplikacji, zablokowania głównego wątku przez inne operacje lub zbyt długiego czasu trwania poprzednich wywołań funkcji onMessageReceived. Po tym czasie różne zachowania systemu operacyjnego, takie jak zamykanie procesów w Androidzie czy limity wykonywania w tle w Androidzie O, mogą utrudniać dokończenie pracy.

onMessageReceived jest dostępny w przypadku większości typów wiadomości, z wyjątkiem:

  • Wiadomości z powiadomieniami dostarczane, gdy aplikacja działa w tle. W takim przypadku powiadomienie jest dostarczane do obszaru powiadomień urządzenia. Gdy użytkownik kliknie powiadomienie, domyślnie otworzy się menu z aplikacjami.

  • Wiadomości z ładunkiem powiadomienia i danych, gdy są odbierane w tle. W takim przypadku powiadomienie jest dostarczane do zasobnika systemowego urządzenia, a ładunek danych jest dostarczany w dodatkach do intencji aktywności programu uruchamiającego.

W skrócie:

Stan aplikacji Powiadomienie Dane Oba rodzaje
Pierwszy plan onMessageReceived onMessageReceived onMessageReceived
Tło Obszar powiadomień onMessageReceived Powiadomienie: zasobnik systemowy
Dane: w dodatkach do intencji.
Więcej informacji o typach wiadomości znajdziesz w artykule Powiadomienia i wiadomości z danymi.

Edytowanie pliku manifestu aplikacji

Aby używać FirebaseMessagingService, musisz dodać do pliku manifestu aplikacji następujące elementy:

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

Zalecamy też ustawienie wartości domyślnych, aby dostosować wygląd powiadomień. Możesz określić niestandardową ikonę domyślną i niestandardowy kolor domyślny, które będą stosowane, gdy w ładunku powiadomienia nie będą ustawione równoważne wartości.

Dodaj te wiersze w tagu application, aby ustawić niestandardową ikonę domyślną i niestandardowy kolor:

<!-- 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 wyświetla niestandardową ikonę domyślną dla

  • Wszystkie wiadomości z powiadomieniami wysyłane z  edytora powiadomień.
  • Każda wiadomość powiadomienia, która nie zawiera ikony w ładunku powiadomienia.

Android używa niestandardowego koloru domyślnego w przypadku

  • Wszystkie wiadomości z powiadomieniami wysyłane z  edytora powiadomień.
  • Każda wiadomość z powiadomieniem, która nie zawiera w ładunku powiadomienia wyraźnego ustawienia koloru.

Jeśli nie ustawiono niestandardowej ikony domyślnej ani ikony w ładunku powiadomienia, Android wyświetla ikonę aplikacji w kolorze białym.

Zastąp onMessageReceived

Zastępując metodę FirebaseMessagingService.onMessageReceived, możesz wykonywać działania na podstawie otrzymanego obiektu RemoteMessage i pobierać dane wiadomości:

Kotlin

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

Zastąp onDeletedMessages

W niektórych sytuacjach usługa FCM może nie dostarczyć wiadomości. Dzieje się tak, gdy w momencie połączenia na urządzeniu jest zbyt wiele oczekujących wiadomości (>100) dla Twojej aplikacji lub gdy urządzenie nie łączyło się z FCM od ponad miesiąca. W takich przypadkach możesz otrzymać wywołanie zwrotne na adres FirebaseMessagingService.onDeletedMessages(). Gdy instancja aplikacji otrzyma to wywołanie zwrotne, powinna przeprowadzić pełną synchronizację z serwerem aplikacji. Jeśli w ciągu ostatnich 4 tygodni nie wysłano z tego urządzenia wiadomości do aplikacji, FCM nie zadzwoni do onDeletedMessages().

Obsługa wiadomości z powiadomieniami w aplikacji działającej w tle

Gdy aplikacja działa w tle, Android kieruje wiadomości z powiadomieniami do obszaru powiadomień. Gdy użytkownik kliknie powiadomienie, domyślnie otworzy się menu z aplikacjami.

Dotyczy to wiadomości zawierających zarówno powiadomienia, jak i ładunek danych (oraz wszystkich wiadomości wysyłanych z konsoli powiadomień). W takich przypadkach powiadomienie jest dostarczane do zasobnika systemowego urządzenia, a ładunek danych jest dostarczany w dodatkach do intencji aktywności programu uruchamiającego.

Aby uzyskać informacje o dostarczaniu wiadomości do aplikacji, otwórz FCM panel raportowania, który rejestruje liczbę wysłanych i otwartych wiadomości na urządzeniach z Androidem i Apple, a także dane o „wyświetleniach” (powiadomieniach widocznych dla użytkowników) w przypadku aplikacji na Androida.

Tworzenie próśb o wysłanie

Po utworzeniu tematu (przez subskrybowanie instancji aplikacji klienckiej w temacie po stronie klienta lub za pomocą interfejsu API serwera) możesz wysyłać do niego wiadomości. Jeśli po raz pierwszy tworzysz żądania wysyłania dla FCM, zapoznaj się z przewodnikiem dotyczącym środowiska serwera i FCM, aby uzyskać ważne informacje o konfiguracji i kontekście.

W logice wysyłania na backendzie określ nazwę tematu w sposób pokazany poniżej:

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

Java

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

Python

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

Go

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

REST

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

Polecenie 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

Aby wysłać wiadomość do kombinacji tematów, określ warunek, czyli wyrażenie logiczne, które określa docelowe tematy. Na przykład ten warunek spowoduje wysłanie wiadomości na urządzenia, które subskrybują TopicA oraz TopicB lub TopicC:

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

FCM najpierw sprawdza warunki w nawiasach, a potem wyrażenie od lewej do prawej. W powyższym wyrażeniu użytkownik subskrybujący dowolny pojedynczy temat nie otrzyma wiadomości. Podobnie użytkownik, który nie subskrybuje TopicA, nie otrzyma wiadomości. Te kombinacje otrzymują go:

  • TopicA i TopicB
  • TopicA i TopicC

W wyrażeniu warunkowym możesz uwzględnić maksymalnie 5 tematów.

Aby wysłać do warunku:

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

Java

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

Python

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

Go

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

REST

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",
    }
  }
}

Polecenie 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

Dalsze kroki