‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

مدیریت اشتراک‌های موضوعی

می‌توانید برنامه کارخواه را ازطریق سرور یا کارخواه در موضوعی مشترک کنید:

در سرور، بااستفاده از FCM topic subscription server API یا Firebase Admin SDK.
در کارخواه، بااستفاده از میانای برنامه‌سازی کاربردی سمت کارخواه در برنامه‌تان.

مدیریت اشتراک‌های موضوع بااستفاده از میانای برنامه‌سازی کاربردی سرور اشتراک موضوع

برای مشترک کردن ثبت FCM در یک موضوع، شناسه ثبت (شناسه نصب Firebase یا کد ثبت FCM) را به میانای برنامه‌سازی کاربردی سرور اشتراک موضوع 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"
    }

FCM V1 topics subscriptions API همچنین به شما امکان می‌دهد اشتراک یک توکن را از یک موضوع ازطریق درخواست 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);
  });

جاوا

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

پایتون

# 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")

سی شارپ

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

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

جاوا

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

پایتون

# 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")

سی شارپ

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

روش‌های subscribeToTopic() و unsubscribeFromTopic() منجر به ایجاد شیئی می‌شوند که حاوی پاسخ از FCM است. نوع پاسخ، صرف‌نظر از تعداد توکن‌های ثبت مشخص‌شده در درخواست، قالب یکسانی دارد.

درصورت بروز خطا (ناموفق بودن اصالت‌سنجی، نامعتبر بودن کد یا موضوع، و غیره) این روش‌ها به خطا منجر می‌شوند. برای مشاهده فهرست کامل کدهای خطا، ازجمله شرح و مراحل حل مشکل، به خطاهای Firebase Admin SDK مراجعه کنید.

مدیریت اشتراک‌های موضوع از برنامه کارخواه

نمونه‌های برنامه مشتری نیز می‌توانند مستقیماً ازطریق کیت‌های توسعه نرم‌افزار Firebase در برنامه شما در موضوعات مشترک شوند یا اشتراکشان را لغو کنند. توجه داشته باشید که 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()
    }MainActivity.kt

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

برای لغو اشتراک، برنامه کارخواه Firebase Cloud Messaging unsubscribeFromTopic() را با نام موضوع فراخوانی می‌کند.

iOS

برای مشترک شدن در موضوع، روش اشتراک را از رشته اصلی برنامه‌تان فراخوانی کنید (FCM رشته‌ای امن نیست). اگر درخواست اشتراک در ابتدا ناموفق باشد، FCM به‌طور خودکار دوباره امتحان می‌کند. برای مواردی که اشتراک نمی‌تواند تکمیل شود، اشتراک خطایی را ایجاد می‌کند که می‌توانید آن را در یک کنترل‌کننده تکمیل، همان‌طور که نشان داده شده است، دریافت کنید:

Swift

Messaging.messaging().subscribe(toTopic: "weather") { error in
  print("Subscribed to weather topic")
}MigratedSnippets.swift

Objective-C

[[FIRMessaging messaging] subscribeToTopic:@"weather"
                                completion:^(NSError * _Nullable error) {
  NSLog(@"Subscribed to weather topic");
}];ObjCMigratedSnippets.m

این فراخوانی یک درخواست ناهمگام به باطن 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");

برای لغو اشتراک، Firebase.Messaging.FirebaseMessaging.Unsubscribe را فراخوانی کنید، و FCM در پس‌زمینه اشتراک موضوع را لغو می‌کند.

مدیریت موضوع قدیمی سمت سرور (منسوخ‌شده)

برای درک اینکه «شناسه نمونه» چیست، به صفحه شناسه نمونه مراجعه کنید. برای جزئیات مربوط به پایانه‌های منسوخ‌شده، به مراجع میانای برنامه‌سازی کاربردی شناسه نمونه مراجعه کنید.

مدیریت اشتراک‌های موضوع در FID یا تغییر کد

وقتی FID (شناسه نصب Firebase) یا کد FCM برنامه تغییر می‌کند، اشتراک‌های موضوع مرتبط با FID یا کد قدیمی منتقل نمی‌شوند و درنتیجه شناسه جدید هیچ اشتراک موضوعی ندارد. به‌طور کلی، یک کد درطول به‌روزرسانی‌های برنامه یا بازآوری‌های کد تغییر نمی‌کند. رایج‌ترین دلیل تغییر توکن، حذف/ چرخش FID است که می‌توان آن را با دنبال کردن چرخه حیات شناسه نصب Firebase را پایش کنید پایش کرد.

اگر می‌خواهید اشتراک‌های موضوع را در FID یا تغییرات کد حفظ کنید، باید از داده‌های اشتراک موضوع در کارخواه یا پس‌بک پشتیبان‌گیری کنید و شناسه جدید را در موضوعاتی که نمونه برنامه قبلاً در آن‌ها مشترک شده بود مشترک کنید. Firebase هیچ ویژگی یا قابلیت خودکاری برای ردیابی یا انتقال این اشتراک‌ها ارائه نمی‌دهد. این تکلیفی است که باید به‌صورت دستی در برنامه و باطن خود پیاده‌سازی کنید.

مدیریت اشتراک‌های موضوعی با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

مدیریت اشتراک‌های موضوع بااستفاده از میانای برنامه‌سازی کاربردی سرور اشتراک موضوع

REST (انتقال بازنمودی وضعیت)

REST (انتقال بازنمودی وضعیت)

REST (انتقال بازنمودی وضعیت)

مدیریت اشتراک‌های موضوع بااستفاده از Admin SDK

Node.js

جاوا

پایتون

رفتن

سی شارپ

Node.js

جاوا

پایتون

رفتن

سی شارپ

مدیریت اشتراک‌های موضوع از برنامه کارخواه

Android

Kotlin

Java

iOS

Swift

Objective-C

C++‎

Unity

مدیریت موضوع قدیمی سمت سرور (منسوخ‌شده)

مدیریت اشتراک‌های موضوع در FID یا تغییر کد

مدیریت اشتراک‌های موضوعی