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

בחירת פלטפורמה:

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

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

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

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

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

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

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

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

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

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

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

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

Swift

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
MigratedSnippets.swift

Objective-C

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

[application registerForRemoteNotifications];ObjCMigratedSnippets.m

צריך להקצות את המאפיין delegate של UNUserNotificationCenter ואת המאפיין delegate של FIRMessaging. לדוגמה, באפליקציית iOS, מקצים אותו ב-method‏ applicationWillFinishLaunchingWithOptions: או applicationDidFinishLaunchingWithOptions: של נציג האפליקציה.

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

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

בדומה לאופן שבו פלטפורמות של Apple בדרך כלל מספקות טוקן מכשיר של APNs בהפעלת האפליקציה, FCM מספק טוקן רישום באמצעות השיטה FIRMessagingDelegate's messaging:didReceiveRegistrationToken:. ה-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:. השיטה הזו נקראת בדרך כלל פעם אחת בכל הפעלה של האפליקציה עם טוקן רישום. כשקוראים ל-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.
}MigratedSnippets.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.
}ObjCMigratedSnippets.m

אפשרות אחרת היא להאזין לאירוע 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];

}
...

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

מתקינים את האפליקציה במכשיר היעד ומריצים אותה. במכשירי Apple, מאשרים את הבקשה להרשאה לקבל התראות מרחוק.
בודקים שהאפליקציה פועלת ברקע במכשיר.
במסוף Firebase, פותחים את הדף הודעות.
אם זו ההודעה הראשונה שלכם, בוחרים באפשרות יצירת הקמפיין הראשון.
1. בוחרים באפשרות הודעות התראה של Firebase ולוחצים על יצירה.
אפשרות אחרת: בכרטיסייה קמפיינים, לוחצים על קמפיין חדש ואז על התראות.
מזינים את הטקסט של ההודעה.
בחלונית השמאלית, לוחצים על שליחת הודעת בדיקה.
בשדה עם התווית Add an FCM registration token (הוספת טוקן רישום של FCM), מזינים את טוקן הרישום.
בוחרים באפשרות בדיקה.

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

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

השלבים הבאים

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

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

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

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

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

Swift

Objective-C

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

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

Swift

Objective-C

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

Swift

Objective-C

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

Swift

Objective-C

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

Swift

Objective-C

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

Swift

Objective-C

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

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

השלבים הבאים

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