שליחת הודעות לקבוצות מכשירים

העברת הודעות לקבוצת מכשירים מאפשרת לכם להוסיף כמה מכשירים לקבוצה אחת. האפשרות הזו דומה להעברת הודעות לפי נושא, אבל כוללת אימות כדי לוודא שהחברות בקבוצה מנוהלת רק על ידי השרתים שלכם.

לדוגמה, אם רוצים לשלוח הודעות שונות לדגמי טלפונים שונים, השרתים יכולים להוסיף או להסיר רישומים לקבוצות המתאימות ולשלוח את ההודעה המתאימה לכל קבוצה. ההבדל בין העברת הודעות לקבוצת מכשירים לבין העברת הודעות לפי נושא הוא שבמקרה הראשון, קבוצות המכשירים מנוהלות מהשרתים שלכם ולא ישירות מתוך האפליקציה.

המספר המקסימלי של חברים שמותר להוסיף למפתח התראות הוא 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