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

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

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

الحد الأقصى لعدد الأعضاء المسموح بهم لمفتاح الإشعار هو 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