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

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

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

للاشتراك في موضوع باستخدام تسجيل FCM، مرِّر معرّف التسجيل (معرّف تثبيت Firebase أو رمز تسجيل FCM المميّز) إلى FCM topic subscription server API كما هو موضّح.

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"
    }

تتيح لك واجهة برمجة التطبيقات V1 الخاصة بالاشتراكات في المواضيع في 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 الإصدار 1 عبارة عن عنصر 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)، يتم إنشاء موضوع جديد بهذا الاسم في "مراسلة Firebase السحابية"، ويمكن لأي عميل بعد ذلك الاشتراك فيه.

يمكنك تمرير قائمة برموز التسجيل إلى طريقة 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.

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

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

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