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

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

  • На сервере с помощью 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 отменит подписку на тему в фоновом режиме.

Устаревший способ управления темами на стороне сервера (не поддерживается)

Подробнее об идентификаторах экземпляров… Подробную информацию об устаревших конечных точках можно найти в документации по Instance ID API.

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

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

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