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

בחירת פלטפורמה: ‫iOS+‎ Android Web Flutter Unity C++‎


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

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

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

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

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

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

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

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

  1. במסוף Firebase, עוברים אל הגדרות > כללי. ואז לוחצים על הכרטיסייה Cloud Messaging.
  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()

Objective-C

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

[application registerForRemoteNotifications];

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

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

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

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

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

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

FirebaseMessagingInstallationIdEnabled = YES

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

הטמעה של השיטה didReceiveRegistration

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

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

Swift

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)
  }
}

Objective-C

- (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 כשמפעילים את האפליקציה:

Swift

// 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.")
}

Objective-C

// 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.");
}];

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

אם השבתתם את החלפת השיטות או שאתם מפתחים אפליקציית SwiftUI, אתם צריכים למפות באופן מפורש את טוקן ה-APNs למזהי ההתקנה של Firebase‏ (FID). מטמיעים את השיטה 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;
}

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

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

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

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

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

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

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

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

Swift

Messaging.messaging().delegate = self

Objective-C

[FIRMessaging messaging].delegate = self;

שליפת טוקן הרישום הנוכחי

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

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

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

Swift

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)")
  }
}

Objective-C

[[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);
  }
}];

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

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

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

Swift

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.
}

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.
}

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

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

מניעת אתחול אוטומטי

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

FirebaseMessagingAutoInitEnabled = NO

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

Swift

Messaging.messaging().autoInitEnabled = true

Objective-C

[FIRMessaging messaging].autoInitEnabled = YES;

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

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

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

כדי להוסיף תוסף שירות, מבצעים את משימות ההגדרה הנדרשות לשינוי והצגה של התראות ב-APNs, ואז מוסיפים את ה-API של העזר לתוסף FCM ב-NotificationService.m. במילים אחרות, במקום להשלים את השיחה החוזרת באמצעות 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. בשדה עם התווית Add a Firebase Installation ID or FCM registration token (הוספת מזהה התקנה של Firebase או טוקן רישום), מזינים את טוקן הרישום.

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

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

כדי לקבל תובנות לגבי מסירת הודעות לאפליקציה, עוברים אל לוח הבקרה של דוחות �Firebase במרכז הבקרה הזה מתועד מספר ההודעות שנשלחו ונפתחו במכשירי Apple ובמכשירי Android, לצד נתונים לגבי 'חשיפות' (התראות שהמשתמשים ראו) באפליקציות ל-Android.

השלבים הבאים

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