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

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

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

הוספה והסרה של מכשירים מקבוצת מכשירים

כדי להוסיף מכשירים לקבוצה קיימת או להסיר מכשירים ממנה, שולחים בקשת 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