إدارة الاشتراكات في المواضيع

يمكنك الاشتراك في تطبيق عميل لموضوع معيّن من الخادم أو العميل:

إدارة الاشتراكات في المواضيع باستخدام واجهة برمجة التطبيقات لخادم الاشتراك في المواضيع

للاشتراك في موضوع معيّن من خلال 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 عبارة عن عنصر 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 عبارة عن عنصر 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"
          },
        ...
        ]
    }

إدارة الاشتراكات في المواضيع باستخدام مدير SDK

تتيح لك Firebase Admin SDK تنفيذ مهام إدارة المواضيع الأساسية من جانب الخادم. وبعد الحصول على رموز التسجيل المميّزة، يمكنك الاشتراك في نُسخ تطبيق العميل وإلغاء الاشتراك فيها بشكل مجمّع باستخدام منطق الخادم.

يمكنك الاشتراك في نُسخ تطبيق العميل لأي موضوع حالي، أو يمكنك إنشاء موضوع جديد. عند استخدام واجهة برمجة التطبيقات للاشتراك في تطبيق عميل لموضوع جديد (غير موجود في مشروع 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.

إدارة الاشتراكات في المواضيع من تطبيق العميل

يمكن أيضًا الاشتراك في المواضيع أو إلغاء الاشتراك فيها من خلال مثيلات تطبيق العميل مباشرةً من تطبيقك عبر حِزم تطوير البرامج (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 من الموضوع في الخلفية.

إدارة المواضيع القديمة من جهة الخادم (متوقفة نهائيًا)

لفهم المقصود بأرقام تعريف المثيلات، يُرجى الانتقال إلى صفحة "رقم تعريف المثيل". لمعرفة التفاصيل حول نقاط النهاية المتوقفة نهائيًا، يُرجى الاطّلاع على مراجع واجهة برمجة التطبيقات Instance ID.

إدارة الاشتراكات في المواضيع عند تغيير معرّف مثيل Firebase أو الرمز المميّز

عندما يتغيّر معرّف تثبيت Firebase‏ (FID) أو الرمز المميّز FCM لتطبيق معيّن، لا يتم نقل اشتراكات المواضيع المرتبطة بمعرّف FID أو الرمز المميّز القديم، وبالتالي لا يتضمّن المعرّف الجديد أي اشتراك في المواضيع. بشكل عام، لا يتغيّر الرمز المميّز أثناء تحديثات التطبيق أو إعادة تحميل الرمز المميّز. السبب الأكثر شيوعًا لتغيير الرمز المميّز هو حذف/تبديل معرّف Firebase، والذي يمكن تتبُّعه من خلال اتّباع الخطوات الواردة في مقالة تتبُّع مراحل نشاط معرّف Firebase.

إذا أردت الاحتفاظ باشتراكات المواضيع عند تغيير معرّف مثيل Firebase أو الرمز المميّز، عليك الاحتفاظ بنسخة احتياطية من بيانات اشتراك المواضيع على العميل أو الخلفية والاشتراك في المعرّف الجديد للمواضيع التي سبق لمثيل التطبيق الاشتراك فيها. لا توفّر Firebase أي ميزات أو إمكانات تلقائية لتتبُّع هذه الاشتراكات أو نقلها. هذه مهمة يجب تنفيذها يدويًا في تطبيقك وفي الخلفية.