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

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

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

الحد الأقصى لعدد الأعضاء المسموح به لمفتاح الإشعار هو 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 لاسم مفتاح إشعار معيّن، يعرض الخادم سلسلة فريدة مرمّزة. على الرغم من أنّ كل سلسلة قد تبدو مفتاحًا مختلفًا، إلا أنّها في الواقع قيمة notification_key صالحة.

جارٍ استرداد رموز مميّزة عددها FCM لمجموعات الأجهزة

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

https://fcm.googleapis.com/fcm/notification?notification_key=APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ
Content-Type:application/json
access_token_auth: true
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
project_id:SENDER_ID
{}

يظهر الرد على النحو التالي:

{
   "notification_key_name": "appUser-Chris",
   "registration_ids": ["token1", "token2"]
}

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

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