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

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

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

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