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

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

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

  • در کارخواه، بااستفاده از 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}

درصورت موفقیت، پاسخ FCM HTTP v1 API یک شیء JSON است که حاوی نام منبع، نام موضوع، و مُهر زمان است.

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

میانای برنامه‌سازی کاربردی 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

درصورت موفقیت، پاسخ 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"
          },
        ...
        ]
    }

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

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 اشتراک موضوع را در پس‌زمینه لغو می‌کند.

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

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

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

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

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