שליחה של הודעת בדיקה לאפליקציה ברקע של 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, כשפרויקט האפליקציה פתוח, עוברים אל קובץ > הוספת חבילות.
2. כשמופיעה בקשה, מוסיפים את המאגר של Firebase SDK לפלטפורמות של Apple:

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

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

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

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

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

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

3. עוברים למיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על פתיחה. מוסיפים את מזהה המפתח (זמין ב מרכז החברים של 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, עליכם ליצור נציג אפליקציה ולצרף אותו למבנה 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. ה-SDK של FCM מאחזר אסימון חדש או קיים במהלך ההפעלה הראשונית של האפליקציה, וגם בכל פעם שהאסימון מתעדכן או מבוטל. בכל המקרים, ה-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. לחלופין, בכרטיסייה Campaigns (קמפיינים), בוחרים באפשרות New campaign (קמפיין חדש) ואז באפשרות Notifications (התראות).

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

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

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

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

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

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

השלבים הבאים

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

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