Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

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

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

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

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

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

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

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

اختياريًا ، يمكن لتطبيقات عميل Android إدارة مجموعات الأجهزة من جانب العميل.

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

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

لإنشاء مجموعة أجهزة ، أرسل طلب 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": ["4", "8", "15", "16", "23", "42"]
}

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 _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 ، وقم بتوفير رموز التسجيل add أو الإزالة.

طلب HTTP POST

على سبيل المثال ، لإضافة جهاز بمعرف التسجيل 51 إلى appUser-Chris ، سترسل هذا الطلب:

{
   "operation": "add",
   "notification_key_name": "appUser-Chris",
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
   "registration_ids": ["51"]
}

تنسيق الاستجابة

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

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

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

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

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

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

ج 652057d08

رسالة 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.

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

{
  "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 .