איך מתחילים להשתמש ב-Firebase Cloud Messaging באפליקציות לפלטפורמת Apple

במדריך הזה מוסבר איך להתחיל להשתמש ב-Firebase Cloud Messaging באפליקציות הלקוח שלכם בפלטפורמות של Apple (כמו iOS) כדי שתוכלו לשלוח הודעות באופן מהימן.

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

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

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

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

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

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

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

1. במסוף Firebase, נכנסים אל settings הגדרות > כללי. ואז לוחצים על הכרטיסייה העברת הודעות בענן.
2. בקטע APNs authentication key (מפתח אימות של APNs) שמתחת לקטע iOS app configuration (הגדרת אפליקציה ל-iOS), לוחצים על Upload (העלאה) כדי להעלות את מפתח האימות של הסביבה לפיתוח, או את מפתח האימות של סביבת הייצור, או את שניהם. צריך להוסיף לפחות אחד.
3. עוברים למיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על Open. מוסיפים את מזהה המפתח (שזמין ב-Apple Developer Member Center) ולוחצים על העלאה.

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

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
MigratedSnippets.swift

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

[application registerForRemoteNotifications];
ObjCMigratedSnippets.m

גישה למזהה ההתקנה של Firebase

כברירת מחדל, ה-SDK של FCM רושם את מופע האפליקציה ב-FCM ומחזיר מזהה התקנה של Firebase‏ (FID) למופע של אפליקציית הלקוח כשהאפליקציה מופעלת. בדומה לטוקן המכשיר של APNs, ה-FID הזה מאפשר לכם לשלוח התראות ממוקדות לכל מופע ספציפי של האפליקציה שלכם.

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

הפעלת הרישום באמצעות מזהה ההתקנה של Firebase

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

FirebaseMessagingInstallationIdEnabled = YES

הגדרת הנציג להעברת הודעות

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

מטמיעים את השיטה didReceiveRegistration

אחרי שההרשמה מסתיימת, המערכת משתמשת ב-FID כדי לטרגט מופעים של האפליקציה. כדי לקבל את ה-FID בזמן הרישום, מטמיעים את ה-method‏ messaging:didReceiveRegistration:. בדרך כלל, קוראים לשיטה הזו פעם אחת בכל הפעלה של האפליקציה עם ה-FID. כשמפעילים את ה-method הזו, אפשר לבצע את הפעולות הבאות:

• אם לא שלחתם את ה-FID לשרת, או ששלחתם אותו לאחרונה, שלחו אותו לשרת האפליקציה.
• אם המינוי חדש או שהמשתמש התקין מחדש את האפליקציה, צריך לרשום את ה-FID לנושאים.

func messaging(_ messaging: Messaging, didReceiveRegistration installationId: String?) {
  print("Firebase Installation ID: \(String(describing: installationId))")
  // Note: This callback is fired at each app startup.

  if let installationId = installationId {
    // Send the Firebase Installation ID to your app server.
    sendRegistrationToServer(installationId)
  }
}
    

- (void)messaging:(FIRMessaging *)messaging didReceiveRegistration:(nullable NSString *)installationId {
  NSLog(@"Firebase Installation ID: %@", installationId);
  // Note: This callback is fired at each app startup.

  if (installationId != nil) {
    // Send the Firebase Installation ID to your app server.
    [self sendRegistrationToServer:installationId];
  }
}
    

רישום ידני כשההפעלה האוטומטית מושבתת

אם השבתתם את ההפעלה האוטומטית, ה-SDK של FCM לא ירשום באופן אוטומטי את מופע האפליקציה ב-FCM בזמן הפעלת האפליקציה. כדי להפעיל את הרישום ואת המסירה של ה-FID דרך השיטה messaging:didReceiveRegistration:, צריך לבצע קריאה ל-register בהפעלת האפליקציה:

// Trigger manual registration if auto-initialization is turned off.
Messaging.messaging().register { error in
    if let error = error {
        // Handle the error
        print("Failed registering: \(error)")
        return
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    print("Successfully registered.")
}
    

// Trigger manual registration if auto-initialization is turned off.
[[FIRMessaging messaging] registerWithCompletion:^(NSError * _Nullable error) {
    if (error) {
        // Handle the error
        NSLog(@"Failed registering: %@", error);
        return;
    }
    // Registration was successful. FID is delivered through the messaging:didReceiveRegistration: method.
    NSLog(@"Successfully registered.");
}];
    

החלפת שיטות מושבתת: מיפוי של טוקן ה-APNs וה-FID

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

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

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

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

גישה לטוקן הרישום (יצא משימוש)

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

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

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

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

הגדרת הנציג להעברת הודעות

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

אחזור של אסימון הרישום הנוכחי

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

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

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

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

[[FIRMessaging messaging] tokenWithCompletion:^(NSString * _Nullable token, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"Error fetching the remote FCM registration token: %@", error);
  } else {
    NSLog(@"Remote FCM registration token: %@", token);
    NSString* message =
      [NSString stringWithFormat:@"FCM registration token: %@", token];
    // display message
    NSLog(@"%@", message);
  }
}];

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

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

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

func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
  print("Firebase registration token: \(String(describing: fcmToken))")
  // TODO: If necessary send token to application server.
  // Note: This callback is fired at each app startup and whenever a new token is generated.
}
MigratedSnippets.swift

- (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.
}
ObjCMigratedSnippets.m

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

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

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

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

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

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

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

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

FirebaseMessagingAutoInitEnabled = NO

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

Messaging.messaging().autoInitEnabled = true

[FIRMessaging messaging].autoInitEnabled = YES;

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

הגדרת התוסף של שירות ההתראות

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

כדי להוסיף תוסף שירות, מבצעים את משימות ההגדרה הנדרשות לשינוי ולהצגה של התראות ב-APNs, ואז מוסיפים את ה-API של FCM extension helper ב-NotificationService.m. באופן ספציפי, במקום להשלים את הקריאה החוזרת (callback) באמצעות self.contentHandler(self.bestAttemptContent);, צריך להשלים אותה באמצעות FIRMessaging extensionHelper, כמו שמוצג כאן:

@interface NotificationService () <NSURLSessionDelegate>
@property(nonatomic) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property(nonatomic) UNMutableNotificationContent *bestAttemptContent;
@end

‎@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
self.bestAttemptContent = [request.content mutableCopy];

    // Modify the notification content here as you want
self.bestAttemptContent.title = [NSString stringWithFormat:@"%@ [modified]",
self.bestAttemptContent.title];

  // Call FIRMessaging extension helper API.
  [[FIRMessaging extensionHelper] populateNotificationContent:self.bestAttemptContent
withContentHandler:contentHandler];

}
...

שליחת הודעה

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

2. מוודאים שהאפליקציה פועלת ברקע במכשיר.

3. במסוף Firebase, עוברים אל DevOps & Engagement > Messaging.

4. יוצרים קמפיין.

   • אם זו ההודעה הראשונה שלכם:

     1. לוחצים על יצירת הקמפיין הראשון.

     2. בוחרים באפשרות הודעות של התראות ב-Firebase ולוחצים על יצירה.

   • אם כבר יצרתם קמפיינים:

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

     2. לוחצים על התראות.

5. מזינים את הטקסט של ההודעה.

6. בחלונית השמאלית, לוחצים על שליחת הודעת בדיקה.

7. בשדה הוספה של מזהה התקנה של Firebase או אסימון רישום של FCM, מזינים את אסימון הרישום.

8. בוחרים באפשרות בדיקה.

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

כדי לקבל תובנות לגבי מסירת ההודעות לאפליקציה, נכנסים ללוח הבקרה DevOps & Engagement (DevOps ומעורבות) > Messaging (העברת הודעות) > Reports (דוחות) במסוף Firebase. בלוח הבקרה הזה מתועד מספר ההודעות שנשלחו ונפתחו במכשירי Apple ו-Android, לצד נתונים לגבי 'חשיפות' (התראות שהמשתמשים ראו) באפליקציות ל-Android.

השלבים הבאים

אחרי שתסיימו את שלבי ההגדרה, תוכלו לבחור אחת מהאפשרויות הבאות כדי להמשיך להשתמש ב-FCM בפלטפורמות של אפל:

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