תחילת העבודה עם Firebase Cloud Messaging


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

הגדרה של אפליקציית לקוח בפלטפורמות של אפלFirebase Cloud Messaging

באפליקציות לקוח של Apple, אפשר לקבל התראות ומטעני נתונים (payload) של עד 4,096 בייט דרך ממשק Firebase Cloud Messaging APNs.

כדי לכתוב את קוד הלקוח ב-Objective-C או ב-Swift, מומלץ להשתמש ב-FIRMessaging API. בדוגמה של התחלה מהירה יש קוד לדוגמה בשתי השפות.

לפני שמתחילים, צריך להוסיף את Firebase לפרויקט Apple.

שינוי פונקציונליות של שיטה ב-Firebase Cloud Messaging

ערכת ה-SDK‏ FCM מבצעת החלפת שיטות בשני תחומים מרכזיים: מיפוי של טוקן APNs לטוקן הרישום של FCM ואיסוף נתוני ניתוח במהלך הטיפול בקריאה חוזרת (callback) של הודעות במורד הזרם. מפתחים שלא רוצים להשתמש ב-swizzling יכולים להשבית אותו על ידי הוספת הדגל FirebaseAppDelegateProxyEnabled לקובץ Info.plist של האפליקציה והגדרתו ל-NO (ערך בוליאני). באזורים הרלוונטיים במדריכים מופיעות דוגמאות לקוד, עם הפעלה של החלפת שיטות וגם ללא הפעלה של החלפת שיטות.

העלאת מפתח אימות של APNs

מעלים את מפתח האימות של APNs ל-Firebase. אם עדיין אין לכם מפתח אימות APNs, הקפידו ליצור אותו ב-Apple Developer Member Center.

  1. בפרויקט במסוף Firebase, לוחצים על סמל גלגל השיניים, בוחרים באפשרות Project Settings (הגדרות הפרויקט) ואז בוחרים בכרטיסייה Cloud Messaging (הודעות Cloud).

  2. בקטע APNs authentication key (מפתח אימות של APNs) בקטע iOS app configuration (הגדרת אפליקציה ל-iOS), לוחצים על הלחצן Upload (העלאה) כדי להעלות את מפתח האימות של סביבת הפיתוח, את מפתח האימות של סביבת הייצור או את שניהם. צריך להזין לפחות תמונה אחת.

  3. מדפדפים למיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על פתיחה. מוסיפים את מזהה המפתח (שזמין ב- Apple Developer Member Center) ולוחצים על העלאה.

הרשמה לקבלת התראות מרחוק

בתחילת ההפעלה או בנקודה הרצויה בתהליך השימוש באפליקציה, צריך לרשום את האפליקציה לקבלת התראות מרחוק. קוראים ל-registerForRemoteNotifications כמו שמוצג:

Swift

UNUserNotificationCenter.current().delegate = self

let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
UNUserNotificationCenter.current().requestAuthorization(
  options: authOptions,
  completionHandler: { _, _ in }
)

application.registerForRemoteNotifications()

AppDelegate.swift

Objective-C

[UNUserNotificationCenter currentNotificationCenter].delegate = self;
UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert |
    UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
[[UNUserNotificationCenter currentNotificationCenter]
    requestAuthorizationWithOptions:authOptions
    completionHandler:^(BOOL granted, NSError * _Nullable error) {
      // ...
    }];

[application registerForRemoteNotifications];
AppDelegate.m

גישה לטוקן הרישום

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

בדומה לאופן שבו פלטפורמות של Apple בדרך כלל מספקות טוקן מכשיר של APNs בהפעלת האפליקציה,‏ FCM מספק טוקן רישום באמצעות השיטה messaging:didReceiveRegistrationToken: של FIRMessagingDelegate. ה-SDK של FCM מאחזר אסימון חדש או קיים במהלך ההפעלה הראשונית של האפליקציה, ובכל פעם שהאסימון מתעדכן או נפסל. בכל המקרים, FCM SDK קורא ל-messaging:didReceiveRegistrationToken: עם טוקן תקין.

אסימון הרישום עשוי להשתנות במקרים הבאים:

  • האפליקציה משוחזרת במכשיר חדש
  • המשתמש מסיר את האפליקציה ומתקין אותה מחדש
  • המשתמש מוחק את נתוני האפליקציה.

הגדרת נציג לניהול שיחות

כדי לקבל טוקנים של רישום, צריך להטמיע את פרוטוקול שליחת ההודעות של delegate ולהגדיר את המאפיין FIRMessaging של delegate אחרי הקריאה ל-[FIRApp configure]. לדוגמה, אם נציג האפליקציה תואם לפרוטוקול של נציג ההודעות, אפשר להגדיר את הנציג ב-application:didFinishLaunchingWithOptions: לעצמו.

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

אחזור של טוקן הרישום הנוכחי

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

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

אפשר לאחזר את האסימון ישירות באמצעות token(completion:). אם אחזור האסימון נכשל מסיבה כלשהי, תסופק שגיאה שאינה null.

Swift

Messaging.messaging().token { token, error in
  if let error = error {
    print("Error fetching FCM registration token: \(error)")
  } else if let token = token {
    print("FCM registration token: \(token)")
    self.fcmRegTokenMessage.text  = "Remote FCM registration token: \(token)"
  }
}

Objective-C

[[FIRMessaging messaging] tokenWithCompletion:^(NSString *token, NSError *error) {
  if (error != nil) {
    NSLog(@"Error getting FCM registration token: %@", error);
  } else {
    NSLog(@"FCM registration token: %@", token);
    self.fcmRegTokenMessage.text = token;
  }
}];

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

מעקב אחרי רענון טוקנים

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

Swift

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")

  let dataDict: [String: String] = ["token": fcmToken ?? ""]
  NotificationCenter.default.post(
    name: Notification.Name("FCMToken"),
    object: nil,
    userInfo: dataDict
  )
  // TODO: If necessary send token to application server.
  // Note: This callback is fired at each app startup and whenever a new token is generated.
}

AppDelegate.swift

Objective-C

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistrationToken:(NSString *)fcmToken {
    NSLog(@"FCM registration token: %@", fcmToken);
    // Notify about received token.
    NSDictionary *dataDict = [NSDictionary dictionaryWithObject:fcmToken forKey:@"token"];
    [[NSNotificationCenter defaultCenter] postNotificationName:
     @"FCMToken" object:nil userInfo:dataDict];
    // TODO: If necessary send token to application server.
    // Note: This callback is fired at each app startup and whenever a new token is generated.
}
AppDelegate.m

אפשרות אחרת היא להאזין לאירוע NSNotification בשם kFIRMessagingRegistrationTokenRefreshNotification במקום לספק שיטת delegate. מאפיין הטוקן תמיד מכיל את ערך הטוקן הנוכחי.

החלפת שיטות מושבתת: מיפוי של טוקן APNs וטוקן רישום

אם השבתתם את החלפת השיטות או שאתם מפתחים אפליקציית SwiftUI, תצטרכו למפות באופן מפורש את טוקן ה-APNs לטוקן הרישום FCM. מטמיעים את השיטה application(_:didRegisterForRemoteNotificationsWithDeviceToken:) כדי לאחזר את טוקן ה-APNs, ואז מגדירים את המאפיין apnsToken של Messaging:

Swift

func application(application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Messaging.messaging().apnsToken = deviceToken
}

Objective-C

// With "FirebaseAppDelegateProxyEnabled": NO
- (void)application:(UIApplication *)application
    didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [FIRMessaging messaging].APNSToken = deviceToken;
}

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

מניעת הפעלה אוטומטית

כשנוצר FCM אסימון רישום, הספרייה מעלה את המזהה ואת נתוני ההגדרה ל-Firebase. אם אתם רוצים לקבל הסכמה מפורשת מהמשתמשים קודם, אתם יכולים להשבית את FCM כדי למנוע יצירת אסימונים בזמן ההגדרה. כדי לעשות את זה, מוסיפים ערך מטא-נתונים ל-Info.plist (ולא ל-GoogleService-Info.plist):

FirebaseMessagingAutoInitEnabled = NO

כדי להפעיל מחדש את FCM, אפשר לבצע קריאה בזמן ריצה:

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[FIRMessaging messaging].autoInitEnabled = YES;

הערך הזה נשמר גם אחרי הפעלה מחדש של האפליקציה, אחרי שהוא מוגדר.

שליחת הודעת התראה

  1. מתקינים את האפליקציה ומפעילים אותה במכשיר היעד. במכשירי Apple, מאשרים את בקשת ההרשאה לקבלת התראות מרחוק.
  2. בודקים שהאפליקציה פועלת ברקע במכשיר.
  3. במסוף Firebase, פותחים את הדף הודעות.
  4. אם זו ההודעה הראשונה שלכם, בוחרים באפשרות יצירת הקמפיין הראשון.
    1. בוחרים באפשרות הודעות התראה של Firebase ולוחצים על יצירה.
  5. אחרת, בכרטיסייה קמפיינים, בוחרים באפשרות קמפיין חדש ואז באפשרות התראות.
  6. מזינים את הטקסט של ההודעה.
  7. בחלונית השמאלית, לוחצים על שליחת הודעת בדיקה.
  8. בשדה עם התווית הוספת טוקן רישום של FCM, מזינים את טוקן הרישום.
  9. בוחרים באפשרות בדיקה.

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

כדי לקבל תובנות לגבי מסירת הודעות לאפליקציה, אפשר לעיין בFCM לוח הבקרה של הדוחות, שבו מתועד מספר ההודעות שנשלחו ונפתחו במכשירי Apple ובמכשירי Android.

השלבים הבאים

אחרי שמגדירים את לקוח Apple, אפשר להתחיל לקבל ולשלוח הודעות למשתמשים: