إرسال الطلبات من خادم إنشاء التطبيق

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

• اسم الموضوع
• الشرط
• الرمز المميّز لتسجيل الجهاز
• اسم مجموعة الأجهزة (البروتوكول فقط)

يمكنك إرسال رسائل تتضمن حمولة إشعارات تتكون من حقول محددة مسبقًا أو حمولة بيانات من الحقول التي يحددها المستخدم أو رسالة تحتوي على كلا النوعين من الحمولة. راجِع أنواع الرسائل لمعرفة مزيد من المعلومات.

ملاحظة مهمة: يجب أن تحتوي الطلبات لكل من "حزمة SDK لمشرفي Firebase" وبروتوكول HTTP v1 على رقم تعريف مشروع Firebase لتطبيقك والذي يتوفّر في علامة التبويب إعدادات المشروع العامة في "وحدة تحكُّم Firebase". تتطلّب أيضًا طريقتا إرسال الرسائل تفويض طلبات الإرسال.

توضّح الأمثلة في هذه الصفحة كيفية إرسال رسائل الإشعارات باستخدام حزمة تطوير البرامج (SDK) لمشرفي Firebase (التي تتوافق مع Node وJava وPython وC# وGo) والإصدار 1 من بروتوكول HTTP. تتوفّر أيضًا إرشادات حول إرسال الرسائل من خلال بروتوكولات HTTP وXMPP القديمة المتوقّفة نهائيًا.

تنبيه: تم إيقاف ميزة إرسال الرسائل (بما في ذلك الرسائل الرئيسية) من خلال FCM وواجهات برمجة تطبيقات HTTP القديمة لـ FCM في 20 حزيران (يونيو) 2023 وستتم إزالتها في حزيران (يونيو) 2024. إذا كنت تستخدم واجهات برمجة التطبيقات القديمة لإرسال "المراسلة عبر السحابة الإلكترونية من Firebase"، ننصحك بشدة بنقل البيانات إلى واجهة برمجة التطبيقات HTTP v1 أو استخدام SDK للمشرف لإنشاء طلبات الإرسال.

إرسال رسائل إلى أجهزة محدّدة

لإرسالها إلى جهاز واحد محدد، عليك تمرير الرمز المميز لتسجيل الجهاز كما هو موضح. يمكنك الاطّلاع على معلومات إعداد البرنامج على منصتك لمعرفة المزيد حول الرموز المميّزة للتسجيل.

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'YOUR_REGISTRATION_TOKEN';

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

// Send a message to the device corresponding to the provided
// registration token.
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

// This registration token comes from the client FCM SDKs.
String registrationToken = "YOUR_REGISTRATION_TOKEN";

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

// Send a message to the device corresponding to the provided
// registration token.
String response = FirebaseMessaging.getInstance().send(message);
// Response is a message ID string.
System.out.println("Successfully sent message: " + response);
FirebaseMessagingSnippets.java

Python

# This registration token comes from the client FCM SDKs.
registration_token = 'YOUR_REGISTRATION_TOKEN'

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

# Send a message to the device corresponding to the provided
# registration token.
response = messaging.send(message)
# Response is a message ID string.
print('Successfully sent message:', response)
cloud_messaging.py

Go

// Obtain a messaging.Client from the App.
ctx := context.Background()
client, err := app.Messaging(ctx)
if err != nil {
	log.Fatalf("error getting Messaging client: %v\n", err)
}

// This registration token comes from the client FCM SDKs.
registrationToken := "YOUR_REGISTRATION_TOKEN"

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

// Send a message to the device corresponding to the provided
// registration token.
response, err := client.Send(ctx, message)
if err != nil {
	log.Fatalln(err)
}
// Response is a message ID string.
fmt.Println("Successfully sent message:", response)
messaging.go

C#‎

// This registration token comes from the client FCM SDKs.
var registrationToken = "YOUR_REGISTRATION_TOKEN";

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

// Send a message to the device corresponding to the provided
// registration token.
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":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

الأمر cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

عند إتمام الإجراء بنجاح، تعرض كل طريقة إرسال معرّف الرسالة. تعرض "حزمة SDK للمشرف" في Firebase سلسلة رقم التعريف بالتنسيق projects/{project_id}/messages/{message_id}. استجابة بروتوكول HTTP هي مفتاح JSON واحد:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

إرسال رسائل إلى أجهزة متعددة

ملاحظة مهمة: تم إيقاف "طُرق الإرسال" الموضّحة في هذا القسم في 21 حزيران (يونيو) 2023 وستتم إزالتها في حزيران (يونيو) 2024. بالنسبة إلى البروتوكول، استخدِم بدلاً من ذلك طريقة الإرسال العادية عبر HTTP v1 API لتنفيذ الإرسال المجمَّع من خلال تكرار قائمة المستلِمين وإرسالها إلى الرمز المميّز لكل مُستلِم. بالنسبة إلى طرق SDK للمشرف، تأكَّد من التحديث إلى الإصدار الرئيسي التالي. يمكنك الاطّلاع على الأسئلة الشائعة حول Firebase للحصول على مزيد من المعلومات.

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

Node.js

// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

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

getMessaging().sendMulticast(message)
  .then((response) => {
    console.log(response.successCount + ' messages were sent successfully');
  });

Java

// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
FirebaseMessagingSnippets.java

Python

# Create a list containing up to 500 registration tokens.
# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_N',
]

message = messaging.MulticastMessage(
    data={'score': '850', 'time': '2:45'},
    tokens=registration_tokens,
)
response = messaging.send_multicast(message)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
cloud_messaging.py

Go

// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Tokens: registrationTokens,
}

br, err := client.SendMulticast(context.Background(), message)
if err != nil {
	log.Fatalln(err)
}

// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
messaging.go

C#‎

// Create a list containing up to 500 registration tokens.
// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
    Tokens = registrationTokens,
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
FirebaseMessagingSnippets.cs

القيمة المعروضة هي قائمة من الرموز المميزة التي تتوافق مع ترتيب رموز الإدخال المميزة. ويكون هذا مفيدًا عندما تريد التحقق من الرموز المميزة التي أدت إلى حدوث أخطاء.

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'YOUR_REGISTRATION_TOKEN_1',
  // …
  'YOUR_REGISTRATION_TOKEN_N',
];

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

getMessaging().sendMulticast(message)
  .then((response) => {
    if (response.failureCount > 0) {
      const failedTokens = [];
      response.responses.forEach((resp, idx) => {
        if (!resp.success) {
          failedTokens.push(registrationTokens[idx]);
        }
      });
      console.log('List of tokens that caused failures: ' + failedTokens);
    }
  });

Java

// These registration tokens come from the client FCM SDKs.
List<String> registrationTokens = Arrays.asList(
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n"
);

MulticastMessage message = MulticastMessage.builder()
    .putData("score", "850")
    .putData("time", "2:45")
    .addAllTokens(registrationTokens)
    .build();
BatchResponse response = FirebaseMessaging.getInstance().sendMulticast(message);
if (response.getFailureCount() > 0) {
  List<SendResponse> responses = response.getResponses();
  List<String> failedTokens = new ArrayList<>();
  for (int i = 0; i < responses.size(); i++) {
    if (!responses.get(i).isSuccessful()) {
      // The order of responses corresponds to the order of the registration tokens.
      failedTokens.add(registrationTokens.get(i));
    }
  }

  System.out.println("List of tokens that caused failures: " + failedTokens);
}
FirebaseMessagingSnippets.java

Python

# These registration tokens come from the client FCM SDKs.
registration_tokens = [
    'YOUR_REGISTRATION_TOKEN_1',
    # ...
    'YOUR_REGISTRATION_TOKEN_N',
]

message = messaging.MulticastMessage(
    data={'score': '850', 'time': '2:45'},
    tokens=registration_tokens,
)
response = messaging.send_multicast(message)
if response.failure_count > 0:
    responses = response.responses
    failed_tokens = []
    for idx, resp in enumerate(responses):
        if not resp.success:
            # The order of responses corresponds to the order of the registration tokens.
            failed_tokens.append(registration_tokens[idx])
    print('List of tokens that caused failures: {0}'.format(failed_tokens))
cloud_messaging.py

Go

// Create a list containing up to 500 registration tokens.
// This registration tokens come from the client FCM SDKs.
registrationTokens := []string{
	"YOUR_REGISTRATION_TOKEN_1",
	// ...
	"YOUR_REGISTRATION_TOKEN_n",
}
message := &messaging.MulticastMessage{
	Data: map[string]string{
		"score": "850",
		"time":  "2:45",
	},
	Tokens: registrationTokens,
}

br, err := client.SendMulticast(context.Background(), message)
if err != nil {
	log.Fatalln(err)
}

if br.FailureCount > 0 {
	var failedTokens []string
	for idx, resp := range br.Responses {
		if !resp.Success {
			// The order of responses corresponds to the order of the registration tokens.
			failedTokens = append(failedTokens, registrationTokens[idx])
		}
	}

	fmt.Printf("List of tokens that caused failures: %v\n", failedTokens)
}
messaging.go

C#‎

// These registration tokens come from the client FCM SDKs.
var registrationTokens = new List<string>()
{
    "YOUR_REGISTRATION_TOKEN_1",
    // ...
    "YOUR_REGISTRATION_TOKEN_n",
};
var message = new MulticastMessage()
{
    Tokens = registrationTokens,
    Data = new Dictionary<string, string>()
    {
        { "score", "850" },
        { "time", "2:45" },
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachForMulticastAsync(message);
if (response.FailureCount > 0)
{
    var failedTokens = new List<string>();
    for (var i = 0; i < response.Responses.Count; i++)
    {
        if (!response.Responses[i].IsSuccess)
        {
            // The order of responses corresponds to the order of the registration tokens.
            failedTokens.Add(registrationTokens[i]);
        }
    }

    Console.WriteLine($"List of tokens that caused failures: {failedTokens}");
}
FirebaseMessagingSnippets.cs

إرسال رسائل إلى المواضيع

بعد إنشاء موضوع، يمكنك إرسال رسائل إلى الموضوع من خلال اشتراك مثيلات تطبيق العميل في الموضوع من جهة العميل أو عبر واجهة برمجة تطبيقات الخادم. إذا كانت هذه هي المرة الأولى التي تنشئ فيها طلبات لإرسال طلبات إلى "المراسلة عبر السحابة الإلكترونية من 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);
FirebaseMessagingSnippets.java

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)
cloud_messaging.py

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)
messaging.go

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);
FirebaseMessagingSnippets.java

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)
cloud_messaging.py

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)
messaging.go

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

إرسال رسائل إلى مجموعات الأجهزة

لإرسال رسائل إلى مجموعات أجهزة، استخدِم HTTP v1 API. إذا كنت ترسل حاليًا إلى مجموعات أجهزة باستخدام واجهات برمجة تطبيقات الإرسال القديمة المتوقّفة نهائيًا والخاصة ببروتوكول HTTP أو XMPP أو أي إصدار قديم من حزمة تطوير البرامج (SDK) لمشرف Firebase لنظام Node.js استنادًا إلى البروتوكولات القديمة، ننصحك بشدة بنقل البيانات إلى HTTP v1 API في أقرب وقت ممكن. سيتم إيقاف واجهات برمجة تطبيقات الإرسال القديمة وإزالتها في يونيو 2024.

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

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":{
      "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
      "data":{
        "hello": "This is a Firebase Cloud Messaging device group message!"
      }
   }
}

الأمر cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "data":{
     "hello": "This is a Firebase Cloud Messaging device group message!"
   },
   "token":"APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

ملاحظة: على عكس طرق إرسال مجموعة الأجهزة في واجهات برمجة التطبيقات القديمة المتوقّفة، لا تحتوي استجابة HTTP v1 على أعداد النجاح والفشل. يؤدي الإرسال الناجح إلى إرجاع استجابة فارغة.

إرسال مجموعة من الرسائل

ملاحظة مهمة: تم إيقاف "طرق الإرسال المجمَّع" الموضّحة في هذا القسم في 21 حزيران (يونيو) 2023 وستتم إزالتها في حزيران (يونيو) 2024. بالنسبة إلى البروتوكول، استخدِم بدلاً من ذلك طريقة الإرسال العادية عبر HTTP v1 API لتنفيذ الإرسال المجمَّع من خلال تكرار قائمة المستلِمين وإرسالها إلى الرمز المميّز لكل مُستلِم. بالنسبة إلى طرق SDK للمشرف، تأكَّد من التحديث إلى الإصدار الرئيسي التالي. يمكنك الاطّلاع على الأسئلة الشائعة حول Firebase للحصول على مزيد من المعلومات.

تتيح حزم تطوير البرامج (SDK) للمشرف إرسال الرسائل على دفعات. يمكنك تجميع ما يصل إلى 500 رسالة في دفعة واحدة وإرسالها كلّها في طلب بيانات واحد من واجهة برمجة التطبيقات، مع تحسّن كبير في الأداء مقارنةً بإرسال طلبات HTTP منفصلة لكل رسالة.

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

Node.js

// Create a list containing up to 500 messages.
const messages = [];
messages.push({
  notification: { title: 'Price drop', body: '5% off all electronics' },
  token: registrationToken,
});
messages.push({
  notification: { title: 'Price drop', body: '2% off all books' },
  topic: 'readers-club',
});

getMessaging().sendAll(messages)
  .then((response) => {
    console.log(response.successCount + ' messages were sent successfully');
  });

Java

// Create a list containing up to 500 messages.
List<Message> messages = Arrays.asList(
    Message.builder()
        .setNotification(Notification.builder()
            .setTitle("Price drop")
            .setBody("5% off all electronics")
            .build())
        .setToken(registrationToken)
        .build(),
    // ...
    Message.builder()
        .setNotification(Notification.builder()
            .setTitle("Price drop")
            .setBody("2% off all books")
            .build())
        .setTopic("readers-club")
        .build()
);

BatchResponse response = FirebaseMessaging.getInstance().sendAll(messages);
// See the BatchResponse reference documentation
// for the contents of response.
System.out.println(response.getSuccessCount() + " messages were sent successfully");
FirebaseMessagingSnippets.java

Python

# Create a list containing up to 500 messages.
messages = [
    messaging.Message(
        notification=messaging.Notification('Price drop', '5% off all electronics'),
        token=registration_token,
    ),
    # ...
    messaging.Message(
        notification=messaging.Notification('Price drop', '2% off all books'),
        topic='readers-club',
    ),
]

response = messaging.send_all(messages)
# See the BatchResponse reference documentation
# for the contents of response.
print('{0} messages were sent successfully'.format(response.success_count))
cloud_messaging.py

Go

// Create a list containing up to 500 messages.
messages := []*messaging.Message{
	{
		Notification: &messaging.Notification{
			Title: "Price drop",
			Body:  "5% off all electronics",
		},
		Token: registrationToken,
	},
	{
		Notification: &messaging.Notification{
			Title: "Price drop",
			Body:  "2% off all books",
		},
		Topic: "readers-club",
	},
}

br, err := client.SendAll(context.Background(), messages)
if err != nil {
	log.Fatalln(err)
}

// See the BatchResponse reference documentation
// for the contents of response.
fmt.Printf("%d messages were sent successfully\n", br.SuccessCount)
messaging.go

C#‎

// Create a list containing up to 500 messages.
var messages = new List<Message>()
{
    new Message()
    {
        Notification = new Notification()
        {
            Title = "Price drop",
            Body = "5% off all electronics",
        },
        Token = registrationToken,
    },
    new Message()
    {
        Notification = new Notification()
        {
            Title = "Price drop",
            Body = "2% off all books",
        },
        Topic = "readers-club",
    },
};

var response = await FirebaseMessaging.DefaultInstance.SendEachAsync(messages);
// See the BatchResponse reference documentation
// for the contents of response.
Console.WriteLine($"{response.SuccessCount} messages were sent successfully");
FirebaseMessagingSnippets.cs

إرسال رسائل مباشرة يتم تفعيل التمهيد (Android فقط)

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

تنبيه: من المهم مراعاة مستوى رؤية الرسائل التي تم تفعيل ميزة "التشغيل المباشر" فيها، لأنّ أي مستخدم لديه إذن الوصول إلى الجهاز يمكنه الاطّلاع على هذه الرسائل بدون إدخال بيانات اعتماد المستخدم.

الإرسال باستخدام واجهة برمجة تطبيقات HTTP للإصدار 1 من FCM

يجب أن يتضمّن طلب الرسالة المفتاح "direct_boot_ok" : true في خيارات AndroidConfig لنص الطلب. على سبيل المثال:

https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
  "message":{
    "token" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
    "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "android": {
      "direct_boot_ok": true,
    },
}

الإرسال باستخدام واجهة برمجة تطبيقات HTTP القديمة لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

تنبيه: تم إيقاف ميزة إرسال الرسائل (بما في ذلك الرسائل الرئيسية) من خلال FCM وواجهات برمجة تطبيقات HTTP القديمة لـ FCM في 20 حزيران (يونيو) 2023 وستتم إزالتها في حزيران (يونيو) 2024. إذا كنت تستخدم واجهات برمجة التطبيقات القديمة لإرسال "المراسلة عبر السحابة الإلكترونية من Firebase"، ننصحك بشدة بنقل البيانات إلى واجهة برمجة التطبيقات HTTP v1 أو استخدام SDK للمشرف لإنشاء طلبات الإرسال.

يجب أن يتضمّن طلب الرسالة المفتاح "direct_boot_ok" : true في المستوى الأعلى من نص الطلب. على سبيل المثال:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  "direct_boot_ok" : true
}

يمكن معالجة الرسائل المُرسَلة باستخدام هذا المفتاح في نص الطلب من خلال التطبيقات على الأجهزة التي تكون في وضع التشغيل المباشر حاليًا (وكذلك في حال عدم استخدام ذلك الوضع).

تخصيص الرسائل على جميع الأنظمة الأساسية

إنّ "SDK للمشرف" في Firebase وبروتوكول FCM v1 HTTP يتيحان لطلبات الرسائل ضبط جميع الحقول المتاحة في العنصر message. يشمل هذا النوع من المحتوى ما يلي:

• مجموعة شائعة من الحقول ليتم تفسيرها بواسطة جميع مثيلات التطبيقات التي تتلقى الرسالة.
• مجموعات الحقول الخاصة بالنظام الأساسي، مثل AndroidConfig وWebpushConfig، لا يتم تفسيرها إلا من خلال مثيلات التطبيق التي تعمل على النظام الأساسي المحدد.

تمنحك عمليات الحظر الخاصة بالنظام الأساسي المرونة لتخصيص الرسائل للأنظمة الأساسية المختلفة لضمان التعامل معها بشكل صحيح عند استلامها. ستراعي خلفية "المراسلة عبر السحابة الإلكترونية من Firebase" جميع المعلمات المحدّدة وتخصِّص الرسالة لكل نظام أساسي.

متى تستخدم الحقول المشتركة

استخدِم الحقول الشائعة عند:

• استهداف مثيلات التطبيقات على جميع الأنظمة الأساسية: Apple وAndroid والويب
• إرسال رسائل إلى المواضيع

يمكن لجميع مثيلات التطبيقات، بغض النظر عن النظام الأساسي، تفسير الحقول الشائعة التالية:

• message.notification.title
• message.notification.body
• message.data

حالات استخدام الحقول الخاصة بالنظام الأساسي

استخدِم الحقول الخاصة بالنظام الأساسي عندما تريد:

• إرسال الحقول إلى أنظمة أساسية معيّنة فقط
• إرسال الحقول الخاصة بالنظام الأساسي بالإضافة إلى الحقول المشتركة

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

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

مثال: رسالة إشعار تتضمن خيارات اللون والرمز

يرسل مثال الإرسال هذا عنوان إشعار ومحتواه مشتركان إلى جميع الأنظمة الأساسية، كما يرسل أيضًا بعض عمليات الإلغاء الخاصة بالنظام الأساسي إلى أجهزة Android.

بالنسبة إلى أجهزة Android، يضبط الطلب رمزًا خاصًا ولونًا لعرضهما على أجهزة Android. وكما هو مذكور في مرجع AndroidNotification، يتم تحديد اللون بتنسيق #rrggbb، ويجب أن تكون الصورة موردًا للرمز قابلاً للرسم محليًا لتطبيق Android.

في ما يلي تقريب للتأثير المرئي على جهاز المستخدم:

Node.js

const topicName = 'industry-tech';

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.'
  },
  android: {
    notification: {
      icon: 'stock_ticker_update',
      color: '#7e55c3'
    }
  },
  topic: topicName,
};

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

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())
    .setAndroidConfig(AndroidConfig.builder()
        .setTtl(3600 * 1000)
        .setNotification(AndroidNotification.builder()
            .setIcon("stock_ticker_update")
            .setColor("#f45342")
            .build())
        .build())
    .setApnsConfig(ApnsConfig.builder()
        .setAps(Aps.builder()
            .setBadge(42)
            .build())
        .build())
    .setTopic("industry-tech")
    .build();
FirebaseMessagingSnippets.java

Python

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.',
    ),
    android=messaging.AndroidConfig(
        ttl=datetime.timedelta(seconds=3600),
        priority='normal',
        notification=messaging.AndroidNotification(
            icon='stock_ticker_update',
            color='#f45342'
        ),
    ),
    apns=messaging.APNSConfig(
        payload=messaging.APNSPayload(
            aps=messaging.Aps(badge=42),
        ),
    ),
    topic='industry-tech',
)
cloud_messaging.py

Go

oneHour := time.Duration(1) * time.Hour
badge := 42
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.",
	},
	Android: &messaging.AndroidConfig{
		TTL: &oneHour,
		Notification: &messaging.AndroidNotification{
			Icon:  "stock_ticker_update",
			Color: "#f45342",
		},
	},
	APNS: &messaging.APNSConfig{
		Payload: &messaging.APNSPayload{
			Aps: &messaging.Aps{
				Badge: &badge,
			},
		},
	},
	Topic: "industry-tech",
}
messaging.go

C#‎

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.",
    },
    Android = new AndroidConfig()
    {
        TimeToLive = TimeSpan.FromHours(1),
        Notification = new AndroidNotification()
        {
            Icon = "stock_ticker_update",
            Color = "#f45342",
        },
    },
    Apns = new ApnsConfig()
    {
        Aps = new Aps()
        {
            Badge = 42,
        },
    },
    Topic = "industry-tech",
};
FirebaseMessagingSnippets.cs

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":"industry-tech",
     "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."
     },
     "android":{
       "notification":{
         "icon":"stock_ticker_update",
         "color":"#7e55c3"
       }
     }
   }
 }

يمكنك الاطّلاع على المستندات المرجعية للإصدار HTTP v1 للحصول على تفاصيل كاملة حول المفاتيح المتوفرة في الوحدات الخاصة بالنظام الأساسي في نص الرسالة.

مثال: رسالة إشعار بها صورة مخصّصة

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

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Sparky says hello!'
  },
  android: {
    notification: {
      imageUrl: 'https://foo.bar.pizza-monster.png'
    }
  },
  apns: {
    payload: {
      aps: {
        'mutable-content': 1
      }
    },
    fcm_options: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  webpush: {
    headers: {
      image: 'https://foo.bar.pizza-monster.png'
    }
  },
  topic: topicName,
};

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);
  });

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":"industry-tech",
     "notification":{
       "title":"Sparky says hello!",
     },
     "android":{
       "notification":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "mutable-content":1
         }
       },
       "fcm_options": {
           "image":"https://foo.bar/pizza-monster.png"
       }
     },
     "webpush":{
       "headers":{
         "image":"https://foo.bar/pizza-monster.png"
       }
     }
   }
 }

يمكنك الاطّلاع على المستندات المرجعية للإصدار HTTP v1 للحصول على تفاصيل كاملة حول المفاتيح المتوفرة في الوحدات الخاصة بالنظام الأساسي في نص الرسالة.

مثال: رسالة إشعار مع إجراء نقر مرتبط

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

Node.js

const topicName = 'industry-tech';

const message = {
  notification: {
    title: 'Breaking News....'
  },
  android: {
    notification: {
      clickAction: 'news_intent'
    }
  },
  apns: {
    payload: {
      aps: {
        'category': 'INVITE_CATEGORY'
      }
    }
  },
  webpush: {
    fcmOptions: {
      link: 'breakingnews.html'
    }
  },
  topic: topicName,
};

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);
  });

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":"industry-tech",
     "notification":{
       "title":"Breaking News...",
     },
     "android":{
       "notification":{
         "click_action":"news_intent"
       }
     },
     "apns":{
       "payload":{
         "aps":{
           "category" : "INVITE_CATEGORY"
         }
       },
     },
     "webpush":{
       "fcm_options":{
         "link":"breakingnews.html"
       }
     }
   }
 }

يمكنك الاطّلاع على المستندات المرجعية للإصدار HTTP v1 للحصول على تفاصيل كاملة حول المفاتيح المتوفرة في الوحدات الخاصة بالنظام الأساسي في نص الرسالة.

مثال: رسالة إشعار بخيارات الترجمة

يرسل المثال التالي طلب الإرسال خيارات الترجمة للعميل لعرض الرسائل المترجمة. في ما يلي تقريب للتأثير المرئي على جهاز المستخدم:

Node.js

var topicName = 'industry-tech';

var message = {
  android: {
    ttl: 3600000,
    notification: {
      bodyLocKey: 'STOCK_NOTIFICATION_BODY',
      bodyLocArgs: ['FooCorp', '11.80', '835.67', '1.43']
    }
  },
  apns: {
    payload: {
      aps: {
        alert: {
          locKey: 'STOCK_NOTIFICATION_BODY',
          locArgs: ['FooCorp', '11.80', '835.67', '1.43']
        }
      }
    }
  },
  topic: topicName,
};

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);
  });

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":"Tech",
             "android":{
               "ttl":"3600s",
               "notification":{
                 "body_loc_key": "STOCK_NOTIFICATION_BODY",
                 "body_loc_args":  ["FooCorp", "11.80", "835.67", "1.43"],
               },
             },
             "apns":{
               "payload":{
                 "aps":{
                   "alert" : {
                     "loc-key": "STOCK_NOTIFICATION_BODY",
                     "loc-args":  ["FooCorp", "11.80", "835.67", "1.43"],
                    },
                 },
               },
             },
  },
}'

يمكنك الاطّلاع على المستندات المرجعية للإصدار HTTP v1 للحصول على تفاصيل كاملة حول المفاتيح المتوفرة في الوحدات الخاصة بالنظام الأساسي في نص الرسالة.

رموز خطأ REST الخاصة بواجهة برمجة التطبيقات HTTP v1

تحتوي استجابات خطأ HTTP لواجهة برمجة التطبيقات HTTP v1 على رمز خطأ ورسالة خطأ وحالة خطأ. وقد تحتوي أيضًا على مصفوفة details مع مزيد من التفاصيل حول الخطأ.

في ما يلي نموذجان للرد على الخطأ:

المثال 1: استجابة خطأ من طلب HTTP v1 API تحتوي على قيمة غير صالحة في رسالة بيانات

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "message.data[0].value",
            "description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
          }
        ]
      }
    ]
  }
}

المثال 2: استجابة خطأ من طلب HTTP v1 API باستخدام رمز مميَّز غير صالح للتسجيل

{
  "error": {
    "code": 400,
    "message": "The registration token is not a valid FCM registration token",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "INVALID_ARGUMENT"
      }
    ]
   }
}

يُرجى العِلم أنّ كلتا الرسالتَين لهما الرمز نفسه والحالة نفسيهما، ولكن مصفوفة التفاصيل تحتوي على قيم في أنواع مختلفة. يحتوي المثال الأول على النوع type.googleapis.com/google.rpc.BadRequest الذي يشير إلى وجود خطأ في قيم الطلب. المثال الثاني من النوع type.googleapis.com/google.firebase.fcm.v1.FcmError به خطأ خاص بالمراسلة عبر السحابة الإلكترونية من Firebase. بالنسبة إلى العديد من الأخطاء، تحتوي مصفوفة التفاصيل على المعلومات التي ستحتاجها لتصحيح الأخطاء والعثور على حلّ.

يسرد الجدول التالي رموز الخطأ في واجهة برمجة التطبيقات FCM v1 REST وأوصافها.

رمز الخطأ	خطوات الوصف والحلّ
UNSPECIFIED_ERROR لا تتوفر معلومات أخرى عن هذا الخطأ.	بلا.
INVALID_ARGUMENT (رمز خطأ HTTP = 400) كانت مَعلمات الطلب غير صالحة. يتم إرجاع إضافة من النوع google.rpc.BadRequest لتحديد الحقل غير الصالح.	تتضمن الأسباب المحتملة تسجيل غير صالح، أو اسم حزمة غير صالح، أو حجم الرسالة كبير جدًا، أو مفتاح بيانات غير صالح، أو مدة بقاء غير صالحة، أو معلمات أخرى غير صالحة. تسجيل غير صالح: تحقَّق من تنسيق الرمز المميّز للتسجيل الذي ترسله إلى الخادم. تأكَّد من تطابق الرمز مع الرمز المميّز للتسجيل الذي يتلقّاه تطبيق العميل من التسجيل لدى خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". لا تقتطع الرمز المميّز أو تدرج أحرفًا إضافية. اسم الحزمة غير صالح: تأكَّد من أنّ الرسالة موجَّهة إلى رمز مميَّز للتسجيل يتطابق اسم حزمته مع القيمة التي تم تمريرها في الطلب. حجم الرسالة كبير جدًا: تأكَّد من أنّ الحجم الإجمالي لبيانات الحمولة المضمَّنة في الرسالة لا يتجاوز حدود "المراسلة عبر السحابة الإلكترونية من Firebase": 4096 بايت لمعظم الرسائل، أو 2048 بايت في حالة الرسائل المُرسَلة إلى مواضيع. وهذا يشمل كلاً من المفاتيح والقيم. مفتاح بيانات غير صالح: تأكَّد من أنّ بيانات الحمولة لا تحتوي على مفتاح (مثل from أو gcm أو أي قيمة مسبوقة بـ google) يستخدمها داخليًا في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". يُرجى العلم أنّ بعض الكلمات (مثل تصغير_key) تستخدمها أيضًا خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، ولكن يُسمح باستخدامها في الحمولة، وفي هذه الحالة سيتم تجاهل قيمة الحمولة من خلال قيمة "المراسلة عبر السحابة الإلكترونية من Firebase". مدة البقاء غير صالحة: تأكَّد من أنّ القيمة المستخدَمة في ttl هي عدد صحيح يمثّل مدّة تتراوح بالثواني بين 0 و2,419,200 (4 أسابيع). المَعلمات غير الصالحة: تأكَّد من أنّ المَعلمات المقدّمة لها الاسم والنوع الصحيحَين.
UNREGISTERED (رمز خطأ HTTP = 404) تم إلغاء تسجيل مثيل التطبيق من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". يعني ذلك عادةً أنّ الرمز المميّز المستخدَم لم يعد صالحًا ويجب استخدام رمز جديد.	قد يرجع السبب في هذا الخطأ إلى فقدان رموز التسجيل المميَّزة أو الرموز المميّزة غير المسجَّلة. التسجيل غير متوفّر: إذا كان هدف الرسالة هو قيمة token، تأكَّد من أنّ الطلب يحتوي على رمز مميَّز للتسجيل. غير مسجَّل: قد لا يعود الرمز المميّز الحالي للتسجيل صالحًا في عدد من الحالات، بما في ذلك: - إذا ألغى تطبيق العميل التسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". - إذا تم إلغاء تسجيل تطبيق العميل تلقائيًا، قد يحدث ذلك إذا ألغى المستخدم تثبيت التطبيق. على سبيل المثال، في نظام التشغيل iOS، إذا أبلغت "خدمة ملاحظات أسماء نقاط الوصول" (APNs) عن أنّ الرمز المميّز لأسماء نقاط الوصول غير صالح. - في حال انتهاء صلاحية الرمز المميّز للتسجيل (على سبيل المثال، قد تقرِّر Google إعادة تحميل الرموز المميّزة للتسجيل أو قد انتهت صلاحية الرموز المميّزة لأسماء نقاط الوصول (APN) لأجهزة iOS). - إذا تم تحديث تطبيق العميل ولكن لم يتم إعداد الإصدار الجديد لتلقّي الرسائل. في جميع هذه الحالات، عليك إزالة الرمز المميّز للتسجيل من خادم التطبيق والتوقّف عن استخدامه لإرسال الرسائل.
SENDER_ID_MISMATCH (رمز خطأ HTTP = 403) يختلف معرّف المُرسِل الذي تمت مصادقته عن معرّف المُرسِل للرمز المميز للتسجيل.	ويرتبط الرمز المميّز للتسجيل بمجموعة معيّنة من المُرسِلين. عندما يسجِّل تطبيق عميل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، يجب تحديد المرسِلين المسموح لهم بإرسال الرسائل. يجب استخدام أحد معرّفات المُرسِلين هذه عند إرسال الرسائل إلى تطبيق العميل. في حال التبديل إلى مُرسِل مختلف، لن تعمل الرموز المميّزة الحالية للتسجيل.
QUOTA_EXCEEDED (رمز خطأ HTTP = 429) تم تجاوز حد الإرسال لهدف الرسالة. يتم عرض إضافة من النوع google.rpc.QuotaFailure لتحديد الحصة التي تم تجاوزها.	قد يرجع السبب في هذا الخطأ إلى تجاوز حصة معدل الرسائل أو تجاوز الحصة لمعدل الرسائل على الجهاز أو تجاوز حصة معدّل الرسائل المتعلقة بالمواضيع. تم تجاوز معدل الرسائل: معدل إرسال الرسائل مرتفع جدًا. يجب عليك تخفيض المعدل الكلي لإرسال الرسائل. ويمكنك استخدام خوارزمية الرقود الأسي مع مهلة أولية تبلغ دقيقة واحدة على الأقل لإعادة محاولة الرسائل المرفوضة. تم تجاوز معدّل الرسائل على الجهاز: معدّل الرسائل إلى جهاز معيَّن مرتفع جدًا. راجِع الحد الأقصى لمعدّل الرسائل في جهاز واحد. يمكنك تقليل عدد الرسائل المُرسَلة إلى هذا الجهاز واستخدام ميزة "الرقود الأسي" لإعادة محاولة الإرسال. تم تجاوز معدّل الرسائل المرتبطة بموضوع معيّن: معدّل الرسائل الموجَّهة إلى المشتركين حول موضوع معيّن مرتفع جدًا. يمكنك تقليل عدد الرسائل المُرسَلة حول هذا الموضوع واستخدام ميزة "الرقود الأسي" مع مهلة أولية تبلغ دقيقة واحدة على الأقل لإعادة محاولة الإرسال.
UNAVAILABLE (رمز خطأ HTTP = 503) تم تحميل الخادم بشكل زائد.	لم يتمكّن الخادم من معالجة الطلب في الوقت المناسب. أعِد محاولة إرسال الطلب نفسه، ولكن عليك إجراء ما يلي: - يجب الالتزام بالعنوان "إعادة المحاولة بعد" في حال تضمينه في الاستجابة من خادم اتصال "المراسلة عبر السحابة الإلكترونية من Firebase". - تنفيذ خوارزمية الرقود الأسي في آلية إعادة المحاولة (على سبيل المثال، إذا انتظرت ثانية واحدة قبل إعادة المحاولة الأولى، انتظر لمدة ثانيتين على الأقل قبل المحاولة التالية، ثم 4 ثوانٍ وما إلى ذلك). إذا كنت ترسل رسائل متعددة، فكّر في تطبيق المخاوف. لمزيد من المعلومات، يُرجى الاطّلاع على التعامل مع محاولات إعادة المحاولة. ويخاطر المُرسِلون الذين يتسبّبون بمشاكل أن يتم إدراجهم في قائمة الحظر.
INTERNAL (رمز خطأ HTTP = 500) حدث خطأ داخلي غير معروف.	حدث خطأ في الخادم أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة تقديم الطلب نفسه بعد تنفيذ الاقتراحات في قسم معالجة محاولات إعادة المحاولة. في حال استمرار ظهور الخطأ، يُرجى التواصل مع فريق دعم Firebase.
THIRD_PARTY_AUTH_ERROR (رمز خطأ HTTP = 401) شهادة أسماء نقاط الوصول (APN) أو مفتاح المصادقة على الويب غير صالح أو غير متوفّر.	تعذر إرسال رسالة تستهدف جهاز iOS أو تسجيل فوري على الويب. تحقق من صلاحية بيانات اعتماد التطوير والإنتاج.

رموز خطأ المشرف

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

رمز الخطأ	خطوات الوصف والحلّ
messaging/invalid-argument	تم تقديم وسيطة غير صالحة إلى طريقة FCM. ومن المفترض أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-recipient	مستلم الرسالة المقصود غير صالح. ومن المفترض أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-payload	تم تقديم عنصر غير صالح لحمولة الرسالة. ومن المفترض أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-data-payload-key	تحتوي حمولة رسالة البيانات على مفتاح غير صالح. يمكنك الاطّلاع على المستندات المرجعية لـ DataMessagePayload لمعرفة المفاتيح المفروض عليها قيود.
messaging/payload-size-limit-exceeded	تتجاوز حمولة الرسائل المقدّمة حدود حجم خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". الحد الأقصى المسموح به لمعظم الرسائل هو 4096 بايت. وبالنسبة إلى الرسائل المُرسَلة إلى المواضيع، يبلغ الحدّ الأقصى المسموح به 2048 بايت. ويشمل إجمالي حجم الحمولة كلاً من المفاتيح والقيم.
messaging/invalid-options	تم تقديم عنصر غير صالح لخيارات الرسالة. ومن المفترض أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-registration-token	تم تقديم رمز تسجيل غير صالح. يُرجى التأكّد من تطابقه مع الرمز المميّز للتسجيل الذي يتلقّاه تطبيق العميل من التسجيل لدى خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". ولا تقتطع أحرفًا أو تضِف أحرفًا أخرى إلى النص.
messaging/registration-token-not-registered	الرمز المميّز للتسجيل الذي تم تقديمه غير مسجَّل. يمكن إلغاء تسجيل رمز مميّز صالح للتسجيل سابقًا لعدة أسباب، منها: ألغى تطبيق العميل تسجيل نفسه من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". تم إلغاء تسجيل تطبيق العميل تلقائيًا. ويمكن أن يحدث ذلك إذا ألغى المستخدم تثبيت التطبيق أو على منصات Apple إذا كانت "خدمة ملاحظات APN" قد أبلغت عن الرمز المميّز لأسماء نقاط الوصول على أنّه غير صالح. انتهت صلاحية الرمز المميّز للتسجيل. على سبيل المثال، قد تقرِّر Google إعادة تحميل الرموز المميّزة للتسجيل أو قد تكون صلاحية الرموز المميّزة لأسماء نقاط الوصول (APN) قد انتهت صلاحيتها لأجهزة Apple. تم تحديث تطبيق العميل، ولكن لم يتم ضبط الإصدار الجديد على تلقّي الرسائل. في جميع هذه الحالات، عليك إزالة الرمز المميّز للتسجيل والتوقّف عن استخدامه لإرسال الرسائل.
messaging/invalid-package-name	تم توجيه الرسالة إلى رمز مميَّز للتسجيل لا يتطابق اسم حزمته مع خيار restrictedPackageName المقدَّم.
messaging/message-rate-exceeded	معدل الرسائل الموجهة إلى هدف معين مرتفع جدًا. قلِّل عدد الرسائل المُرسَلة إلى هذا الجهاز أو الموضوع ولا تعيد محاولة الإرسال على الفور إلى هذا الهدف.
messaging/device-message-rate-exceeded	معدّل الرسائل إلى جهاز معيّن مرتفع جدًا. قلِّل عدد الرسائل المُرسَلة إلى هذا الجهاز ولا تعيد محاولة الإرسال إليه على الفور.
messaging/topics-message-rate-exceeded	معدل الرسائل الموجهة إلى المشتركين في موضوع معين مرتفع جدًا. قلل عدد الرسائل المرسلة لهذا الموضوع، ولا تحاول الإرسال إليه على الفور.
messaging/too-many-topics	تم الاشتراك في رمز مميّز للتسجيل وفقًا لأقصى عدد ممكن من المواضيع ولا يمكن الاشتراك فيه بعد الآن.
messaging/invalid-apns-credentials	تعذَّر إرسال رسالة موجَّهة إلى جهاز Apple بسبب عدم تحميل شهادة طبقة المقابس الآمنة (SSL) المطلوبة لأسماء نقاط الوصول (APN) أو انتهت صلاحيتها. تحقَّق من صلاحية شهادات التطوير والإنتاج الخاصة بك.
messaging/mismatched-credential	لا تتضمّن بيانات الاعتماد المستخدَمة لمصادقة حزمة تطوير البرامج (SDK) هذه إذنًا لإرسال الرسائل إلى الجهاز المتوافق مع الرمز المميّز للتسجيل. تأكَّد من أنّ بيانات الاعتماد والرمز المميّز للتسجيل ينتميان إلى مشروع Firebase نفسه. اطّلِع على مقالة إضافة Firebase إلى تطبيقك للحصول على مستندات حول كيفية مصادقة حِزم SDK لمشرفي Firebase.
messaging/authentication-error	تعذّر على حزمة تطوير البرامج (SDK) مصادقة خوادم "المراسلة عبر السحابة الإلكترونية من Firebase". واحرص على مصادقة "حزمة تطوير البرامج (SDK) لمشرفي Firebase" باستخدام بيانات اعتماد تتضمّن الأذونات المناسبة لإرسال رسائل "المراسلة عبر السحابة الإلكترونية من Firebase". اطّلِع على مقالة إضافة Firebase إلى تطبيقك للحصول على مستندات حول كيفية مصادقة حِزم SDK لمشرفي Firebase.
messaging/server-unavailable	لم يتمكن خادم "المراسلة عبر السحابة الإلكترونية من Firebase" من معالجة الطلب في الوقت المناسب. عليك إعادة محاولة إرسال الطلب نفسه، مع العِلم بأنّه: عليك تنفيذ عنوان Retry-After إذا تم تضمينه في الاستجابة من خادم اتصال "المراسلة عبر السحابة الإلكترونية من Firebase". تنفيذ الرقود الأسي في آلية إعادة المحاولة. على سبيل المثال، إذا انتظرت ثانية واحدة قبل إعادة المحاولة الأولى، انتظِر قبل الثانية التالية على الأقل، ثم أربع ثوانٍ، وما إلى ذلك. في حال إرسال عدة رسائل، عليك تأخير كل رسالة على حدة بمبلغ عشوائي إضافي لتجنُّب إصدار طلب جديد لجميع الرسائل في الوقت نفسه. قد يُدرج المُرسِلون الذين يسببون مشاكل في قائمة سوداء.
messaging/internal-error	حدث خطأ في خادم "المراسلة عبر السحابة الإلكترونية من Firebase" أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة تقديم الطلب نفسه باتّباع المتطلبات المدرَجة في الصف messaging/server-unavailable أعلاه. إذا استمر ظهور الخطأ، يُرجى إبلاغ قناة الدعم تقرير الأخطاء عن المشكلة.
messaging/unknown-error	حدث خطأ غير معروف في الخادم. للاطّلاع على مزيد من التفاصيل، يُرجى الاطّلاع على استجابة الخادم الأولية في رسالة الخطأ. إذا ظهر لك هذا الخطأ، يُرجى الإبلاغ عن رسالة الخطأ الكاملة على قناة الدعم الخاصة بتقرير الأخطاء.

إرسال الرسائل باستخدام بروتوكولات خادم التطبيقات القديمة

تنبيه: تم إيقاف ميزة إرسال الرسائل (بما في ذلك الرسائل الرئيسية) من خلال FCM وواجهات برمجة تطبيقات HTTP القديمة لـ FCM في 20 حزيران (يونيو) 2023 وستتم إزالتها في حزيران (يونيو) 2024. إذا كنت تستخدم واجهات برمجة التطبيقات القديمة لإرسال "المراسلة عبر السحابة الإلكترونية من Firebase"، ننصحك بشدة بنقل البيانات إلى واجهة برمجة التطبيقات HTTP v1 أو استخدام SDK للمشرف لإنشاء طلبات الإرسال.

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

إرسال رسائل إلى أجهزة محدّدة

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

طلب HTTP POST

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{ "data": {
    "score": "5x1",
    "time": "15:10"
  },
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}

استجابة HTTP

{ "multicast_id": 108,
  "success": 1,
  "failure": 0,
  "results": [
    { "message_id": "1:08" }
  ]
}

رسالة XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
    { "data": {
      "score": "5x1",
      "time": "15:10"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
  </gcm>
</message>

ردّ XMPP

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

يوفر خادم اتصال XMPP بعض الخيارات الأخرى للردود. يمكنك الاطّلاع على تنسيق استجابة الخادم.

للاطّلاع على القائمة الكاملة لخيارات الرسائل المتاحة عند إرسال رسائل استلام إلى تطبيقات العميل، يمكنك مراجعة المعلومات المرجعية للبروتوكول الذي اخترته لخادم الاتصال، HTTP أو XMPP.

إرسال رسائل إلى المواضيع

إنّ إرسال الرسائل إلى موضوع "المراسلة عبر السحابة الإلكترونية من Firebase" يشبه إلى حد كبير إرسال الرسائل إلى جهاز فردي أو إلى مجموعة مستخدمين. يضبط خادم التطبيق مفتاح to بقيمة مثل /topics/yourTopic. ويمكن للمطوّرين اختيار أي اسم موضوع يتطابق مع التعبير العادي: "/topics/[a-zA-Z0-9-_.~%]+".

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

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

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

• الموضوع (أ) والموضوع (ب)
• الموضوع (أ) والموضوع (ج)

يمكنك تضمين ما يصل إلى خمسة موضوعات في التعبير الشرطي، ويتم دعم الأقواس. عوامل التشغيل المتوافقة: && و||

طلب HTTP POST للموضوع

الإرسال إلى موضوع واحد:

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

الإرسال إلى الأجهزة المشتركة في موضوعَي "الكلاب" أو "القطط":

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

استجابة HTTP للموضوع

// Success example:
{
  "message_id": "1023456"
}

// failure example:
{
  "error": "TopicsMessageRateExceeded"
}

رسالة XMPP حول الموضوع

الإرسال إلى موضوع واحد:

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

الإرسال إلى الأجهزة المشتركة في موضوعَي "الكلاب" أو "القطط":

<message id="">
  <gcm xmlns="google:mobile:data">


  </gcm>
</message>

رد XMPP على الموضوع

// Success example:
{
  "message_id": "1023456"
}

// failure example:
{
  "error": "TopicsMessageRateExceeded"
}

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

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

إرسال رسائل إلى مجموعات الأجهزة

تنبيه: تم إيقاف ميزة إرسال الرسائل (بما في ذلك الرسائل الرئيسية) من خلال FCM وواجهات برمجة تطبيقات HTTP القديمة لـ FCM في 20 حزيران (يونيو) 2023 وستتم إزالتها في حزيران (يونيو) 2024. إذا كنت تستخدم واجهات برمجة التطبيقات القديمة لإرسال "المراسلة عبر السحابة الإلكترونية من Firebase"، ننصحك بشدة بنقل البيانات إلى واجهة برمجة التطبيقات HTTP v1 أو استخدام SDK للمشرف لإنشاء طلبات الإرسال.

إنّ إرسال الرسائل إلى مجموعة أجهزة باستخدام واجهات برمجة التطبيقات القديمة التي تم إيقافها نهائيًا يشبه إلى حد كبير إرسال رسائل إلى جهاز فردي. اضبط المَعلمة to على مفتاح الإشعارات الفريد لمجموعة الأجهزة. توضّح الأمثلة الواردة في هذا القسم كيفية إرسال رسائل البيانات إلى مجموعات الأجهزة في بروتوكول HTTP وXMPP القديم.

طلب HTTP POST لمجموعة الأجهزة

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

استجابة HTTP لمجموعة الأجهزة

في ما يلي مثال على الحالة "تم بنجاح": يتضمّن notification_key رمزَين مميَّزَين للتسجيل مرتبطَين به، وقد تم إرسال الرسالة بنجاح إلى كليهما:

{
  "success": 2,
  "failure": 0
}

في ما يلي مثال على "النجاح الجزئي": يتضمّن notification_key 3 رموز تسجيل مميّزة مرتبطة به. تم إرسال الرسالة بنجاح إلى واحد من الرموز المميّزة للتسجيل فقط. تسرد رسالة الرد الرموز المميزة للتسجيل (registration_ids) التي تعذّر عليها تلقّي الرسالة:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

عند تعذُّر تسليم رسالة إلى رمز مميّز واحد أو أكثر من الرموز المميّزة للتسجيل المرتبطة بـ notification_key، على خادم التطبيق إعادة المحاولة مع التراجع عن المحاولة.

إذا حاول الخادم إرسال رسالة إلى مجموعة أجهزة لا تتضمّن أي أعضاء، سيظهر الرد كالتالي، بدون نجاح أو فشل:

{
  "success": 0,
  "failure": 0
}

رسالة XMPP لمجموعة الأجهزة

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

استجابة XMPP لمجموعة الأجهزة

وعند إرسال الرسالة إلى أي جهاز من أجهزة المجموعة بنجاح، يستجيب خادم اتصال XMPP بإرسال ACK. وإذا تعذّر إرسال جميع الرسائل إلى جميع الأجهزة في المجموعة، يستجيب خادم اتصال XMPP برمز NACK.

في ما يلي مثال على حالة "النجاح": لدى notification_key 3 رموز مميّزة للتسجيل مرتبطة به، وقد تم إرسال الرسالة إلى جميع هذه الرموز بنجاح:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

في ما يلي مثال على "النجاح الجزئي": يتضمّن notification_key 3 رموز تسجيل مميّزة مرتبطة به. تم إرسال الرسالة بنجاح إلى واحد من الرموز المميّزة للتسجيل فقط. تسرد رسالة الرد الرموز المميزة للتسجيل التي تعذّر عليها تلقّي الرسالة:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

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

للحصول على القائمة الكاملة لخيارات الرسائل، يمكنك الاطّلاع على المعلومات المرجعية للبروتوكول الذي اخترته لخادم الاتصال، أي HTTP أو XMPP.

طرق الإرسال القديمة لحزمة تطوير البرامج (SDK) الخاصة بمشرف Firebase

تنبيه: تم في 21 شباط (فبراير) 2023 إيقاف واجهات برمجة تطبيقات SDK للمشرف في Node.js الموضّحة في هذا القسم، وستتم إزالة الوظيفة في شباط (فبراير) 2024. بدلاً من sendToDevice() وsendToDeviceGroup()، يمكنك استخدام send().

إنّ حزمة تطوير برامج Node.js لمشرفي Firebase تتيح طرقًا لإرسال الرسائل استنادًا إلى واجهة برمجة تطبيقات خادم FCM القديمة. تقبل هذه الطرق وسيطات مختلفة مقارنةً بطريقة send(). عليك استخدام طريقة send() كلّما أمكن ذلك، وعدم استخدام الطرق الموضّحة في هذه الصفحة إلا عند إرسال الرسائل إلى أجهزة فردية أو مجموعات أجهزة.

ملاحظة: لا تتوفّر واجهات برمجة التطبيقات هذه إلا في حزمة تطوير البرامج (SDK) الخاصة بالمشرف في Node.js.

الإرسال إلى أجهزة فردية

يمكنك تمرير رمز مميَّز للتسجيل إلى طريقة sendToDevice() لإرسال رسالة إلى هذا الجهاز:

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device corresponding to the provided
// registration token.
getMessaging().sendToDevice(registrationToken, payload)
  .then((response) => {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

يمكن لطريقة sendToDevice() أيضًا إرسال رسالة بث متعدّد (أي رسالة إلى أجهزة متعددة) من خلال تمرير مصفوفة من الرموز المميّزة للتسجيل بدلاً من رمز مميّز واحد للتسجيل:

Node.js

// These registration tokens come from the client FCM SDKs.
const registrationTokens = [
  'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...',
  // ...
  'ecupwIfBy1w:APA91bFtuMY7MktgxA3Au_Qx7cKqnf...'
];

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the devices corresponding to the provided
// registration tokens.
getMessaging().sendToDevice(registrationTokens, payload)
  .then((response) => {
    // See the MessagingDevicesResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

ملاحظة: يمكنك إرسال الرسائل إلى ما يصل إلى 1000 جهاز في طلب واحد. في حال تقديم مصفوفة تحتوي على أكثر من 1, 000 رمز مميَّز للتسجيل، سيتعذّر الطلب مع ظهور خطأ messaging/invalid-recipient.

تعرض الطريقة sendToDevice() وعودًا تم حلّه باستخدام كائن MessagingDevicesResponse يحتوي على الاستجابة من "المراسلة عبر السحابة الإلكترونية من Firebase". ويكون نوع الإرجاع بالتنسيق نفسه عند تمرير رمز مميَّز واحد للتسجيل أو مجموعة من الرموز المميّزة للتسجيل.

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

الإرسال إلى مجموعة أجهزة

تتيح لك طريقة sendToDeviceGroup() إرسال رسالة إلى مجموعة أجهزة من خلال تحديد مفتاح الإشعار لمجموعة الأجهزة هذه:

Node.js

// See the "Managing device groups" link above on how to generate a
// notification key.
const notificationKey = 'some-notification-key';

// See the "Defining the message payload" section below for details
// on how to define a message payload.
const payload = {
  data: {
    score: '850',
    time: '2:45'
  }
};

// Send a message to the device group corresponding to the provided
// notification key.
getMessaging().sendToDeviceGroup(notificationKey, payload)
  .then((response) => {
    // See the MessagingDeviceGroupResponse reference documentation for
    // the contents of response.
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

تعرض الطريقة sendToDeviceGroup() وعودًا تم حلّه باستخدام كائن MessagingDevicesResponse يحتوي على الاستجابة من "المراسلة عبر السحابة الإلكترونية من Firebase".

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

تحديد حمولة الرسالة

تقبل الطرق أعلاه المستندة إلى بروتوكولات "المراسلة عبر السحابة الإلكترونية من Firebase" القديمة حمولة الرسالة كوسيطة ثانية وتدعم كلاً من رسائل الإشعارات والبيانات. يمكنك تحديد نوع واحد أو كلا نوعَي الرسائل من خلال إنشاء كائن باستخدام المفتاحَين data و / أو notification. على سبيل المثال، إليك كيفية تعريف أنواع مختلفة من حمولات الرسائل:

رسالة إشعار

const payload = {
  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.'
  }
};

رسالة البيانات

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

رسالة مجمّعة

const payload = {
  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.'
  },
  data: {
    stock: 'GOOG',
    open: '829.62',
    close: '635.67'
  }
};

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

تتكون حمولات رسائل البيانات من أزواج المفتاح/القيمة المخصصة مع بعض القيود، بما في ذلك حقيقة أن جميع القيم يجب أن تكون سلاسل. راجِع المستندات المرجعية لـ DataMessagePayload للاطّلاع على قائمة كاملة بالقيود.

تحديد خيارات الرسالة

تقبل الطرق المذكورة أعلاه استنادًا إلى بروتوكولات "المراسلة عبر السحابة الإلكترونية من Firebase" القديمة وسيطة ثالثة اختيارية تحدد بعض الخيارات للرسالة. مثلاً، يرسل المثال التالي رسالة ذات أولوية عالية إلى جهاز تنتهي صلاحيته بعد 24 ساعة:

Node.js

// This registration token comes from the client FCM SDKs.
const registrationToken = 'bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...';

// See the "Defining the message payload" section above for details
// on how to define a message payload.
const payload = {
  notification: {
    title: 'Urgent action needed!',
    body: 'Urgent action is needed to prevent your account from being disabled!'
  }
};

// Set the message as high priority and have it expire after 24 hours.
const options = {
  priority: 'high',
  timeToLive: 60 * 60 * 24
};

// Send a message to the device corresponding to the provided
// registration token with the provided options.
getMessaging().sendToDevice(registrationToken, payload, options)
  .then((response) => {
    console.log('Successfully sent message:', response);
  })
  .catch((error) => {
    console.log('Error sending message:', error);
  });

راجِع المستندات المرجعية لـ MessagingOptions للاطّلاع على قائمة كاملة بالخيارات المتاحة.