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

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

הגדרת ה-SDK

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

לפני שמתחילים

  • מתקינים או מעדכנים את Android Studio לגרסה האחרונה.

  • צריך לוודא שהפרויקט עומד בדרישות הבאות (שימו לב: למוצרים מסוימים יכולות להיות דרישות מחמירות יותר):

    • טירגוט לרמת API 21 (Lollipop) ואילך
    • נעשה שימוש ב-Android מגרסה 5.0 ומעלה
    • נעשה שימוש ב-Jetpack (AndroidX), שכולל עמידה בדרישות הגרסה הבאות:
      • com.android.tools.build:gradle גרסה 7.3.0 ואילך
      • compileSdkVersion 28 ואילך

  • כדי להפעיל את האפליקציה, צריך להגדיר מכשיר פיזי או להשתמש באמולטור.
    לתשומת ליבכם: ערכות Firebase SDK שתלויות בשירותי Google Play צריכות להיות מותקנות במכשיר או באמולטור של Google Play Services.

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

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

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

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

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

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

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

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

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

  4. (אופציונלי) מזינים מידע נוסף על האפליקציה: הכינוי של האפליקציה וSHA-1 של אישור החתימה לניפוי באגים.

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

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

  1. מורידים את קובץ התצורה של Firebase ל-Android‏ (google-services.json) ומוסיפים אותו לאפליקציה:

    1. לוחצים על Download google-services.json כדי לקבל את קובץ התצורה של Firebase ל-Android.

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

  2. כדי לאפשר לערכות ה-SDK של Firebase לגשת לערכים בקובץ התצורה google-services.json, צריך את הפלאגין של Google services ל-Gradle (google-services).

    1. בקובץ Gradle ברמת השורש (ברמת הפרויקט) (<project>/build.gradle.kts או <project>/build.gradle), מוסיפים את הפלאגין של שירותי Google כתלייה:

      Kotlin 

      plugins {
  id("com.android.application") version "7.3.0" apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id("com.google.gms.google-services") version "4.4.2" apply false
}

      Groovy 

      plugins {
  id 'com.android.application' version '7.3.0' apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id 'com.google.gms.google-services' version '4.4.2' apply false
}

    2. בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל <project>/<app-module>/build.gradle.kts או <project>/<app-module>/build.gradle), מוסיפים את הפלאגין של שירותי Google:

      Kotlin 

      plugins {
  id("com.android.application")

  // Add the Google services Gradle plugin
  id("com.google.gms.google-services")
  // ...
}

      Groovy 

      plugins {
  id 'com.android.application'

  // Add the Google services Gradle plugin
  id 'com.google.gms.google-services'
  // ...
}

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

  1. בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל <project>/<app-module>/build.gradle.kts או <project>/<app-module>/build.gradle), מוסיפים את התלות בספרייה Firebase Cloud Messaging ל-Android. מומלץ להשתמש ב-Firebase Android BoM כדי לשלוט בגרסאות הספרייה.

    כדי ליהנות מחוויה אופטימלית עם Firebase Cloud Messaging, מומלץ להפעיל את Google Analytics בפרויקט Firebase ולהוסיף לאפליקציה את Firebase SDK for Google Analytics. 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.0"))

    // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-messaging")
    implementation("com.google.firebase:firebase-analytics")
}

    כשמשתמשים ב-Firebase Android BoM, האפליקציה תמיד תשתמש בגרסאות תואמות של ספריות Firebase ל-Android.

    (חלופה)  מוסיפים יחסי תלות לספריות של Firebase בלי להשתמש ב-BoM

    אם בוחרים לא להשתמש ב-Firebase BoM, צריך לציין את כל הגרסאות של ספריות Firebase בשורת התלות שלהן.

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

    dependencies {
    // Add the dependencies for the Firebase Cloud Messaging and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-messaging:24.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
         מחפשים מודול ספרייה ספציפי ל-Kotlin? החל מ-אוקטובר 2023 (Firebase BoM 32.5.0), מפתחי Kotlin ומפתחי Java יוכלו להסתמך על מודול הספרייה הראשי (פרטים נוספים זמינים בשאלות הנפוצות לגבי היוזמה הזו).

  2. סנכרון פרויקט Android עם קובצי Gradle.

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

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

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

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

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

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

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

כשצריך לאחזר את האסימון הנוכחי, צריך להפעיל את הפונקציה FirebaseMessaging.getInstance().getToken():

Kotlin+KTX

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

Java

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

מעקב אחר יצירת הטוקנים

קריאת החזרה (callback) של onNewToken מופעלת בכל פעם שנוצר טוקן חדש.

Kotlin+KTX

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}
MyFirebaseMessagingService.kt

Java

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(@NonNull String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}
MyFirebaseMessagingService.java

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

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

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

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

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

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

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

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

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

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

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

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

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

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

השלבים הבאים

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

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

מעבר להתראות

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