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

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

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

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

قبل إرسال الرسائل إلى مجموعة أجهزة، عليك تنفيذ ما يلي:

  1. احصل على رموز التسجيل المميَّزة لكل جهاز تريد إضافته إلى المجموعة.

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

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

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

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

لإنشاء مجموعة أجهزة، أرسِل طلب POST الذي يوفّر اسمًا للمجموعة وقائمة بالرموز المميّزة للتسجيل للأجهزة. تعرض خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" رمز 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 لاسم مفتاح إشعار معيّن، يعرض الخادم سلسلة مشفرة فريدة. ومع أنّ كل سلسلة قد تبدو كمفتاح مختلف، فإنّها في الواقع قيمة "مفتاح_إشعار" صالحة.

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

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

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

لإرسال رسائل إلى مجموعات أجهزة، استخدِم 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