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

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

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

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

פורמט התגובה

אם הבקשה להוספה או להסרה של מכשיר בוצעה בהצלחה, תקבלו notification_key שדומה לדוגמה הבאה:

{
   "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ"
}

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

בטבלה הבאה מפורטים המפתחות ליצירת קבוצות של מכשירים, להוספת חברים ולהסרת חברים.

טבלה 10. מפתחות ניהול של קבוצות מכשירים.

פרמטר שימוש תיאור
operation שדה חובה, מחרוזת הפעולה להרצה. הערכים החוקיים הם create,‏ add ו-remove.
notification_key_name חובה, מחרוזת השם שהמשתמש נתן לקבוצת המכשירים שיוצרים או משנים.
notification_key חובה (למעט הפעולה create, מחרוזת המזהה הייחודי של קבוצת המכשירים. הערך הזה מוחזר בתגובה לפעולת create מוצלחת, והוא נדרש לכל הפעולות הבאות בקבוצת המכשירים.
registration_ids חובה, מערך של מחרוזות האסימונים של המכשיר שרוצים להוסיף או להסיר. אם תסירו את כל אסימוני ההרשמה הקיימים מקבוצת מכשירים, מערכת FCM תמחק את קבוצת המכשירים.

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

כדי לשלוח הודעות לקבוצות של מכשירים, משתמשים ב-HTTP v1 API. אם אתם שולחים כרגע לקבוצות של מכשירים באמצעות ממשקי ה-API הקודמים של HTTP או XMPP, או באמצעות אחת מהגרסאות הקודמות של Firebase Admin SDK ל-Node.js שמבוססות על הפרוטוקולים הקודמים, מומלץ מאוד לעבור ל-HTTP v1 API בהקדם האפשרי. ממשקי ה-API הקודמים לשליחה יושבתו ויוסרו ביוני 2024.

שליחת הודעות לקבוצת מכשירים דומה מאוד לשליחת הודעות למכשיר ספציפי, וניתן להשתמש באותה שיטה כדי להעניק הרשאה לבקשות שליחה. מגדירים את השדה 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