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

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

الحدّ الأقصى لعدد الأعضاء المسموح به لمفتاح الإشعارات هو 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، عليك إرسال الطلب التالي: 

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}

تنسيق الرد

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

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

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

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

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

المَعلمة الاستخدام الوصف
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