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

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

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

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

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

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

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

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

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

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

لإنشاء مجموعة أجهزة، أرسِل طلب 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، وقدِّم علامات تسجيل للإضافة أو الإزالة.

إذا أزلت جميع الرموز المميّزة الحالية للتسجيل من مجموعة أجهزة، يحذف FCM مجموعة الأجهزة.

طلب 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"
}

ملاحظة: ليس من الضروري استخدام notification_key_name لإضافة/إزالة الرموز المميّزة للتسجيل، ولكنّ تضمينه يحميك من استخدامnotification_key غير الصحيح عن طريق الخطأ.

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

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

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

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

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

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

RESTأمر cURL

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 -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 على أعداد عمليات الإرسال الناجحة وغير الناجحة. يؤدي الإرسال الناجح إلى عرض استجابة فارغة.