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

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

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

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

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

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

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

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

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

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

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

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