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 nowszejcompileSdkVersion
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.
Otwórz Firebasekonsolę.
W centrum strony „Opis” projektu kliknij ikonę Android
lub Dodaj aplikację, aby uruchomić proces konfiguracji.Wpisz nazwę pakietu aplikacji w polu Nazwa pakietu na Androida.
(Opcjonalnie) wpisz inne informacje o aplikacji: pseudonim aplikacji i skrót SHA-1 certyfikatu podpisywania do debugowania.
Kliknij Zarejestruj aplikację.
Dodawanie pliku konfiguracyjnego Firebase
Pobierz, a następnie dodaj do bazy kodu plik konfiguracyjny Firebase aplikacji (
):google-services.json Kliknij Pobierz google-services.json, aby uzyskać plik konfiguracyjny Firebase aplikacji.
Przenieś plik konfiguracyjny do głównego katalogu modułu (na poziomie aplikacji) aplikacji.
Aby wartości w pliku konfiguracyjnym
były dostępne dla pakietów SDK Firebase, potrzebujesz wtyczki Gradle usług Google (google-services.json google-services
).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 }
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
W 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") }
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()
z 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 onMessageReceived
i onDeletedMessages
.
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. |
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
iTopicB
TopicA
iTopicC
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
- Możesz używać serwera do subskrybowania instancji aplikacji klienckich w tematach i wykonywania innych zadań związanych z zarządzaniem. Zobacz Zarządzanie subskrypcjami tematów na serwerze.