Zarządzanie subskrypcjami tematów

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

Zarządzanie subskrypcjami tematów za pomocą interfejsu topic subscription server API

Aby zasubskrybować rejestrację FCM w temacie, przekaż identyfikator rejestracji (identyfikator instalacji Firebase lub token rejestracji FCM) do interfejsu FCM topic subscription server API, jak pokazano poniżej.

REST

POST https://fcm.googleapis.com/v1/projects/${PROJECT_ID}/registrations/${REGISTRATION_ID}/topicSubscriptions?topic_name=${TOPIC_NAME}

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{}

Polecenie „curl”:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{}'
https://fcm.googleapis.com/v1/projects/${PROJECT_ID}/registrations/${REGISTRATION_ID}/topicSubscriptions?topic_name=${TOPIC_NAME}

W przypadku powodzenia odpowiedź interfejsu API HTTP v1 jest obiektem JSON zawierającym nazwę zasobu, nazwę tematu i sygnaturę czasową.

    {
      "topic_name": "${TOPIC_NAME}",
      "create_time": "2026-01-15T01:30:15.01Z"
    }

Interfejs FCM V1 topics subscriptions API umożliwia też anulowanie subskrypcji tokena w temacie za pomocą żądania DELETE:

REST

DELETE https://fcm.googleapis.com/v1/projects/${PROJECT_ID}/registrations/${REGISTRATION_ID}/topicSubscriptions/${TOPIC_NAME}

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{}

Polecenie „curl”:

curl -X DELETE -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{}'
https://fcm.googleapis.com/v1/projects/$｛PROJECT_ID｝/registrations/${REGISTRATION_ID}/topicSubscriptions/${TOPIC_NAME}

Możesz też wyświetlić listę subskrypcji tematów identyfikatora rejestracji za pomocą żądania GET:

REST

GET https://fcm.googleapis.com/v1/projects/${PROJECT_ID}/registrations/${REGISTRATION_ID}/topicSubscriptions

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Polecenie „curl”:

curl -X GET -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json"
https://fcm.googleapis.com/v1/projects/$｛PROJECT_ID｝/registrations/${REGISTRATION_ID}/topicSubscriptions

W przypadku powodzenia odpowiedź interfejsu HTTP v1 API jest obiektem JSON zawierającym listę subskrypcji tematów.

    {
        "topic_subscriptions": [
          {
              "topic_name": "${TOPIC_NAME1}",
              "create_time": "2026-01-15T01:30:15.01Z"
          },
          {
              "topic_name": "${TOPIC_NAME2}",
              "create_time": "2026-01-16T02:40:17.01Z"
          },
        ...
        ]
    }

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. Na podstawie tokenów rejestracji możesz zbiorczo subskrybować i anulować subskrypcje instancji aplikacji klienckich za pomocą logiki serwera.

Możesz zasubskrybować instancje aplikacji klienckich w dowolnym istniejącym temacie lub utworzyć nowy temat. Gdy używasz interfejsu API do zasubskrybowania 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ć.

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().subscribeToTopicAsync(
    registrationTokens, topic).get();
// 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");

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().unsubscribeFromTopicAsync(
    registrationTokens, topic).get();
// 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");

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. niepowodzenia uwierzytelnienia, nieprawidłowego tokena lub tematu) 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ć i anulować subskrypcje tematów bezpośrednio z aplikacji za pomocą pakietów Firebase SDK. Pamiętaj, że FCM ponawia próby w przypadku początkowych niepowodzeń, aby zapewnić powodzenie subskrypcji.

Wybierz platformę:

Android

Aplikacje klienckie mogą subskrybować dowolny istniejący temat lub tworzyć 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 metodę Firebase Cloud Messaging subscribeToTopic() z nazwą tematu FCM. Ta metoda zwraca Task, którego odbiorca może użyć do określenia, 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()
    }

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 metodę Firebase Cloud Messaging unsubscribeFromTopic() z nazwą tematu.

iOS

Aplikacje klienckie mogą subskrybować dowolny istniejący temat lub tworzyć 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 wątkowo bezpieczny). 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")
}

Objective-C

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

To wywołanie wysyła asynchroniczne żądanie 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ę tematu 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óby, 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, i FCM anuluje subskrypcję tematu 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óby, 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ę tematu w tle.

Starsze zarządzanie tematami po stronie serwera (wycofane)

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.

Zarządzanie subskrypcjami tematów w przypadku zmiany identyfikatora FID lub tokena

Gdy zmieni się identyfikator FID (identyfikator instalacji Firebase) lub token FCM aplikacji, subskrypcje tematów powiązane ze starym identyfikatorem FID lub tokenem nie zostaną przeniesione, a nowy identyfikator nie będzie miał subskrypcji tematu. Zazwyczaj token nie zmienia się podczas aktualizacji aplikacji ani odświeżania tokena. Najczęstszą przyczyną zmiany tokena jest usunięcie lub rotacja identyfikatora FID, którą można monitorować zgodnie z instrukcjami w artykule Monitorowanie cyklu życia identyfikatora instalacji Firebase.

Jeśli chcesz zachować subskrypcje tematów w przypadku zmiany identyfikatora FID lub tokena, musisz utworzyć kopię zapasową danych subskrypcji tematów na kliencie lub backendzie i zasubskrybować nowy identyfikator w tematach, które były wcześniej subskrybowane przez instancję aplikacji. Firebase nie udostępnia żadnych automatycznych funkcji ani możliwości śledzenia ani przenoszenia tych subskrypcji. Jest to zadanie, które musisz zaimplementować ręcznie w aplikacji i backendzie.