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

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

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

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

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 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 تنفيذ مهام أساسية لإدارة المواضيع من جهة الخادم. يمكنك الاشتراك في مثيلات تطبيقات العميل وإلغاء الاشتراك فيها بشكلٍ مجمّع باستخدام منطق الخادم، وذلك استنادًا إلى رموز التسجيل المميّزة الخاصة بها.

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

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

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

اختيار المنصّة:

Android

يمكن لتطبيقات العميل الاشتراك في أي موضوع حالي، أو يمكنها إنشاء موضوع جديد. عندما يشترك تطبيق عميل في اسم موضوع جديد (لم يسبق أن كان موجودًا لمشروعك على Firebase)، يتم إنشاء موضوع جديد بهذا الاسم في FCM ويمكن لأي عميل الاشتراك فيه لاحقًا.

للاشتراك في موضوع، يستدعي تطبيق العميل Firebase Cloud Messaging subscribeToTopic() مع اسم الموضوع FCM. تعرض هذه الطريقة `Task`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 أو الرمز المميّز FCM لتطبيق، لا يتم نقل الاشتراكات في المواضيع المرتبطة بمعرّف تثبيت Firebase أو الرمز المميّز القديمَين، ونتيجةً لذلك، لا يحتوي المعرّف الجديد على أي اشتراك في موضوع. لا يتغيّر الرمز المميّز عادةً أثناء تحديثات التطبيق أو عمليات إعادة تحميل الرمز المميّز. السبب الأكثر شيوعًا لتغيير الرمز المميّز هو حذف معرّف تثبيت Firebase أو تدويره، ويمكن مراقبة ذلك من خلال اتّباع الخطوات الواردة في مقالة مراقبة دورة حياة معرّف تثبيت Firebase.

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