إرسال الرسائل إلى مجموعات الأجهزة على نظام التشغيل Android

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

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

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

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

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

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

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

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

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

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

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

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