Zarządzanie subskrypcjami tematów

Aplikację kliencką możesz zasubskrybować w temacie na serwerze lub na urządzeniu klienta:

Zarządzanie subskrypcjami tematów za pomocą interfejsu API serwera subskrypcji tematów

Aby zasubskrybować rejestrację FCM w temacie, przekaż identyfikator rejestracji (identyfikator instalacji Firebase lub token rejestracji FCM) do serwera subskrypcji tematów FCM 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 HTTP v1 API 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

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

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

Możesz przekazać listę tokenów rejestracji do metody Firebase Admin SDKsubskrypcji, aby zasubskrybować odpowiednie urządzenia w temacie:

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 tematu przez urządzenia. Wystarczy przekazać tokeny 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. Typ zwracany ma taki sam format niezależnie od liczby tokenów rejestracyjnych podanych w żądaniu.

W przypadku błędu (niepowodzenia uwierzytelniania, nieprawidłowego tokena lub tematu itp.) te metody powodują błąd. Pełną listę kodów błędów wraz z opisami i instrukcjami rozwiązywania problemów znajdziesz w sekcji Firebase Admin SDK Błędy.

Zarządzanie subskrypcjami tematów w aplikacji klienckiej

Instancje aplikacji klienckich mogą też subskrybować tematy lub anulować subskrypcję bezpośrednio z aplikacji za pomocą pakietów SDK Firebase. Pamiętaj, że w przypadku początkowych niepowodzeń FCM ponawia próby, aby zapewnić pomyślne zakończenie subskrypcji.

Wybierz platformę:

Android

Aplikacje klienckie mogą subskrybować dowolny istniejący temat lub utworzyć nowy. Gdy aplikacja kliencka zasubskrybuje nową nazwę tematu (która nie istnieje jeszcze w Twoim projekcie w Firebase), w FCM zostanie utworzony nowy temat o tej nazwie i każdy klient będzie mógł go zasubskrybować.

Aby zasubskrybować temat, aplikacja kliencka wywołuje funkcję Firebase Cloud Messaging subscribeToTopic() z nazwą tematu FCM. Ta metoda zwraca Task, którego odbiorca 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.

iOS

Aplikacje klienckie mogą subskrybować dowolny istniejący temat lub utworzyć nowy. Gdy aplikacja kliencka zasubskrybuje nową nazwę tematu (która nie istnieje jeszcze w Twoim projekcie w Firebase), w FCM zostanie utworzony nowy temat o tej nazwie i każdy klient będzie mógł go zasubskrybować.

Aby zasubskrybować temat, wywołaj metodę subskrypcji z głównego wątku aplikacji (FCM nie jest bezpieczna dla wątków). Jeśli żądanie subskrypcji początkowo się nie powiedzie, FCM automatycznie ponowi próbę. W przypadku, gdy subskrypcja nie może zostać zrealizowana, zgłasza ona 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 żądanie asynchroniczne do backendu FCM i subskrybuje klienta w danym temacie. Przed wywołaniem funkcji subscribeToTopic:topic upewnij się, że instancja aplikacji klienckiej otrzymała już token rejestracyjny 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ę, zadzwoń pod numer unsubscribeFromTopic:topic.FCM anuluje subskrypcję tematu w tle.

C++

Aby zasubskrybować temat, wywołaj z aplikacji funkcję ::firebase::messaging::Subscribe. 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ę, zadzwoń pod numer ::firebase::messaging::Unsubscribe.FCM anuluje subskrypcję tematu w tle.

Unity

Aby zasubskrybować temat, wywołaj funkcję Firebase.Messaging.FirebaseMessaging.Subscribe w aplikacji. 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ę, zadzwoń pod numer Firebase.Messaging.FirebaseMessaging.Unsubscribe.FCM anuluje subskrypcję tematu w tle.

Starsze zarządzanie tematami po stronie serwera (wycofane)

Aby dowiedzieć się, czym są identyfikatory instancji, odwiedź tę stronę. 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 identyfikator instalacji Firebase (FID) lub token FCM aplikacji ulegnie zmianie, subskrypcje tematów powiązane ze starym identyfikatorem FID lub tokenem nie zostaną przeniesione, w wyniku czego nowy identyfikator nie będzie miał subskrypcji tematów. Zwykle token nie zmienia się podczas aktualizacji aplikacji ani odświeżania tokena. Najczęstszą przyczyną zmiany tokena jest usunięcie lub rotacja identyfikatora instalacji Firebase. Możesz to monitorować, postępując zgodnie z instrukcjami w artykule Monitorowanie cyklu życia identyfikatora instalacji Firebase.

Jeśli chcesz zachować subskrypcje tematów po zmianie 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 na backendzie.