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

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

الحدّ الأقصى لعدد الأعضاء المسموح به لمفتاح الإشعارات هو 20.

إدارة مجموعات الأجهزة

قبل إرسال رسائل إلى مجموعة أجهزة، يجب إجراء ما يلي:

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

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

إدارة مجموعات الأجهزة على خادم التطبيق

إنشاء مجموعة أجهزة

لإنشاء مجموعة أجهزة، أرسِل طلب POST يوفّر اسمًا للمجموعة وقائمة برموز التسجيل للأجهزة. تعرض FCM notification_key جديدًا يمثّل مجموعة الأجهزة.

طلب HTTP POST

أرسِل طلبًا مشابهًا لما يلي إلى https://fcm.googleapis.com/fcm/notification:

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "create",
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
                        "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...",
                        ... ]
}

notification_key_name هو اسم أو معرّف (مثل اسم مستخدم) فريد لمجموعة معيّنة. يكون كل من notification_key_name وnotification_key فريدًا لمجموعة من رموز التسجيل المميزة. من المهم أن يكون notification_key_name فريدًا لكل تطبيق عميل إذا كان لديك عدة تطبيقات عميل تستخدم معرّف المرسل نفسه. ويضمن ذلك توجيه الرسائل إلى التطبيق المستهدف فقط.

تنسيق الردّ

يعرض الطلب الناجح notification_key على النحو التالي:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

احفظ notification_key وnotification_key_name المقابل لاستخدامهما في العمليات اللاحقة.

استرداد مفتاح إشعار

إذا كنت بحاجة إلى استرداد مفتاح إشعار حالي، استخدِم notification_key_name في طلب GET كما هو موضّح:

https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

لكل طلب GET لاسم مفتاح إشعار معيّن، يعرض الخادم سلسلة مشفّرة فريدة. على الرغم من أنّ كل سلسلة قد تبدو مفتاحًا مختلفًا، إلّا أنّها في الواقع قيمة notification_key صالحة.

إضافة الأجهزة وإزالتها من مجموعة أجهزة

لإضافة أجهزة إلى مجموعة حالية أو إزالتها منها، أرسِل طلب POST مع ضبط المَعلمة operation على add أو remove، وقدِّم رموز التسجيل لإضافتها أو إزالتها.

طلب HTTP POST

على سبيل المثال، لإضافة جهاز باستخدام رمز التسجيل bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1... إلى appUser-Chris، عليك إرسال الطلب التالي:

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}
تنسيق الردّ

يؤدي الطلب الناجح لإضافة جهاز أو إزالته إلى عرض notification_key على النحو التالي:

{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }

مفاتيح إدارة مجموعات الأجهزة

يسرد الجدول التالي المفاتيح المستخدَمة لإنشاء مجموعات الأجهزة وإضافة الأعضاء وإزالتهم.

المَعلمة الاستخدام الوصف
operation مطلوب، سلسلة العملية التي سيتم تنفيذها.القيم الصالحة هي create وadd وremove.
notification_key_name مطلوب، سلسلة اسم مجموعة الأجهزة الذي يحدّده المستخدم لإنشائه أو تعديله.
notification_key مطلوبة (باستثناء العملية create، سلسلة) المعرّف الفريد لمجموعة الأجهزة. يتم عرض هذه القيمة في الردّ على عملية create ناجحة، وهي مطلوبة لجميع العمليات اللاحقة على مجموعة الأجهزة.
registration_ids مطلوب، مصفوفة من السلاسل رموز الأجهزة التي سيتمّ إضافتها أو إزالتها إذا أزلت جميع رموز التسجيل الحالية من مجموعة أجهزة، ستحذف خدمة FCM مجموعة الأجهزة.

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

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