رسائل موضوعية على C++

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

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

بعض النقاط التي يجب مراعاتها بشأن المواضيع:

  • تُعدّ رسائل الموضوع أكثر ملاءمة للمحتوى، مثل حالة الطقس أو المعلومات الأخرى المتاحة للجميع.
  • تم تحسين رسائل المواضيع لمعالجة البيانات بدلاً من وقت الاستجابة. لضمان التسليم السريع والآمن لأجهزة فردية أو مجموعات صغيرة من الأجهزة، يمكنك توجيه الرسائل إلى رموز التسجيل المميّزة وليس المواضيع.
  • إذا كنت تريد إرسال الرسائل إلى أجهزة متعدّدة لكل مستخدم، ننصحك باستخدام ميزة المراسلة الجماعية على الأجهزة لحالات الاستخدام هذه.
  • تتيح ميزة "رسائل المواضيع" اشتراكات غير محدودة لكل موضوع. ومع ذلك، تفرض خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" حدودًا في الجوانب التالية:
    • لا يمكن الاشتراك في نسخة واحدة من التطبيق في أكثر من 2000 موضوع.
    • إذا كنت تستخدم الاستيراد المجمّع للاشتراك في نُسخ التطبيق، سيقتصر كل طلب على 1, 000 نسخة من التطبيق.
    • يكون تكرار الاشتراكات الجديدة محدودًا لمعدل لكل مشروع. إذا أرسلت عددًا كبيرًا جدًا من طلبات الاشتراك خلال فترة زمنية قصيرة، ستستجيب خوادم خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" باستجابة 429 RESOURCE_EXHAUSTED ("تم تجاوز الحصة المحدّدة"). أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.

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

للاشتراك في موضوع، يمكنك الاتصال بالرقم ::firebase::messaging::Subscribe من تطبيقك. يؤدي هذا إلى إنشاء طلب غير متزامن إلى الواجهة الخلفية للمراسلة عبر السحابة الإلكترونية من Firebase ويشترك العميل في الموضوع المحدّد.

::firebase::messaging::Subscribe("example");

إذا تعذّر طلب الاشتراك في البداية، ستحاول خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" إعادة المحاولة إلى أن يمكن الاشتراك في الموضوع بنجاح. في كل مرة يبدأ فيها التطبيق، تتأكد خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" من أن جميع المواضيع المطلوبة قد تم الاشتراك فيها.

لإلغاء الاشتراك، يمكنك الاتصال بالرقم ::firebase::messaging::Unsubscribe، وإلغاء الاشتراك في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" عن الموضوع في الخلفية.

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

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

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

يمكنك تمرير قائمة بالرموز المميزة للتسجيل إلى طريقة اشتراك SDK لمشرف Firebase لاشتراك الأجهزة المقابلة في أحد المواضيع:

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().subscribeToTopic(
    registrationTokens, topic);
// 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')

Go

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

تسمح لك واجهة برمجة تطبيقات Admin FCM API أيضًا بإلغاء اشتراك الأجهزة من موضوع من خلال تمرير رموز التسجيل المميّزة إلى الطريقة المناسبة:

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().unsubscribeFromTopic(
    registrationTokens, topic);
// 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')

Go

// 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() كائن يحتوي على الاستجابة من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". يكون لنوع الإرجاع نفس التنسيق بغض النظر عن عدد رموز التسجيل المميزة المحددة في الطلب.

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

تلقّي رسائل المواضيع والتعامل معها

تسلِّم ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" رسائل المواضيع بالطريقة نفسها التي ترسِل بها الرسائل الأخرى في مرحلة متأخرة من الوقت.

من خلال تجاوز الطريقة ::firebase::messaging::Listener::OnMessage، يمكنك تنفيذ الإجراءات استنادًا إلى الرسالة المُستلَمة والحصول على بيانات الرسالة:

void OnMessage(const ::firebase::messaging::Message& message) {
  LogMessage(TAG, "From: %s", message.from.c_str());
  LogMessage(TAG, "Message ID: %s", message.message_id.c_str());
}

إنشاء طلبات الإرسال

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

في منطق الإرسال في الخلفية، حدد اسم الموضوع المطلوب كما هو موضح:

Node.js

// The topic name can be optionally prefixed with "/topics/".
const topic = 'highScores';

const message = {
  data: {
    score: '850',
    time: '2:45'
  },
  topic: topic
};

// Send a message to devices subscribed to the provided topic.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// The topic name can be optionally prefixed with "/topics/".
String topic = "highScores";

// See documentation on defining a message payload.
Message message = Message.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .setTopic(topic)
    .build();

// Send a message to the devices subscribed to the provided topic.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Python

# The topic name can be optionally prefixed with "/topics/".
topic = 'highScores'

# See documentation on defining a message payload.
message = messaging.Message(
    data={
        'score': '850',
        'time': '2:45',
    },
    topic=topic,
)

# Send a message to the devices subscribed to the provided topic.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Go

// The topic name can be optionally prefixed with "/topics/".
topic := "highScores"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Topic: topic,
}

// Send a message to the devices subscribed to the provided topic.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#‎

// The topic name can be optionally prefixed with "/topics/".
var topic = "highScores";

// See documentation on defining a message payload.
var message = new Message()
{
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
    Topic = topic,
};

// Send a message to the devices subscribed to the provided topic.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
  "message":{
    "topic" : "foo-bar",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}

الأمر cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "message": {
    "topic" : "foo-bar",
    "notification": {
      "body": "This is a Firebase Cloud Messaging Topic Message!",
      "title": "FCM Message"
    }
  }
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

لإرسال رسالة إلى مجموعة من المواضيع، حدِّد condition، وهو تعبير منطقي يحدد المواضيع المستهدفة. على سبيل المثال، سيؤدي الشرط التالي إلى إرسال رسائل إلى الأجهزة المشتركة في TopicA والتي تستخدم إما TopicB أو TopicC:

"'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"

وتقيّم FCM أولاً أي شروط بين قوسين، ثم تقيّم التعبير من اليسار إلى اليمين. في التعبير أعلاه، لا يتلقى المستخدم المشترك في أي موضوع فردي الرسالة. وبالمثل، لن يتلقى المستخدم الذي لم يشترك في TopicA الرسالة. وهذه المجموعات تحصل عليه:

  • TopicA وTopicB
  • TopicA وTopicC

يمكنك تضمين ما يصل إلى خمسة مواضيع في التعبير الشرطي.

للإرسال إلى أحد الشروط:

Node.js

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
const condition = '\'stock-GOOG\' in topics || \'industry-tech\' in topics';

// See documentation on defining a message payload.
const message = {
  notification: {
    title: '$FooCorp up 1.43% on the day',
    body: '$FooCorp gained 11.80 points to close at 835.67, up 1.43% on the day.'
  },
  condition: condition
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
getMessaging().send(message)
  .then((response) => {
    // Response is a message ID string.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

Java

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
String condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
Message message = Message.builder()
    .setNotification(Notification.builder()
        .setTitle("$GOOG up 1.43% on the day")
        .setBody("$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.")
        .build())
    .setCondition(condition)
    .build();

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);

Python

# Define a condition which will send to devices which are subscribed
# to either the Google stock or the tech industry topics.
condition = "'stock-GOOG' in topics || 'industry-tech' in topics"

# See documentation on defining a message payload.
message = messaging.Message(
    notification=messaging.Notification(
        title='$GOOG up 1.43% on the day',
        body='$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.',
    ),
    condition=condition,
)

# Send a message to devices subscribed to the combination of topics
# specified by the provided condition.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)

Go

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
condition := "'stock-GOOG' in topics || 'industry-tech' in topics"

// See documentation on defining a message payload.
message := &messaging.Message{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Condition: condition,
}

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)

C#‎

// Define a condition which will send to devices which are subscribed
// to either the Google stock or the tech industry topics.
var condition = "'stock-GOOG' in topics || 'industry-tech' in topics";

// See documentation on defining a message payload.
var message = new Message()
{
    Notification = new Notification()
    {
        Title = "$GOOG up 1.43% on the day",
        Body = "$GOOG gained 11.80 points to close at 835.67, up 1.43% on the day.",
    },
    Condition = condition,
};

// Send a message to devices subscribed to the combination of topics
// specified by the provided condition.
string response = await FirebaseMessaging.DefaultInstance.SendAsync(message);
// Response is a message ID string.
Console.WriteLine("Successfully sent message: " + response);

REST

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
   "message":{
    "condition": "'dogs' in topics || 'cats' in topics",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message",
    }
  }
}

الأمر cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
  "notification": {
    "title": "FCM Message",
    "body": "This is a Firebase Cloud Messaging Topic Message!",
  },
  "condition": "'dogs' in topics || 'cats' in topics"
}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1