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

باستخدام بروتوكولَي خادم التطبيقات Firebase Admin SDK أو FCM، يمكنك إنشاء طلبات رسائل وإرسالها إلى الأنواع التالية من الاستهدافات:

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

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

ملاحظة مهمة: يجب أن تحتوي طلبات إرسال البيانات لكل من بروتوكول HTTP في الإصدارَين Firebase Admin SDK و1 على رقم تعريف مشروع Firebase لتطبيقك، والذي يمكن العثور عليه في علامة التبويب General project settings (إعدادات المشروع العامة) في وحدة تحكّم Firebase. تتطلّب أيضًا كلتا الطريقتَين لإرسال الرسائل منك تفويض طلبات الإرسال.

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

ملاحظة: تم إيقاف إرسال الرسائل (بما في ذلك الرسائل الواردة) باستخدام واجهات برمجة التطبيقات القديمة FCM XMPP وHTTP نهائيًا في 20 حزيران (يونيو) 2023، وستتم إزالتها اعتبارًا من حزيران (يونيو) 2024. إذا كنت تستخدِم واجهات برمجة تطبيقات إرسالFCM القديمة، ننصحك بشدة بالانتقال إلى واجهة برمجة التطبيقات HTTP v1 API أو استخدام Admin 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);
  });

جافا

// 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

انتقال

// 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

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

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

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

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

تتيح لك واجهات برمجة تطبيقات Admin FCM نشر رسالة إعلام في وقت واحد إلى قائمة برموز تسجيل الأجهزة. يمكنك تحديد ما يصل إلى 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');
  });

جافا

// 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

انتقال

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

جافا

// 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

انتقال

// 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

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

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

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

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

جافا

// 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

انتقال

// 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

لإرسال رسالة إلى مجموعة من المواضيع، حدِّد شرطًا، وهو تعبير منطقي يحدِّد topics المستهدفة. على سبيل المثال، سيؤدي الشرط التالي إلى إرسال الرسائل إلى الأجهزة التي اشتركت في 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);
  });

جافا

// 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

انتقال

// 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. إذا كنت في الوقت الحالي تُرسِل الرسائل إلى مجموعات الأجهزة باستخدام واجهات برمجة التطبيقات القديمة المتوقّفة نهائيًا لإرسال رسائل بروتوكول HTTP أو XMPP أو أي من الإصدارات القديمة من واجهة برمجة التطبيقات Firebase Admin SDK لـ 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‏ 1 على أعداد عمليات الإرسال الناجحة وغير الناجحة. يؤدي إرسال ملف بنجاح إلى عرض استجابة فارغة.

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

ملاحظة مهمة: تم إيقاف طُرق الإرسال المجمّع الموضّحة في هذا القسم نهائيًا في 21 حزيران (يونيو) 2023، وسيتمّت إزالتها في حزيران (يونيو) 2024. بالنسبة إلى البروتوكول، استخدِم بدلاً من ذلك طريقة الإرسال العادية لواجهة برمجة التطبيقات HTTP v1، وطبِّق عملية الإرسال المجمّع الخاصة بك من خلال التنقّل في قائمة المستلمين والإرسال إلى الرمز المميّز لكل مستلِم. بالنسبة إلى طرق "حزمة 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');
  });

جافا

// 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

انتقال

// 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 القديمة. قبل الإرسال إلى الأجهزة في وضع التشغيل المباشر، تأكَّد من إكمال خطوات تفعيل أجهزة العميل لتلقّي رسائل FCM في وضع التشغيل المباشر.

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

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

يجب أن يتضمّن طلب الرسالة المفتاح "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 XMPP وHTTP نهائيًا في 20 حزيران (يونيو) 2023، وستتم إزالتها اعتبارًا من حزيران (يونيو) 2024. إذا كنت تستخدِم واجهات برمجة تطبيقات إرسالFCM القديمة، ننصحك بشدة بالانتقال إلى واجهة برمجة التطبيقات HTTP v1 API أو استخدام Admin 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
}

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

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

يسمح كل من Firebase Admin SDK وبروتوكول HTTP في الإصدار 1 من إطار عمل إدارة إشعارات Google (FCM) لطلبات الرسائل بضبط جميع الحقول المتاحة في كائن message. ويشمل ذلك ما يلي:

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

تمنحك الكتل الخاصة بالنظام الأساسي مرونة في تخصيص الرسائل لمختلف المنصات لضمان معالجتها بشكل صحيح عند تلقّيها. ستأخذ المعالجة الخلفية لـ FCM جميع المَعلمات المحدّدة في الاعتبار وستخصّص الرسالة لكل منصة.

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

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

• استهداف نُسخ التطبيق على جميع الأنظمة الأساسية، مثل 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);
  });

جافا

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

انتقال

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‏ 1 للحصول على تفاصيل كاملة عن المفاتيح المتاحة في الكتل الخاصة بالنظام الأساسي في نص الرسالة.

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

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

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‏ 1 للحصول على تفاصيل كاملة عن المفاتيح المتاحة في الكتل الخاصة بالنظام الأساسي في نص الرسالة.

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

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

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‏ 1 للحصول على تفاصيل كاملة عن المفاتيح المتاحة في الكتل الخاصة بالنظام الأساسي في نص الرسالة.

مثال: رسالة إشعار تتضمّن خيارات الأقلمة

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

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‏ 1 للحصول على تفاصيل كاملة عن المفاتيح المتاحة في الكتل الخاصة بالنظام الأساسي في نص الرسالة.

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

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

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

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

{
  "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‏ 1.0 يتضمّن رمز تنشيط تسجيل غير صالح

{
  "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 خطأ خاصًا بـ FCM. في العديد من الأخطاء، تحتوي صفيف التفاصيل على المعلومات التي ستحتاج إليها لتصحيح الأخطاء والعثور على حلّ.

يسرد الجدول التالي رموز أخطاء واجهة برمجة التطبيقات REST API في الإصدار 1 من خدمة "إشعارات Google من خادم Firebase" وأوصافها.

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

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

يسرد الجدول التالي رموز أخطاء واجهة برمجة التطبيقات FCM Admin API و أوصافها، بما في ذلك الخطوات المقترَحة لحلّها.

رمز الخطأ	الوصف وخطوات الحلّ
messaging/invalid-argument	تم تقديم وسيطة غير صالحة لطريقة FCM. يجب أن تتضمّن رسالة الخطأ معلومات إضافية.
messaging/invalid-recipient	عنوان مستلم الرسالة غير صالح. من المفترض أن تتضمّن رسالة الخطأ معلومات إضافية.
messaging/invalid-payload	تم تقديم عنصر غير صالح لحمولة الرسالة. من المفترض أن تتضمّن رسالة الخطأ معلومات إضافية.
messaging/invalid-data-payload-key	تحتوي حمولة رسالة البيانات على مفتاح غير صالح. راجِع مستندات مرجع DataMessagePayload للحصول على مفاتيح التشفير المحظورة.
messaging/payload-size-limit-exceeded	تتجاوز الحمولة المقدَّمة للرسالة حدود الحجم FCM. الحد الأقصى هو 4096 بايت لمعظم الرسائل. بالنسبة إلى الرسائل المُرسَلة إلى المواضيع، يبلغ الحد الأقصى 2048 بايت. يشمل إجمالي حجم الحمولة كلّ من المفاتيح والقيم.
messaging/invalid-options	تم تقديم عنصر غير صالح للخيارات المتاحة للرسائل. من المفترض أن تتضمّن رسالة الخطأ معلومات إضافية.
messaging/invalid-registration-token	تم تقديم رمز مميز غير صالح للتسجيل. تأكَّد من أنّه يتطابق مع الرمز المميّز للتسجيل الذي يتلقّاه تطبيق العميل من التسجيل باستخدام FCM. لا ينبغي اقتطاعه أو إضافة أحرف إضافية إليه.
messaging/registration-token-not-registered	الرمز المميّز المقدَّم للتسجيل غير مسجَّل. يمكن إلغاء تسجيل رمز تسجيل صالح سابقًا لعدة أسباب، بما في ذلك: ألغى تطبيق العميل تسجيل نفسه من FCM. تم إلغاء تسجيل تطبيق العميل تلقائيًا. يمكن أن يحدث ذلك إذا أزال المستخدم التطبيق أو إذا أبلغت "خدمة ملاحظات APNs" على منصات Apple عن رمز APNs باعتباره غير صالح. انتهت صلاحية الرمز المميّز للتسجيل. على سبيل المثال، قد تقرّر Google إعادة تحميل الرموز المميّزة للتسجيل أو قد تنتهي صلاحية رمز APNs على أجهزة 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 إلى تطبيقك للحصول على مستندات حول كيفية مصادقة Firebase Admin SDK.
messaging/authentication-error	تعذّر على حزمة تطوير البرامج (SDK) المصادقة مع خوادم FCM. تأكَّد من مصادقة Firebase Admin SDK باستخدام بيانات اعتماد تتضمّن الأذونات المناسبة لإرسال رسائل FCM. راجِع مقالة إضافة Firebase إلى تطبيقك للحصول على مستندات حول كيفية مصادقة Firebase Admin SDK.
messaging/server-unavailable	تعذّر على خادم FCM معالجة الطلب في الوقت المحدّد. عليك إعادة محاولة إرسال الطلب نفسه، ولكن عليك إجراء ما يلي: يجب الالتزام بعنوان Retry-After إذا كان مضمّنًا في الاستجابة الواردة من FCM Connection Server. نفِّذ ميزة "الرقود الأسي الثنائي" في آلية إعادة المحاولة. على سبيل المثال، إذا انتظرت ثانية واحدة قبل المحاولة الأولى، انتظِر اثنتين على الأقل قبل المحاولة التالية، ثم أربع ثوانٍ، وهكذا. إذا كنت تُرسِل رسائل متعدّدة، يمكنك تأخير كل رسالة بشكل مستقل بمقدار إضافي عشوائي لتجنّب تقديم طلب جديد لجميع الرسائل في الوقت نفسه. يواجه المُرسِلون الذين يتسببون في مشاكل خطر إدراجهم في القائمة السوداء.
messaging/internal-error	واجه خادم FCM خطأً أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة إرسال الطلب نفسه باتّباع المتطلبات الواردة في صف messaging/server-unavailable أعلاه. إذا استمرّ الخطأ، يُرجى الإبلاغ عن المشكلة في قناة الدعم الخاصة بموضوع الإبلاغ عن الأخطاء.
messaging/unknown-error	تم عرض خطأ غير معروف في الخادم. يمكنك الاطّلاع على ردّ الخادم الأوّلي في رسالة الخطأ للحصول على مزيد من التفاصيل. إذا ظهرت لك رسالة الخطأ هذه، يُرجى الإبلاغ عن رسالة الخطأ الكاملة إلى قناة الدعم المخصّصة لتلقّي تقارير الأخطاء.

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

ملاحظة: تم إيقاف إرسال الرسائل (بما في ذلك الرسائل الواردة) باستخدام واجهات برمجة التطبيقات القديمة FCM XMPP وHTTP نهائيًا في 20 حزيران (يونيو) 2023، وستتم إزالتها اعتبارًا من حزيران (يونيو) 2024. إذا كنت تستخدِم واجهات برمجة تطبيقات إرسالFCM القديمة، ننصحك بشدة بالانتقال إلى واجهة برمجة التطبيقات HTTP v1 API أو استخدام Admin 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 Cloud Messaging إلى حد كبير إرسال الرسائل إلى جهاز فردي أو إلى مجموعة مستخدمين. يضبط خادم التطبيق مفتاح to بقيمة مثل /topics/yourTopic. يمكن للمطوّرين اختيار أي اسم موضوع يتطابق مع التعبير العادي: "/topics/[a-zA-Z0-9-_.~%]+".

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

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

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

• TopicA وTopicB
• TopicA وTopicC

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

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

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

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

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

إنّ إرسال الرسائل إلى مجموعة أجهزة باستخدام واجهات برمجة التطبيقات القديمة المهجورة يشبه إلى حد كبير إرسال الرسائل إلى جهاز فردي. اضبط المَعلمة to على مفتاح الإشعار الفريد لمجموعة الأجهزة. توضِّح الأمثلة الواردة في هذا القسم كيفية إرسال رسائل data إلى مجموعات الأجهزة في بروتوكولَي 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 برسالة تأكيد. إذا كانت جميع الرسائل المُرسَلة إلى جميع الأجهزة في المجموعة لا تجتاز الفحص، يردّ خادم اتصال بروتوكول 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"
  ]
}

عندما يتعذّر على خادم اتصال FCM إرسال الرسائل إلى جميع الأجهزة في المجموعة سيتلقّى خادم التطبيق استجابة nack.

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

Firebase Admin SDK طرق الإرسال القديمة

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

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

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

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

يمكنك تمرير رمز مميّز للتسجيل إلى الوسيطة 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);
  });

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

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

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

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

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

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

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

تقبل الطرق المذكورة أعلاه المستندة إلى بروتوكولات FCM القديمة حمولة رسالة كوسيطة ثانية وتتوافق مع كلاً من إشعارات البيانات والرسائل. يمكنك تحديد نوع واحد من أنواع الرسائل أو النوعَين معًا عن طريق إنشاء عنصر باستخدام المفتاحَين 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 للحصول على قائمة كاملة بالقيود.

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

تقبل الطرق أعلاه المستندة إلى بروتوكولات FCM القديمة مَعلمة ثالثة اختيارية تحدِّد بعض خيارات الرسالة. على سبيل المثال، يرسل المثال التالي رسالة ذات أولوية عالية إلى جهاز تنتهي صلاحيتها بعد 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 للحصول على قائمة كاملة بالخيارات المتاحة.