Catch up on highlights from Firebase at Google I/O 2023. Learn more

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

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

يمكنك استخدام الرسائل الجماعية للأجهزة عبر بروتوكولات XMPP أو HTTP القديمة على خادم التطبيق الخاص بك. تستند الإصدارات الأقدم من Firebase Admin SDK لـ Node.js إلى البروتوكولات القديمة وتوفر أيضًا إمكانيات المراسلة لمجموعة الأجهزة. الحد الأقصى لعدد الأعضاء المسموح به لمفتاح الإعلام هو 20.

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

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

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

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

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

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

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

لإنشاء مجموعة أجهزة ، أرسل طلب POST الذي يوفر اسمًا للمجموعة وقائمة برموز التسجيل المميزة للأجهزة. تُعيد FCM notification_key جديد يمثل مجموعة الأجهزة.

طلب HTTP POST

أرسل طلبًا مثل ما يلي إلى https://fcm.googleapis.com/fcm/notification :

https://fcm.googleapis.com/fcm/notification
Content-Type:application/json
Authorization:key=API_KEY
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
Authorization:key=API_KEY
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"
}

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

إرسال الرسائل إلى مجموعة أجهزة يشبه إلى حد بعيد إرسال الرسائل إلى جهاز فردي. قم بتعيين to إلى مفتاح الإعلام الفريد لمجموعة الأجهزة. راجع أنواع الرسائل للحصول على تفاصيل حول دعم الحمولة. توضح الأمثلة في هذه الصفحة كيفية إرسال رسائل البيانات إلى مجموعات الأجهزة في بروتوكولات HTTP و XMPP القديمة.

طلب HTTP POST لمجموعة الأجهزة

https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

{
  "to": "aUniqueKey",
  "data": {
    "hello": "This is a Firebase Cloud Messaging Device Group Message!",
   }
}

استجابة HTTP لمجموعة الأجهزة

فيما يلي مثال على "نجاح" - يحتوي " notification_key " على رمزين مميزين للتسجيل مرتبطين به ، وتم إرسال الرسالة لكليهما بنجاح:

{
  "success": 2,
  "failure": 0
}

فيما يلي مثال على "النجاح الجزئي" - يحتوي notification_key على 3 رموز مميزة للتسجيل مرتبطة به. تم إرسال الرسالة بنجاح إلى 1 من الرموز المميزة للتسجيل فقط. تسرد رسالة الرد رموز التسجيل ( registration_ids ) التي فشلت في تلقي الرسالة:

{
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

عندما يفشل تسليم رسالة إلى واحد أو أكثر من الرموز المميزة للتسجيل المرتبطة notification_key ، يجب على خادم التطبيق إعادة المحاولة مع التراجع بين عمليات إعادة المحاولة.

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

{
  "success": 0,
  "failure": 0
}

رسالة XMPP لمجموعة الأجهزة

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to": "aUniqueKey",
      "message_id": "m-1366082849205" ,
      "data": {
          "hello":"This is a Firebase Cloud Messaging Device Group Message!"
      }
  }
  </gcm>
</message>

استجابة XMPP لمجموعة الأجهزة

عندما يتم إرسال الرسالة إلى أي جهاز من الأجهزة في المجموعة بنجاح ، يستجيب خادم اتصال XMPP بـ ACK. إذا فشلت جميع الرسائل المرسلة إلى جميع الأجهزة في المجموعة ، يستجيب خادم اتصال XMPP بـ NACK.

فيما يلي مثال على "نجاح" - يوجد 3 رموز تسجيل مرتبطة notification_key ، وقد تم إرسال الرسالة إلى كل منهم بنجاح:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success": 3,
  "failure": 0,
  "message_id": "m-1366082849205"
}

فيما يلي مثال على "النجاح الجزئي" - يحتوي notification_key على 3 رموز مميزة للتسجيل مرتبطة به. تم إرسال الرسالة بنجاح إلى 1 من الرموز المميزة للتسجيل فقط. تسرد رسالة الرد رموز التسجيل التي فشلت في تلقي الرسالة:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

عندما يفشل خادم اتصال FCM في التسليم لجميع الأجهزة في المجموعة. سيتلقى خادم التطبيق استجابة غير متوقعة.

للحصول على القائمة الكاملة لخيارات الرسائل ، راجع المعلومات المرجعية لبروتوكول خادم الاتصال الذي اخترته ، HTTP أو XMPP .