Zarządzanie subskrypcjami tematów

Aplikację kliencką możesz zasubskrybować do tematu z poziomu serwera lub klienta:

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

Aby zasubskrybować temat za pomocą rejestracji FCM, przekaż identyfikator rejestracji (identyfikator instalacji Firebase lub token rejestracji FCM) do interfejsu API serwera subskrypcji tematów FCM, 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 API subskrypcji tematów FCM w wersji 1 umożliwia też anulowanie subskrypcji tematu przez token 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. Jeśli masz tokeny rejestracji, możesz zbiorczo subskrybować i anulować subskrypcję instancji aplikacji klienckich, korzystając z logiki serwera.

Możesz zasubskrybować instancje aplikacji klienckiej do dowolnego istniejącego tematu lub utworzyć nowy temat. Gdy używasz interfejsu API do subskrybowania aplikacji klienckiej na nowy temat (który nie istnieje jeszcze w projekcie w Firebase), w FCM tworzony jest nowy temat o tej nazwie, który może być następnie subskrybowany przez dowolnego klienta.

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

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 tematów na urządzeniach 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 (błędy uwierzytelniania, nieprawidłowy token lub temat itp.) te metody zwracają błąd. Pełną listę kodów błędów wraz z opisami i instrukcjami rozwiązywania problemów znajdziesz w artykule Błędy Firebase Admin SDK.

Zarządzanie subskrypcjami tematów z poziomu aplikacji klienckiej

Instancje aplikacji klienckich mogą też być subskrybowane lub odsubskrybowane bezpośrednio z aplikacji za pomocą pakietów SDK Firebase. Pamiętaj, że w przypadku niepowodzenia początkowej próby FCM ponawia próbę, aby zapewnić powodzenie subskrypcji.

Wybierz platformę:

Android

Aplikacje klienckie mogą subskrybować dowolny istniejący temat lub utworzyć nowy. Gdy aplikacja kliencka subskrybuje nowy temat (który nie istnieje jeszcze w projekcie w Firebase), w FCM tworzony jest nowy temat o tej nazwie, który może następnie subskrybować dowolny klient.

Aby zasubskrybować temat, aplikacja kliencka wywołuje Firebase Cloud Messaging subscribeToTopic() z nazwą tematu FCM. Ta metoda zwraca obiekt Task, który może być używany przez detektor ukończenia 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 utworzyć nowy. Gdy aplikacja kliencka subskrybuje nowy temat (który nie istnieje jeszcze w projekcie w Firebase), w FCM tworzony jest nowy temat o tej nazwie, który może następnie subskrybować dowolny klient.

Aby zasubskrybować temat, wywołaj metodę subskrypcji z głównego wątku aplikacji (FCM nie jest wątkowo bezpieczny). Jeśli początkowo prośba o subskrypcję 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żna przechwycić w module 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 do danego tematu. Przed wywołaniem 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 unsubscribeFromTopic:topic, a FCM anuluje subskrypcję tematu w tle.

C++

Aby zasubskrybować temat, wywołaj ::firebase::messaging::Subscribe z aplikacji. Spowoduje to wysłanie żądania asynchronicznego do backendu FCM i zasubskrybowanie klienta do danego tematu.

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

Jeśli początkowa próba subskrypcji się nie powiedzie, FCM będzie próbować, 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::Unsubscribe, a FCM anuluje subskrypcję tematu w tle.

Unity

Aby zasubskrybować temat, wywołaj Firebase.Messaging.FirebaseMessaging.Subscribe z aplikacji. Spowoduje to wysłanie żądania asynchronicznego do backendu FCM i zasubskrybowanie klienta do danego tematu.

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

Jeśli początkowo żądanie subskrypcji 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, a FCM anuluje subskrypcję tematu w tle.

Starsza wersja zarządzania tematami po stronie serwera (wycofana)

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

Zarządzanie subskrypcjami tematów po zmianie 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, 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 FID, co można monitorować, postępując zgodnie z instrukcjami podanymi 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 w backendzie i zasubskrybować nowy identyfikator do tematów, które były wcześniej subskrybowane przez instancję aplikacji. Firebase nie udostępnia żadnych automatycznych funkcji ani możliwości śledzenia lub przenoszenia tych subskrypcji. To zadanie musisz wykonać ręcznie w aplikacji i backendzie.