Zarządzanie subskrypcjami tematów

Aplikację kliencką możesz zasubskrybować w temacie na serwerze lub na kliencie:

• Na serwerze za pomocą Firebase Admin SDK.

• Na kliencie za pomocą interfejsu API po stronie klienta w aplikacji.

Zarządzanie subskrypcjami tematów za pomocą pakietu Admin SDK

Pakiet Firebase Admin SDK Firebase Admin SDK umożliwia wykonywanie podstawowych zadań związanych z zarządzaniem tematami po stronie serwera. Znając tokeny rejestracji, możesz zbiorczo subskrybować i anulować subskrypcje instancji aplikacji klienckich za pomocą logiki serwera.

Możesz subskrybować instancje aplikacji klienckich w dowolnym istniejącym temacie lub utworzyć nowy temat. Gdy używasz interfejsu API do subskrybowania aplikacji klienckiej w nowym temacie (który jeszcze nie istnieje w Twoim projekcie w Firebase), w FCM tworzony jest nowy temat o tej nazwie i każdy klient może go później zasubskrybować.

Ważne: aby używać Firebase Admin SDK, musisz najpierw wykonać czynności opisane w sekcji Dodawanie pakietu Firebase Admin SDK do serwera, aby zainicjować pakiet SDK.

Aby zasubskrybować odpowiednie urządzenia w temacie, możesz przekazać listę tokenów rejestracji do metody Firebase Admin SDK subskrypcji:

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Subscribe the devices corresponding to the registration tokens to the
// topic.
getMessaging().subscribeToTopic(registrationTokens, topic)
  .then((response) => {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully subscribed to topic:', response);
  })
  .catch((error) => {
    console.log('Error subscribing to topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Subscribe the devices corresponding to the registration tokens to the
// topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().subscribeToTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were subscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Subscribe the devices corresponding to the registration tokens to the
# topic.
response = messaging.subscribe_to_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were subscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Subscribe the devices corresponding to the registration tokens to the
// topic.
response, err := client.SubscribeToTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were subscribed successfully")

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};

// Subscribe the devices corresponding to the registration tokens to the
// topic
var response = await FirebaseMessaging.DefaultInstance.SubscribeToTopicAsync(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were subscribed successfully");
FirebaseMessagingSnippets.cs

Firebase Admin SDK umożliwia też anulowanie subskrypcji urządzeń w temacie przez przekazanie tokenów rejestracji do odpowiedniej metody:

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // ...
  'YOUR_REGISTRATION_TOKEN_n'
];

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
getMessaging().unsubscribeFromTopic(registrationTokens, topic)
  .then((response) => {
    // See the MessagingTopicManagementResponse reference documentation
    // for the contents of response.
    console.log('Successfully unsubscribed from topic:', response);
  })
  .catch((error) => {
    console.log('Error unsubscribing from topic:', error);
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
TopicManagementResponse response = FirebaseMessaging.getInstance().unsubscribeFromTopic(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " tokens were unsubscribed successfully");

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_n',
]

# Unubscribe the devices corresponding to the registration tokens from the
# topic.
response = messaging.unsubscribe_from_topic(registration_tokens, topic)
# See the TopicManagementResponse reference documentation
# for the contents of response.
print(response.success_count, 'tokens were unsubscribed successfully')

Go

// These registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}

// Unsubscribe the devices corresponding to the registration tokens from
// the topic.
response, err := client.UnsubscribeFromTopic(ctx, registrationTokens, topic)
if err != nil {
	log.Fatalln(err)
}
// See the TopicManagementResponse reference documentation
// for the contents of response.
fmt.Println(response.SuccessCount, "tokens were unsubscribed successfully")

C#

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};

// Unsubscribe the devices corresponding to the registration tokens from the
// topic
var response = await FirebaseMessaging.DefaultInstance.UnsubscribeFromTopicAsync(
    registrationTokens, topic);
// See the TopicManagementResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} tokens were unsubscribed successfully");
FirebaseMessagingSnippets.cs

Uwaga: w jednym żądaniu możesz zasubskrybować lub anulować subskrypcję maksymalnie 1000 urządzeń. Jeśli podasz tablicę z ponad 1000 tokenów rejestracji, żądanie zakończy się niepowodzeniem z powodu błędu messaging/invalid-argument.

Metody subscribeToTopic() i unsubscribeFromTopic() zwracają obiekt zawierający odpowiedź z FCM. Zwracany typ ma ten sam format niezależnie od liczby tokenów rejestracji określonych w żądaniu.

W przypadku błędu (np. nieudane uwierzytelnienie, nieprawidłowy token lub temat) metody te zwracają błąd. Pełną listę kodów błędów wraz z opisami i instrukcjami rozwiązywania problemów znajdziesz w artykule Firebase Admin SDK Błędy.

Zarządzanie subskrypcjami tematów z aplikacji klienckiej

Instancje aplikacji klienckich można też subskrybować w tematach lub anulować ich subskrypcje bezpośrednio z aplikacji za pomocą pakietów Firebase SDK. Pamiętaj, że FCM ponawia próby w przypadku początkowych niepowodzeń, aby zapewnić pomyślne subskrybowanie.

Wybierz platformę:

Android

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

Aby zasubskrybować temat, aplikacja kliencka wywołuje Firebase Cloud Messaging subscribeToTopic() z nazwą tematu FCM. Ta metoda zwraca Task, którego można użyć w detektorze zakończenia, aby określić, czy subskrypcja się powiodła:

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()
    }
MainActivity.kt

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

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

iOS

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

Aby zasubskrybować temat, wywołaj metodę subskrypcji z głównego wątku aplikacji (FCM nie jest bezpieczny dla wątków). Jeśli żądanie subskrypcji początkowo się nie powiedzie, FCM automatycznie ponowi próbę. W przypadkach, gdy nie można ukończyć subskrypcji, subskrypcja zgłasza błąd, który możesz przechwycić w procedurze obsługi zakończenia, jak pokazano poniżej:

Swift

Messaging.messaging().subscribe(toTopic: "weather") { error in
  print("Subscribed to weather topic")
}
MigratedSnippets.swift

Objective-C

[[FIRMessaging messaging] subscribeToTopic:@"weather"
                                completion:^(NSError * _Nullable error) {
  NSLog(@"Subscribed to weather topic");
}];
ObjCMigratedSnippets.m

To wywołanie wysyła żądanie asynchroniczne do FCM backendu i subskrybuje klienta w danym temacie. Zanim wywołasz metodę subscribeToTopic:topic, upewnij się, że instancja aplikacji klienckiej otrzymała już token rejestracji za pomocą wywołania zwrotnego didReceiveRegistrationToken.

Za każdym razem, gdy aplikacja się uruchamia, FCM sprawdza, czy wszystkie żądane tematy zostały zasubskrybowane. Aby anulować subskrypcję, wywołaj metodę unsubscribeFromTopic:topic, a FCM anuluje subskrypcję w tle.

C++

Aby zasubskrybować temat, wywołaj metodę ::firebase::messaging::Subscribe z aplikacji. To wywołanie wysyła żądanie asynchroniczne do backendu FCM i subskrybuje klienta w danym temacie.

::firebase::messaging::Subscribe("example");

Jeśli żądanie subskrypcji początkowo się nie powiedzie, FCM ponawia próbę, dopóki nie uda się zasubskrybować tematu. Za każdym razem, gdy aplikacja się uruchamia, FCM sprawdza, czy wszystkie żądane tematy zostały zasubskrybowane.

Aby anulować subskrypcję, wywołaj metodę ::firebase::messaging::Unsubscribe, a FCM anuluje subskrypcję w tle.

Unity

Aby zasubskrybować temat, wywołaj Firebase.Messaging.FirebaseMessaging.Subscribe z aplikacji. To wywołanie wysyła żądanie asynchroniczne do backendu FCM i subskrybuje klienta w danym temacie.

Firebase.Messaging.FirebaseMessaging.Subscribe("/topics/example");

Jeśli żądanie subskrypcji początkowo się nie powiedzie, FCM ponawia próbę, dopóki nie uda się zasubskrybować tematu. Za każdym razem, gdy aplikacja się uruchamia, FCM sprawdza, czy wszystkie żądane tematy zostały zasubskrybowane.

Aby anulować subskrypcję, wywołaj Firebase.Messaging.FirebaseMessaging.Unsubscribe, i FCM anuluje subskrypcję w tle.

Starsze zarządzanie tematami po stronie serwera (wycofane)

Ostrzeżenie: starsza usługa Instance ID składa się z interfejsów API typu REST do zarządzania subskrypcjami tematów, w tym do dodawania i usuwania poszczególnych tokenów oraz do operacji zbiorczych. Te interfejsy API zostały wycofane i nie są już zalecane w przypadku nowych projektów.

Aby dowiedzieć się, czym są identyfikatory instancji, odwiedź stronę Identyfikator instancji. Szczegółowe informacje o wycofanych punktach końcowych znajdziesz w dokumentacji interfejsu Instance ID API.