הגדר אפליקציית לקוח Firebase Cloud Messaging ב-Android

לקוחות FCM דורשים התקנים עם אנדרואיד 4.4 ומעלה שמותקנת בהם גם האפליקציה של חנות Google Play, או אמולטור שמריץ אנדרואיד 4.4 עם ממשקי API של Google. שים לב שאינך מוגבל לפריסת אפליקציות Android שלך דרך חנות Google Play.

הגדר את ה-SDK

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

ערוך את מניפסט האפליקציה שלך

הוסף את הדברים הבאים למניפסט של האפליקציה שלך:

  • שירות המרחיב את FirebaseMessagingService . זה נדרש אם ברצונך לבצע כל טיפול בהודעות מעבר לקבלת הודעות על אפליקציות ברקע. כדי לקבל התראות באפליקציות בחזית, כדי לקבל מטען נתונים, לשלוח הודעות במעלה הזרם וכן הלאה, עליך להרחיב את השירות הזה.
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (אופציונלי) בתוך רכיב האפליקציה, רכיבי מטא נתונים כדי להגדיר סמל וצבע ברירת מחדל של התראות. אנדרואיד משתמשת בערכים אלה בכל פעם שהודעות נכנסות אינן מוגדרות במפורש סמל או צבע.
  • <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
         See README(https://goo.gl/l4GJaQ) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_icon"
        android:resource="@drawable/ic_stat_ic_notification" />
    <!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
         notification message. See README(https://goo.gl/6BKBk7) for more. -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_color"
        android:resource="@color/colorAccent" />
  • (אופציונלי) מ-Android 8.0 (רמת API 26) ומעלה, ערוצי הודעות נתמכים ומומלצים. FCM מספק ערוץ הודעות ברירת מחדל עם הגדרות בסיסיות. אם אתה מעדיף ליצור ולהשתמש בערוץ ברירת המחדל שלך, הגדר את default_notification_channel_id למזהה של אובייקט ערוץ ההתראות שלך כפי שמוצג; FCM ישתמש בערך זה בכל פעם שהודעות נכנסות לא מגדירים במפורש ערוץ התראות. למידע נוסף, ראה ניהול ערוצי התראות .
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

בקש הרשאת התראה בזמן ריצה ב-Android 13+

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

כברירת מחדל, FCM SDK (גרסה 23.0.6 ומעלה) כולל את ההרשאה POST_NOTIFICATIONS המוגדרת במניפסט. עם זאת, האפליקציה שלך תצטרך לבקש גם את גרסת זמן הריצה של הרשאה זו דרך הקוד הקבוע, android.permission.POST_NOTIFICATIONS . האפליקציה שלך לא תורשה להציג התראות עד שהמשתמש ייתן הרשאה זו.

כדי לבקש את הרשאת זמן הריצה החדשה:

Java

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // FCM SDK (and your app) can post notifications.
            } else {
                // TODO: Inform user that that your app will not show notifications.
            }
        });

// ...
private void askNotificationPermission() {
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED) {
        // FCM SDK (and your app) can post notifications.
    } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
        // TODO: display an educational UI explaining to the user the features that will be enabled
        //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
        //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
        //       If the user selects "No thanks," allow the user to continue without notifications.
    } else {
        // Directly ask for the permission
        requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
    }
}

Kotlin+KTX

// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission()
) { isGranted: Boolean ->
    if (isGranted) {
        // FCM SDK (and your app) can post notifications.
    } else {
        // TODO: Inform user that that your app will not show notifications.
    }
}

// ...
private fun askNotificationPermission() {
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
        PackageManager.PERMISSION_GRANTED
    ) {
        // FCM SDK (and your app) can post notifications.
    } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
        // TODO: display an educational UI explaining to the user the features that will be enabled
        //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
        //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
        //       If the user selects "No thanks," allow the user to continue without notifications.
    } else {
        // Directly ask for the permission
        requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
    }
}

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

ראה הרשאת זמן ריצה של התראות לקבלת שיטות עבודה מומלצות נוספות לגבי מתי האפליקציה שלך צריכה לבקש את הרשאת POST_NOTIFICATIONS מהמשתמש.

הרשאות התראות עבור אפליקציות הממוקדות ל-Android 12L (רמת API 32) ומטה

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

  • אם האפליקציה שלך יוצרת את ערוץ ההתראות הראשון שלה כשהיא פועלת ברקע (מה ש-FCM SDK עושה בעת קבלת התראת FCM), אנדרואיד לא תאפשר את הצגת ההתראה ולא יבקש מהמשתמש את הרשאת ההתראה עד הבא זמן פתיחת האפליקציה שלך. משמעות הדבר היא שכל הודעות שיתקבלו לפני פתיחת האפליקציה שלך והמשתמש מקבל את ההרשאה תאבד .
  • אנו ממליצים בחום לעדכן את האפליקציה שלך כדי למקד ל-Android 13+ כדי לנצל את ממשקי ה-API של הפלטפורמה כדי לבקש הרשאה. אם זה לא אפשרי, האפליקציה שלך צריכה ליצור ערוצי הודעות לפני שאתה שולח הודעות כלשהן לאפליקציה כדי להפעיל את תיבת הדו-שיח של הרשאת הודעות ולהבטיח שהודעות לא יאבדו. ראה שיטות עבודה מומלצות להרשאת הודעות למידע נוסף.

אופציונלי: הסר את הרשאת POST_NOTIFICATIONS

כברירת מחדל, FCM SDK כולל את ההרשאה POST_NOTIFICATIONS . אם האפליקציה שלך לא משתמשת בהודעות התראה (בין אם באמצעות התראות FCM, דרך SDK אחר, או שפורסמה ישירות על ידי האפליקציה שלך) ואתה לא רוצה שהאפליקציה שלך תכלול את ההרשאה, תוכל להסיר אותה באמצעות סמן remove של מיזוג המניפסט . זכור שהסרת הרשאה זו מונעת את הצגת כל ההתראות, לא רק התראות FCM. הוסף את הדברים הבאים לקובץ המניפסט של האפליקציה שלך:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

גש לאסימון רישום המכשיר

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

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

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

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

אחזר את אסימון הרישום הנוכחי

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

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();
        }
    });

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()
})

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

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

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);
}

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)
}

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

בדוק אם יש שירותי Google Play

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

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

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

כאשר נוצר אסימון רישום של FCM, הספרייה מעלה את המזהה ונתוני התצורה ל-Firebase. אם אתה מעדיף למנוע יצירה אוטומטית של אסימון, השבת את איסוף 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, בצע שיחת זמן ריצה:

Java

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin+KTX

Firebase.messaging.isAutoInitEnabled = true

כדי להפעיל מחדש את איסוף Analytics, קרא setAnalyticsCollectionEnabled() של המחלקה FirebaseAnalytics . לדוגמה:

setAnalyticsCollectionEnabled(true);

ערכים אלה נמשכים בכל הפעלה מחדש של האפליקציה לאחר ההגדרה.

הצעדים הבאים

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

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

זכור שכדי לנצל את התכונות הללו, תזדקק למימוש שרת ולפרוקוטולים של השרת (HTTP או XMPP), או הטמעה של ה- Admin SDK .