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

Подписаться на тему можно как на сервере, так и в клиентском приложении.

  • На сервере с помощью 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 подписок на темы версии 1 для приложения "FCM" также можно отменить подписку токена на тему с помощью запроса 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 или токена

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

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