הוספת התראות לאפליקציה ל-iOS

1. מבוא

העדכון האחרון: 2020-1-6

‫Firebase Cloud Messaging (FCM) הוא פתרון להעברת הודעות בין פלטפורמות שמאפשר לכם לשלוח הודעות בצורה מהימנה ללא עלות.

באמצעות FCM, אפשר להודיע לאפליקציית לקוח שיש אימייל חדש או נתונים אחרים שזמינים לסנכרון. אתם יכולים לשלוח הודעות התראה כדי לעודד את המשתמשים לחזור לאפליקציה ולשמר אותם. בתרחישי שימוש כמו העברת הודעות מיידיות, הודעה יכולה להעביר מטען ייעודי (payload) של עד 4KB לאפליקציית לקוח.

איך זה עובד

הטמעה של FCM כוללת שני רכיבים עיקריים לשליחה ולקבלה:

1. סביבה מהימנה כמו Cloud Functions for Firebase או שרת אפליקציות שבה אפשר ליצור, לטרגט ולשלוח הודעות.
2. אפליקציית לקוח ל-iOS, ל-Android או לאינטרנט (JavaScript) שמקבלת הודעות דרך שירות התעבורה הספציפי לפלטפורמה המתאימה.

סקירה כללית על הארכיטקטורה של FCM

‫FCM מסתמך על קבוצת הרכיבים הבאה שיוצרים, מעבירים ומקבלים הודעות:

1. כלים ליצירה או לפיתוח של בקשות להודעות. הכלי ליצירת התראות מספק אפשרות מבוססת-GUI ליצירת בקשות להתראות. כדי להשיג אוטומציה מלאה ותמיכה בכל סוגי ההודעות, צריך ליצור בקשות להודעות בסביבת שרת מהימנה שתומכת ב-Firebase Admin SDK או בפרוטוקולי השרת של FCM. הסביבה הזו יכולה להיות Cloud Functions for Firebase,‏ Google App Engine או שרת האפליקציות שלכם.
2. הקצה העורפי של FCM, שמקבל בקשות להודעות (בין היתר), מבצע פיצול של הודעות באמצעות נושאים ויוצר מטא-נתונים של הודעות, כמו מזהה ההודעה.
3. שכבת תעבורה ברמת הפלטפורמה, שמנתבת את ההודעה למכשיר היעד, מטפלת בשליחת ההודעה ומחילת הגדרה ספציפית לפלטפורמה במקרים המתאימים. שכבת התעבורה הזו כוללת:

• שכבת התעבורה של Android‏ (ATL) למכשירי Android עם Google Play Services
• שירות ההתראות של Apple‏ (APNs) למכשירי iOS
• פרוטוקול של התראות מאפליקציות אינטרנט

הערה: שכבות התעבורה ברמת הפלטפורמה נמצאות מחוץ לשירות FCM. הודעות FCM שמנותבות לשכבת תעבורה ברמת הפלטפורמה עשויות להיות כפופות לתנאים ספציפיים לאותה פלטפורמה ולא לתנאים ולהגבלות של FCM. ניתוב הודעות ב-Android באמצעות ATL כפוף לתנאים ולהגבלות של Google APIs.

4. ‫FCM SDK במכשיר של המשתמש, שבו ההתראה מוצגת או שההודעה מטופלת בהתאם למצב החזית/הרקע של האפליקציה ולכל לוגיקת אפליקציה רלוונטית.

מה תפַתחו

ב-codelab הזה תוסיפו הודעת פוש לאפליקציית iOS לדוגמה באמצעות FCM.

מה תלמדו

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

מה צריך

• ‫Xcode 11.0 ואילך
• ‫CocoaPods 1.9.0 ואילך
• חשבון Apple Developer
• מכשיר iOS פיזי להרצת האפליקציה
• ידע בסיסי ב-Swift

2. תהליך ההגדרה

הורדת קוד לדוגמה

ב-codelab הזה תבנו אפליקציית בדיקה משלכם, אבל אם אתם רוצים לראות ולהריץ את אפליקציית הדוגמה הקיימת, אתם יכולים להוריד את קוד הדוגמה למדריך למתחילים.

יש שתי דרכים לקבל את הדוגמה:

• משכפלים את מאגר Git:

$ git clone https://github.com/firebase/quickstart-ios.git

• מורידים את קובץ ה-ZIP:

אם מורידים את המקור כקובץ ZIP, אחרי פתיחת הדחיסה מקבלים תיקיית בסיס quickstart-ios.

הורדת קוד המקור

יצירת אפליקציה חדשה

כדי ליצור אפליקציית בדיקה משלכם, מבצעים את השלבים הבאים (השלבים הבאים מתייחסים ל-XCode 12.3):

1. פותחים את XCode ובוחרים באפשרות Create a new Xcode project (יצירת פרויקט חדש ב-Xcode).
2. בוחרים באפשרות אפליקציה ולוחצים על הבא.

3. מזינים את שם המוצר (לדוגמה, MessagingExample)
4. בוחרים באפשרות Team (צוות) (אם לא יצרתם צוות, צריך להגדיר אותו בחשבון Apple Developer).
5. מזינים את מזהה הארגון (למשל, com.your-name)
6. מזינים את מזהה החבילה (למשל, ‫com.your-name.MessagingExample, הוא צריך להיות ייחודי בין כל האפליקציות ל-iOS).
7. בתפריט הנפתח ממשק, בוחרים באפשרות Storyboard (תסריט מצויר).
8. בתפריט הנפתח מחזור חיים בוחרים באפשרות UIKit App Delegate.
9. בוחרים באפשרות Swift בקטע שפה.
10. לוחצים על הבא.

תצטרכו את מזהה החבילה כשתיצרו מפתח APN ותירשמו לאפליקציה בפרויקט Firebase.

3. הגדרת APN

יצירת מפתח האימות

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

כדי ליצור מפתח אימות:

1. בחשבון הפיתוח, עוברים אל Certificates, Identifiers & Profiles (אישורים, מזהים ופרופילים) ואז אל Keys (מפתחות).

2. לוחצים על לחצן ההוספה (+) בפינה השמאלית העליונה.

3. מזינים תיאור למפתח האימות של APNs
4. בקטע Key Services (שירותים מרכזיים), מסמנים את התיבה APNs ולוחצים על Continue (המשך).

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

יצירת מזהה אפליקציה

מזהה אפליקציה הוא מזהה ייחודי של אפליקציה. על פי המוסכמה, הוא מיוצג על ידי דומיין הפוך.

1. עוברים אל Apple Developer Member Center ונכנסים לחשבון.
2. עוברים אל Certificates, Identifiers and Profiles (אישורים, מזהים ופרופילים).
3. עוברים אל מזהים.
4. לוחצים על הלחצן + כדי ליצור מזהה אפליקציה חדש.
5. לוחצים על לחצן הבחירה מזהי אפליקציות ואז על המשך.

6. בוחרים באפשרות אפליקציה ולוחצים על המשך.

7. כדי ליצור את מזהה האפליקציה החדש:
8. מזינים שם למזהה האפליקציה.
9. מזינים מזהה צוות. הערך הזה צריך להיות זהה למזהה הצוות בכרטיסייה 'חברות'.
10. בקטע App ID Suffix (סיומת של מזהה האפליקציה), בוחרים באפשרות Explicit App ID (מזהה אפליקציה מפורש) ומזינים את מזהה החבילה.
11. בקטע App Services (שירותי אפליקציות), מוודאים שהתיבה Push Notifications (התראות פוש) מסומנת.
12. לוחצים על המשך ומוודאים שהפרטים שהזנתם נכונים:
13. הערך של Identifier צריך להיות זהה לצירוף של הערכים של Team ID ושל Bundle ID
14. התראות בדחיפה צריכות להיות ניתנות להגדרה
15. לוחצים על Register (הרשמה) כדי ליצור את מזהה האפליקציה.

יצירת הפרופיל

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

1. עוברים אל Apple Developer Member Center ונכנסים לחשבון.
2. עוברים אל Certificates, Identifiers and Profiles (אישורים, מזהים ופרופילים).
3. בתפריט הנפתח בפינה הימנית העליונה, בוחרים באפשרות iOS, ‏ tvOS, ‏ watchOS אם היא לא נבחרה כבר, ואז עוברים אל פרופילים.
4. לוחצים על הלחצן + כדי ליצור פרופיל חדש.
5. בוחרים באפשרות פיתוח אפליקציות ל-iOS כסוג פרופיל ההקצאה ולוחצים על המשך.

6. בתפריט הנפתח, בוחרים את מזהה האפליקציה שרוצים להשתמש בו ולוחצים על המשך.
7. בוחרים את אישור הפיתוח ל-iOS של מזהה האפליקציה שבחרתם בשלב הקודם ולוחצים על המשך.
8. בוחרים את מכשירי ה-iOS שרוצים לכלול בפרופיל ההקצאה ולוחצים על המשך. חשוב לבחור את כל המכשירים שבהם רוצים להשתמש לבדיקה.
9. מזינים שם לפרופיל ההקצאה (למשל MessagingExampleProfile) ולוחצים על Generate (יצירה).

10. לוחצים על הורדה כדי לשמור את פרופיל ההקצאה ב-Mac.

11. לוחצים לחיצה כפולה על קובץ פרופיל ההקצאה כדי להתקין אותו.

4. הוספת Firebase לפרויקט iOS

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

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

1. במסוף Firebase, לוחצים על הוספת פרויקט, ואז בוחרים או מזינים שם פרויקט.

אם יש לכם פרויקט קיים ב-Google Cloud Platform‏ (GCP), תוכלו לבחור את הפרויקט מהתפריט הנפתח כדי להוסיף לו משאבי Firebase.

2. (אופציונלי) אם אתם יוצרים פרויקט חדש, אתם יכולים לערוך את מזהה הפרויקט.

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

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

3. לוחצים על המשך.
4. הגדרתם את Google Analytics לפרויקט, כך שתוכלו ליהנות מחוויה אופטימלית בשימוש בכל אחד מהמוצרים הבאים של Firebase:

• Firebase Crashlytics
• Firebase Predictions
• העברת הודעות בענן ב-Firebase
• העברת הודעות בתוך האפליקציה ב-Firebase
• הגדרת תצורה מרחוק ב-Firebase
• Firebase A/B Testing

כשמוצגת בקשה, בוחרים להשתמש בחשבון Google Analytics קיים או ליצור חשבון חדש. אם בוחרים ליצור חשבון חדש, בוחרים את מיקום הדיווח ב-Analytics, ואז מאשרים את הגדרות שיתוף הנתונים ואת התנאים של Google Analytics עבור הפרויקט.

5. לוחצים על יצירת פרויקט (או על הוספת Firebase אם משתמשים בפרויקט קיים ב-GCP).

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

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

אחרי שיש לכם פרויקט Firebase, אתם יכולים להוסיף אליו את אפליקציית iOS.

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

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

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

3. מזינים את מזהה החבילה של האפליקציה בשדה מזהה החבילה ל-iOS.
4. (אופציונלי) מזינים פרטים נוספים על האפליקציה: שם חיבה לאפליקציה ומזהה App Store.
5. לוחצים על רישום האפליקציה.

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

1. לוחצים על הורדה של GoogleService-Info.plist כדי לקבל את קובץ ההגדרות של Firebase ל-iOS ‏ (GoogleService-Info.plist).
2. מעבירים את קובץ ההגדרות לרמה הבסיסית (root) של פרויקט Xcode. אם מוצגת בקשה, בוחרים להוסיף את קובץ ההגדרות לכל יעדי ההעברה.

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

סוגרים את XCode.

מוסיפים את Firebase SDKs לאפליקציה

מומלץ להשתמש ב-CocoaPods כדי להתקין את ספריות Firebase. עם זאת, אם אתם לא רוצים להשתמש ב-CocoaPods, אתם יכולים לשלב את מסגרות ה-SDK ישירות או להשתמש בגרסת הבטא של Swift Package Manager.

1. צריך ליצור Podfile אם אין עדיין. אם אתם משתמשים בדוגמה להפעלה מהירה, פרויקט Xcode וקובץ Podfile (עם pods) כבר קיימים.

$ cd MessagingExample
$ pod init

2. מוסיפים ל-Podfile את ה-pods של Firebase שרוצים להשתמש בהם באפליקציה.

אתם יכולים להוסיף לאפליקציית iOS כל אחד ממוצרי Firebase הנתמכים.

בדוגמה למתחילים, נוספו Google Analytics ו-Firebase Cloud Messaging SDKs.

# Add the Firebase pod for Google Analytics
pod 'Firebase/Analytics'

# Add the pod for Firebase Cloud Messaging
pod 'Firebase/Messaging'

3. מתקינים את ה-pods ואז פותחים את הקובץ .xcworkspace כדי לראות את הפרויקט ב-Xcode:

$ pod install

4. פותחים את MessagingExample.xcworkspace ולוחצים על הבא במסוף Firebase.

הפעלת Firebase באפליקציה

תצטרכו להוסיף קוד אתחול של Firebase לאפליקציה.

מייבאים את מודול Firebase ומגדירים מופע משותף (במדריך למתחילים, מודול Firebase כבר מיובא).

1. מייבאים את מודול Firebase ב-UIApplicationDelegate:

AppDelegate.swift

import UIKit
import Firebase // Add this line

2. מגדירים מופע משותף של FirebaseApp, בדרך כלל בשיטה application:didFinishLaunchingWithOptions: של האפליקציה:

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  FirebaseApp.configure() // Add this line
  return true
}

3. לוחצים על הבא במסוף Firebase.
4. ערכות ה-SDK של Firebase מתווספות לאפליקציה. לוחצים על המשך למסוף.

5. הגדרת לקוח FCM

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

מעלים את מפתח האימות של APNs ל-Firebase.

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

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

3. מדפדפים למיקום שבו שמרתם את המפתח, בוחרים אותו ולוחצים על פתיחה. מוסיפים את מזהה המפתח (שזמין ב-Certificates, Identifiers & Profiles ב-Apple Developer Member Center) ולוחצים על Upload (העלאה).

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

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

בדוגמה של ההפעלה המהירה, registerForRemoteNotifications כבר נוסף.

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  FirebaseApp.configure()
  // [START register for remote notifications]
  if #available(iOS 10.0, *) {
    // For iOS 10 display notification (sent via APNS)
    UNUserNotificationCenter.current().delegate = self
        
    let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
    UNUserNotificationCenter.current().requestAuthorization(options: authOptions, completionHandler: {_, _ in })
  } else {
    let settings: UIUserNotificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
    application.registerUserNotificationSettings(settings)
  }

  application.registerForRemoteNotifications()
  // [END register for remote notifications]
  return true
}

מקצים את נכס הנציג של UNUserNotificationCenter על ידי הוספת השורות האלה בסוף הקובץ AppDelegate.swift.

AppDelegate.swift

@available(iOS 10, *)
extension AppDelegate : UNUserNotificationCenterDelegate {

  // Receive displayed notifications for iOS 10 devices.
  func userNotificationCenter(_ center: UNUserNotificationCenter,
                              willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    let userInfo = notification.request.content.userInfo

    // Print full message.
    print(userInfo)

    // Change this to your preferred presentation option
    completionHandler([[.alert, .sound]])
  }

  func userNotificationCenter(_ center: UNUserNotificationCenter,
                              didReceive response: UNNotificationResponse,
                              withCompletionHandler completionHandler: @escaping () -> Void) {
    let userInfo = response.notification.request.content.userInfo

    // Print full message.
    print(userInfo)

    completionHandler()
  }
}

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

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

AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  FirebaseApp.configure()
  Messaging.messaging().delegate = self // Add this line
  // [START register for remote notifications]
  if #available(iOS 10.0, *) {
    // For iOS 10 display notification (sent via APNS)
    UNUserNotificationCenter.current().delegate = self
        
    let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
    UNUserNotificationCenter.current().requestAuthorization(options: authOptions, completionHandler: {_, _ in })
  } else {
    let settings: UIUserNotificationSettings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
    application.registerUserNotificationSettings(settings)
  }

  application.registerForRemoteNotifications()
  // [END register for remote notifications]
  return true
}

מקצים את נכס הנציג של FIRMessaging על ידי הוספת השורות האלה בסוף הקובץ AppDelegate.swift.

AppDelegate.swift

extension AppDelegate : MessagingDelegate {
  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)
  }
}

הוספת יכולות

הוספתם את היכולת 'התראות פוש' בקטע 'יצירת מזהה אפליקציה', אבל אתם צריכים להוסיף את היכולת הזו גם ב-XCode באמצעות השלבים הבאים (השלבים שבהמשך מתייחסים ל-XCode 12.3):

1. לוחצים על שם הפרויקט באזור הניווט.
2. לוחצים על חתימה ויכולות.
3. לוחצים על + יכולת.

4. לוחצים לחיצה כפולה על מצבי רקע.
5. לוחצים שוב על + יכולת.
6. לוחצים לחיצה כפולה על התראות בדחיפה.
7. בקטע Background Modes (מצבי רקע), מסמנים את האפשרות Remote notifications (התראות מרחוק).

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

כדי לשלוח הודעת בדיקה:

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

3. מוודאים שהאפליקציה פועלת ברקע במכשיר.
4. פותחים את כלי ההתראות ולוחצים על התראה חדשה.
5. מזינים את הטקסט של ההודעה.
6. בוחרים באפשרות שליחת הודעת בדיקה.
7. בשדה Add an FCM registration token (הוספת אסימון רישום של FCM), מזינים את אסימון הרישום שהתקבל בשלב 2.
8. לוחצים על בדיקה.

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

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

7. מזל טוב

מזל טוב, שלחת הודעת בדיקה בהצלחה!

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

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

מה השלב הבא?

כדאי לעיין בכמה מה-codelabs האלה.

• ‫Advanced Android in Kotlin 01.2:Android Firebase Cloud Messaging

קריאה נוספת

• המסמך הרשמי בנושא העברת הודעות בענן ב-Firebase