Как управлять подписками на темы

Вы можете подписать клиентское приложение на тему с сервера или клиента:

  • На сервере с помощью FCM topic subscription server API или Firebase Admin SDK.

  • На клиенте, используя клиентский API в приложении.

Управление подписками на темы с помощью API сервера подписок на темы

Чтобы зарегистрировать идентификатор FCM в теме, передайте идентификатор регистрации (идентификатор установки Firebase или токен регистрации FCM) в API сервера подписки на темы FCM, как показано ниже.

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

{}

Команда 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}

В случае успеха ответом HTTP v1 API будет объект JSON, содержащий название ресурса, название темы и временную метку.

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

API FCM V1 topics subscriptions также позволяет отменить подписку токена на тему с помощью запроса 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

{}

Команда 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}

Вы также можете получить список подписок на темы для идентификатора регистрации с помощью запроса 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

Команда 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

При успешном выполнении запроса HTTP v1 API возвращает объект JSON, содержащий список подписок на темы.

    {
        "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"
          },
        ...
        ]
    }

Управление подписками на темы с помощью Admin SDK

Firebase Admin SDK позволяет выполнять основные задачи по управлению темами на стороне сервера. Используя токены регистрации, вы можете подписывать и отписывать экземпляры клиентских приложений в массовом порядке, используя логику сервера.

Вы можете подписать экземпляры клиентского приложения на любую существующую тему или создать новую. Когда вы используете API, чтобы подписать клиентское приложение на новую тему (которой ещё нет в вашем проекте Firebase), в FCM создается новая тема с таким названием, и на нее может подписаться любой клиент.

Вы можете передать список токенов регистрации в метод подписки Firebase Admin SDK, чтобы подписать соответствующие устройства на тему:

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')

Проложить маршрут

// 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 также позволяет отменить подписку устройств на тему, передавая токены регистрации в соответствующий метод:

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')

Проложить маршрут

// 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");

Методы subscribeToTopic() и unsubscribeFromTopic() возвращают объект, содержащий ответ от FCM. Формат типа возвращаемого значения не зависит от количества токенов регистрации, указанных в запросе.

В случае ошибки (неудачной аутентификации, недействительного токена или темы и т. д.) эти методы возвращают ошибку. Полный список кодов ошибок с описаниями и инструкциями по устранению приведен в статье Ошибки Firebase Admin SDK.

Как управлять подписками на темы в клиентском приложении

Экземпляры клиентских приложений также могут подписываться на темы или отменять подписку на них непосредственно из вашего приложения через Firebase SDK. Обратите внимание, что в случае сбоя FCM повторит попытку, чтобы подписка была оформлена.

Выберите платформу:

Android

Клиентские приложения могут подписаться на любую существующую тему или создать новую. Когда клиентское приложение подписывается на новую тему (которой ещё нет в проекте Firebase), в FCM создается новая тема с таким названием, и любой клиент может подписаться на нее.

Чтобы подписаться на тему, клиентское приложение вызывает Firebase Cloud Messaging subscribeToTopic() с названием темы FCM. Этот метод возвращает объект Task, который может использоваться прослушивателем завершения, чтобы определить, была ли подписка успешной.

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

Чтобы отменить подписку, клиентское приложение вызывает Firebase Cloud Messaging unsubscribeFromTopic() с названием темы.

iOS

Клиентские приложения могут подписываться на любую существующую тему или создавать новую. Когда клиентское приложение подписывается на новое название темы (которое ещё не существует в вашем проекте Firebase), в FCM создается новая тема с этим названием, и любой клиент может подписаться на нее.

Чтобы подписаться на тему, вызовите метод подписки из основного потока приложения (FCM не является потокобезопасным). Если запрос на подписку не удастся выполнить с первого раза, FCM автоматически повторит попытку. Если подписку оформить не удается, она возвращает ошибку, которую можно перехватить в обработчике завершения, как показано ниже:

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");
}];

Этот вызов отправляет асинхронный запрос к серверной части FCM и подписывает клиента на указанную тему. Прежде чем вызывать subscribeToTopic:topic, убедитесь, что экземпляр клиентского приложения уже получил токен регистрации через обратный вызов didReceiveRegistrationToken.

При каждом запуске приложения FCM проверяет, подписаны ли все запрошенные темы. Чтобы отменить подписку, вызовите unsubscribeFromTopic:topic, и FCM отменит подписку на тему в фоновом режиме.

C++

Чтобы подписаться на тему, вызовите ::firebase::messaging::Subscribe из своего приложения. Это позволяет отправить асинхронный запрос к серверной части FCM и подписать клиента на указанную тему.

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

Если запрос на подписку не удастся выполнить с первого раза, FCM будет повторять попытки, пока не сможет подписаться на тему. При каждом запуске приложения FCM проверяет, подписаны ли все запрошенные темы.

Чтобы отменить подписку, вызовите ::firebase::messaging::Unsubscribe, и FCM отменит подписку на тему в фоновом режиме.

Unity

Чтобы подписаться на тему, вызовите метод Firebase.Messaging.FirebaseMessaging.Subscribe из своего приложения. Это позволяет отправить асинхронный запрос на серверную часть FCM и подписать клиента на указанную тему.

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

Если запрос на подписку не удается выполнить с первого раза, FCM повторяет попытки, пока не подпишется на тему. При каждом запуске приложения FCM проверяет, оформлена ли подписка на все запрошенные темы.

Чтобы отменить подписку, вызовите Firebase.Messaging.FirebaseMessaging.Unsubscribe, и FCM отменит подписку на тему в фоновом режиме.

Устаревшее управление темами на стороне сервера (устарело)

Чтобы узнать, что такое идентификаторы экземпляров, перейдите на эту страницу. Подробнее о конечных точках, поддержка которых прекращена…

Управление подписками на темы при изменении FID или токена

Когда идентификатор установки Firebase (FID) или токен FCM приложения меняется, подписки на темы, связанные со старым FID или токеном, не переносятся, и в результате у нового идентификатора нет подписки на темы. Как правило, токен не меняется при обновлении приложения или токена. Самая распространенная причина изменения токена – удаление или ротация FID. Подробнее о том, как отслеживать жизненный цикл идентификатора установки Firebase…

Если вы хотите сохранить подписки на темы при изменении FID или токена, вам необходимо создать резервную копию данных о подписках на темы на клиенте или в серверной части и подписать новый идентификатор на темы, на которые ранее был подписан экземпляр приложения. Firebase не предоставляет автоматических функций или возможностей для отслеживания или переноса этих подписок. Это задача, которую вы должны реализовать вручную в своем приложении и серверной части.