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

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

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

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

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

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

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

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

השלבים הבאים

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

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

מעבר להתראות

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