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

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

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

iOS+‎

Method swizzling

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

Android

Google Play Services

FCM לקוחות צריכים מכשירים עם Android בגרסה 7.0 ומעלה שמותקנת בהם גם Google Play Services, או אמולטור עם Android בגרסה 7.0 עם Google APIs. חשוב לזכור שאתם לא מוגבלים להפצת אפליקציות ל-Android דרך חנות Google Play.

באפליקציות שמסתמכות על Play Services SDK, תמיד צריך לבדוק אם במכשיר יש קובץ APK תואם של Google Play Services לפני שניגשים לתכונות של Google Play Services. מומלץ לעשות את זה בשני מקומות: ב-method onCreate() של הפעילות הראשית, וב-method onResume() שלה. הבדיקה ב-onCreate() מוודאת שאי אפשר להשתמש באפליקציה בלי שהבדיקה תעבור בהצלחה. הבדיקה ב-onResume() מוודאת שאם המשתמש חוזר לאפליקציה הפועלת באמצעים אחרים, כמו באמצעות הכפתור "הקודם", הבדיקה עדיין מתבצעת.

אם במכשיר אין גרסה תואמת של Google Play Services, האפליקציה יכולה להפעיל את GoogleApiAvailability.makeGooglePlayServicesAvailable() כדי לאפשר למשתמשים להוריד את Google Play Services מחנות Play.

אינטרנט

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

ממשק האינטרנט של FCM משתמש בפרטי כניסה לאינטרנט שנקראים "מפתחות זיהוי וולונטרי של שרת אפליקציות" (VAPID), כדי לאשר בקשות שליחה לשירותי התראות נתמכים באינטרנט. כדי לרשום את האפליקציה להתראות, צריך לשייך זוג מפתחות לפרויקט ב-Firebase. אפשר ליצור זוג מפתחות חדש או לייבא זוג מפתחות קיים דרך מסוף Firebase.

התקנת הפלאגין FCM

1. אם עוד לא עשיתם זאת, מתקינים ומפעילים את הפלאגינים של Firebase ל-Flutter.

2. מהרמה הבסיסית (root) של פרויקט Flutter, מריצים את הפקודה הבאה כדי להתקין את הפלאגין:

   flutter pub add firebase_messaging
   

3. בסיום, בונים מחדש את אפליקציית Flutter:

   flutter run
   

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

כדי לשלוח הודעה למכשיר, צריך לרשום את המכשיר ב-FCM באמצעות register(). אם לא ניתנה הרשאה לשליחת התראות, השיטה הזו תבקש מהמשתמש הרשאות לשליחת התראות. אחרת, הוא מחזיר את ה-FID דרך onRegistered אם הפעולה מצליחה, או דוחה את ה-future בגלל שגיאה.

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, make sure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

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

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

כדי להפעיל את הרישום של מופע האפליקציה ב-FCM באמצעות מזהה ההתקנה (FID) של Firebase, קודם צריך להפעיל את מזהי ההתקנה בהגדרות של האפליקציה לפלטפורמות Android ו-Apple (לא נדרשת הגדרת הסכמה סטטית באינטרנט):

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

<key>FirebaseMessagingInstallationIdEnabled</key>
<true/>

הרשמה לסטרימינג של onRegistered

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

בפלטפורמות Android ו-Apple, ‏ FCM רושם אוטומטית את מופע האפליקציה בזמן ההפעלה כשההפעלה האוטומטית מופעלת (ברירת המחדל). עם זאת, צריך קריאה מפורשת ל-register():

• באתר. אפשר גם להעביר את vapidKey ו-serviceWorkerScriptPath.
• בפלטפורמות של Android ו-Apple אם ההפעלה האוטומטית מושבתת או אחרי קריאה ל-unregister(). אפשר גם להפעיל את register() בכל שלב כדי להפעיל את onRegistered עם מזהה ה-FID שכבר רשום.

תמיד צריך להירשם ל-onRegistered לפני שקוראים ל-register() כדי שהמאזין יהיה פעיל כשאירוע הרישום מופעל:

final messaging = FirebaseMessaging.instance;

messaging.onRegistered
    .listen((String installationId) {
      // TODO: Send the Firebase Installation ID (FID) to your application server.
    })
    .onError((err) {
      // Error getting Firebase Installation ID.
    });

// Required on Web, and on Android/Apple if auto-initialization is disabled.
await messaging.register(
  // Optional on Web (ignored on Android and Apple platforms)
  vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu",
);

הסטרימינג של onRegistered פולט את ה-FID בתרחישים הבאים:

1. באופן אוטומטי בהפעלה הראשונית של האפליקציה ובסנכרון שגרתי בפלטפורמות של Android ו-Apple, כשההפעלה האוטומטית מופעלת.
2. בכל פעם ששיחה ידנית register() מסתיימת (גם אם מופע האפליקציה כבר רשום, onRegistered עדיין מופק ה-FID שכבר רשום).
3. בכל פעם שמזוהה שינוי במזהה ההתקנה ב-Firebase והאפליקציה נרשמת מחדש ב-FCM, או באינטרנט כשמופעל אירוע pushsubscriptionchange.

אחרי שמקבלים את מזהה ההתקנה של Firebase‏ (FID), שולחים אותו לשרת האפליקציה ושומרים אותו בשיטה המועדפת.

גישה לטוקן הרישום (הוצא משימוש)

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

בפלטפורמות אינטרנט, מעבירים את המפתח הציבורי של VAPID אל getToken():

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

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

FirebaseMessaging.instance.onTokenRefresh
    .listen((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.
    })
    .onError((err) {
      // Error getting token.
    });

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

כשנוצר רישום של FCM, הספרייה מעלה את המזהה ואת נתוני ההגדרות ל-Firebase. אם אתם מעדיפים למנוע רישום אוטומטי, השביתו את ההפעלה האוטומטית בזמן ה-build.

כשההפעלה האוטומטית מושבתת, אפשר לרשום באופן מפורש את מופע האפליקציה בזמן הריצה על ידי קריאה ל-register() (חשוב להירשם קודם ל-onRegistered כדי לקבל את מזהה ההתקנה של Firebase):

await FirebaseMessaging.instance.register();

iOS

ב-iOS, מוסיפים ערך מטא-נתונים ל-Info.plist:

FirebaseMessagingAutoInitEnabled = NO

Android

ב-Android, משביתים את איסוף הנתונים של Analytics ואתחול אוטומטי של FCM (צריך להשבית את שניהם) על ידי הוספת ערכי המטא-נתונים האלה לקובץ AndroidManifest.xml:

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

הפעלה מחדש של ההפעלה האוטומטית של FCM בזמן הריצה

כדי להפעיל הפעלה אוטומטית של מופע ספציפי של אפליקציה, קוראים ל-setAutoInitEnabled():

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

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

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

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

3. במסוף Firebase, נכנסים לקטע DevOps & Engagement (DevOps ומעורבות) > Messaging (העברת הודעות).

4. יוצרים קמפיין.

   • אם זו ההודעה הראשונה שלכם:

     1. לוחצים על יצירת הקמפיין הראשון.

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

   • אם כבר יצרתם קמפיינים:

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

     2. לוחצים על התראות.

5. מזינים את הטקסט של ההודעה.

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

7. בשדה Add a Firebase Installation ID or FCM registration token, מזינים את מזהה ההתקנה של Firebase או את אסימון הרישום.

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

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

כדי לקבל תובנות לגבי מסירת ההודעות לאפליקציה, נכנסים ללוח הבקרה DevOps & Engagement (DevOps ומעורבות) > Messaging (העברת הודעות) > Reports (דוחות) במסוף Firebase. בלוח הבקרה הזה מתועד מספר ההודעות שנשלחו ונפתחו במכשירי Apple ו-Android, לצד נתונים לגבי 'חשיפות' (התראות שהמשתמשים ראו) באפליקציות ל-Android.

אינטראקציה עם הטיפול

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

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

החבילה firebase-messaging מספקת שתי דרכים לטפל באינטראקציה הזו:

1. getInitialMessage(): אם האפליקציה נפתחת ממצב סגור, השיטה הזו מחזירה Future שמכיל RemoteMessage. אחרי השימוש, RemoteMessage יוסר.
2. ‫onMessageOpenedApp: Stream שמפרסם RemoteMessage כשהאפליקציה נפתחת ממצב רקע.

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

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

האופן שבו אתם מטפלים באינטראקציה תלוי בהגדרות שלכם. הדוגמה הקודמת היא דוגמה בסיסית לשימוש ב-StatefulWidget.

השלבים הבאים

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

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