שליחה של הודעת בדיקה לאפליקציה ברקע של Apple

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

הוספת Firebase לפרויקט ב-Apple

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

דרישות מוקדמות

• מתקינים את האפליקציות הבאות:

  • Xcode 15.2 ואילך

• ודאו שהפרויקט עומד בדרישות הבאות:

  • הפרויקט צריך לטרגט לגרסאות הפלטפורמה הבאות ואילך:
    • iOS 13
    • macOS 10.15
    • tvOS 13
    • WatchOS 7

• מגדירים מכשיר פיזי של Apple כדי להריץ את האפליקציה, ומבצעים את הפעולות הבאות:

  • מקבלים מפתח אימות של התראות Apple לחשבון הפיתוח שלכם ב-Apple.
  • מפעילים את התראות הדחיפה ב-XCode בקטע אפליקציה > יכולות.

• נכנסים ל-Firebase באמצעות חשבון Google.

אם עדיין אין לכם פרויקט Xcode ואתם רק רוצים לנסות מוצר של Firebase, תוכלו להוריד אחת מהדוגמאות למתחילים.

יצירת פרויקט Firebase

לפני שמוסיפים את Firebase לאפליקציה ל-Apple, צריך ליצור פרויקט Firebase כדי לקשר אותו לאפליקציה. מידע נוסף על פרויקטים ב-Firebase זמין במאמר הסבר על פרויקטים ב-Firebase.

רישום האפליקציה ב-Firebase

כדי להשתמש ב-Firebase באפליקציה ל-Apple, צריך לרשום את האפליקציה לפרויקט ב-Firebase. לעיתים קרובות, רישום האפליקציה נקרא 'הוספת' האפליקציה לפרויקט.

1. נכנסים אל מסוף Firebase.

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

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

3. מזינים את מזהה החבילה של האפליקציה בשדה bundle ID.

   מהו מזהה חבילת מודעות ואיפה הוא נמצא?

   • מזהה חבילה מזהה באופן ייחודי אפליקציה בסביבה העסקית של Apple.

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

     הערך בשדה Bundle Identifier הוא מזהה החבילה (לדוגמה, com.yourcompany.yourproject).

   • חשוב לזכור שהערך של מזהה החבילה תלוי אותיות רישיות (case-sensitive), ולא ניתן לשנות אותו באפליקציית Firebase הזו אחרי שהיא רשומה בפרויקט Firebase.

4. (אופציונלי) מזינים פרטים נוספים של האפליקציה: הכינוי ומזהה האפליקציה ב-App Store.

   איך הכינוי של האפליקציה ומזהה App Store משמשים ב-Firebase?

   • כינוי האפליקציה: מזהה פנימי ונוח שגלוי רק לכם במסוף Firebase

   • מזהה App Store: Firebase Dynamic Links משתמש במזהה הזה כדי לעביר משתמשים לדף של האפליקציה ב-App Store, ו-Google Analytics משתמש בו כדי לייבא אירועי המרה אל Google Ads. אם לאפליקציה עדיין אין מזהה App Store, תוכלו להוסיף את המזהה מאוחר יותר בהגדרות הפרויקט.

5. לוחצים על רישום האפליקציה.

הוספת קובץ תצורה של Firebase

1. לוחצים על Download GoogleService-Info.plist כדי לקבל את קובץ התצורה של Firebase לפלטפורמות Apple (GoogleService-Info.plist).

   מה צריך לדעת על קובץ התצורה הזה?

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

   • תמיד תוכלו להוריד מחדש את קובץ התצורה של Firebase.

   • מוודאים שלא מצורפים תווים נוספים לשם של קובץ התצורה, למשל (2).

2. מעבירים את קובץ התצורה לתיקיית השורש של פרויקט Xcode. אם מופיעה בקשה, בוחרים להוסיף את קובץ התצורה לכל היעדים.

אם יש לכם כמה מזהי חבילות בפרויקט, עליכם לשייך כל מזהה חבילה לאפליקציה רשומה במסוף Firebase כדי שלכל אפליקציה יהיה קובץ GoogleService-Info.plist משלה.

הוספת ערכות SDK של Firebase לאפליקציה

שימוש ב-Swift Package Manager כדי להתקין ולנהל יחסי תלות ב-Firebase.

1. ב-Xcode, כשפרויקט האפליקציה פתוח, עוברים אל File > Add Packages (קובץ > הוספת חבילות).
2. כשמופיעה בקשה, מוסיפים את מאגר ה-SDK של מוצרי הפלטפורמה של Firebase של Apple:

  https://github.com/firebase/firebase-ios-sdk.git

3. בוחרים את הספרייה Firebase Cloud Messaging.
4. מוסיפים את הדגל -ObjC לקטע סימונים של מקשר אחר בהגדרות ה-build של היעד.
5. כדי ליהנות מחוויית שימוש אופטימלית ב-Firebase Cloud Messaging, מומלץ להפעיל את Google Analytics בפרויקט Firebase ולהוסיף את Firebase SDK for Google Analytics לאפליקציה. אפשר לבחור בספרייה ללא איסוף של מזהי IDFA או עם איסוף של מזהי IDFA.
6. בסיום, Xcode יתחיל לפתור את הבעיה ותוריד את יחסי התלות באופן אוטומטי ברקע.

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

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

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

2. בקטע APNs authentication key בקטע iOS app configuration, לוחצים על הלחצן Upload.

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

איך מפעילים את Firebase באפליקציה

צריך להוסיף לאפליקציה קוד אתחול של Firebase. מייבאים את מודול Firebase ומגדירים מכונה משותפת כפי שמוצג:

1. מייבאים את המודול FirebaseCore ב-UIApplicationDelegate, וגם את כל המודולים האחרים של Firebase שבהם משתמש הנציג של האפליקציה. לדוגמה, כדי להשתמש ב-Cloud Firestore וב-Authentication:

   SwiftUI

   import SwiftUI
   import FirebaseCore
   import FirebaseFirestore
   import FirebaseAuth
   // ...
         

   Swift

   import FirebaseCore
   import FirebaseFirestore
   import FirebaseAuth
   // ...
         

   Objective-C

   @import FirebaseCore;
   @import FirebaseFirestore;
   @import FirebaseAuth;
   // ...
         

2. מגדירים מופע משותף של FirebaseApp בשיטה application(_:didFinishLaunchingWithOptions:) של הנציג של האפליקציה:

   SwiftUI

   // Use Firebase library to configure APIs
   FirebaseApp.configure()

   Swift

   // Use Firebase library to configure APIs
   FirebaseApp.configure()

   Objective-C

   // Use Firebase library to configure APIs
   [FIRApp configure];

3. אם אתם משתמשים ב-SwiftUI, עליכם ליצור נציג מורשה לאפליקציה ולצרף אותו ל-build של App דרך UIApplicationDelegateAdaptor או באמצעות NSApplicationDelegateAdaptor. צריך גם להשבית את החלפת הקוד של נציג האפליקציה. מידע נוסף זמין בהוראות ל-SwiftUI.

   SwiftUI

   @main
   struct YourApp: App {
     // register app delegate for Firebase setup
     @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
   
     var body: some Scene {
       WindowGroup {
         NavigationView {
           ContentView()
         }
       }
     }
   }
         

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

UNUserNotificationCenter.current().delegate = self

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

application.registerForRemoteNotifications()
AppDelegate.swift

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

[application registerForRemoteNotifications];
AppDelegate.m

גישה לאסימון הרישום

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

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

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

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

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

איך מגדירים את המשתמש שאחראי להעברת הודעות

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

Messaging.messaging().delegate = self

[FIRMessaging messaging].delegate = self;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. במסוף Firebase, פותחים את הדף Messaging.

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

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

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

6. כותבים את הטקסט של ההודעה. כל שאר השדות הם אופציונליים.

7. בוחרים באפשרות שליחת הודעת בדיקה בחלונית השמאלית.

8. בשדה Add an FCM registration token, מזינים את אסימון ההרשמה שקיבלתם בקטע הקודם במדריך הזה.

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

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

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

השלבים הבאים

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

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