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

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

  • در سرور، بااستفاده از FCM topic subscription server API یا Firebase Admin SDK.

  • در کارخواه، بااستفاده از میانای برنامه‌سازی کاربردی سمت کارخواه در برنامه‌تان.

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

برای مشترک کردن ثبت 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"
    }

FCM V1 topics subscriptions API also lets you unsubscribe a token from a topic through DELETE request:

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

درصورت موفقیت، پاسخ FCM 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");

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

روش‌های 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()
    }

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 برنامه تغییر می‌کند، اشتراک‌های موضوع مرتبط با شناسه نصب Firebase یا کد قدیمی منتقل نمی‌شوند و درنتیجه شناسه جدید اشتراک موضوع ندارد. به‌طور کلی، یک کد درطول به‌روزرسانی‌های برنامه یا بازآوری‌های کد تغییر نمی‌کند. رایج‌ترین دلیل تغییر نشان، حذف/چرخش FID است که می‌توان آن را با دنبال کردن نظارت بر چرخه حیات شناسه نصب Firebase نظارت کرد.

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