כדי להתחיל להשתמש ב-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 SDKs עם תלות ב-Google Play Services צריך להתקין את Google Play Services במכשיר או במכונה הווירטואלית.נכנסים ל-Firebase באמצעות חשבון Google.
אם עדיין אין לכם פרויקט ב-Android ואתם רק רוצים לנסות מוצר של Firebase, תוכלו להוריד אחת מדוגמאות למתחילים.
יצירת פרויקט Firebase
לפני שמוסיפים את Firebase לאפליקציה ל-Android, צריך ליצור פרויקט Firebase כדי לקשר אותו לאפליקציה. במאמר הסבר על פרויקטים ב-Firebase מוסבר בהרחבה על פרויקטים ב-Firebase.
יצירת פרויקט Firebase
-
במסוף Firebase, לוחצים על Add project.
-
כדי להוסיף משאבים של Firebase לפרויקט Google Cloud קיים, מזינים את שם הפרויקט או בוחרים אותו בתפריט הנפתח.
-
כדי ליצור פרויקט חדש, מזינים את שם הפרויקט הרצוי. אפשר גם לערוך את מזהה הפרויקט שמוצג מתחת לשם הפרויקט.
-
-
אם תופיע בקשה, קוראים את התנאים של Firebase ומאשרים אותם.
-
לוחצים על המשך.
-
(אופציונלי) מגדירים את Google Analytics בפרויקט כדי ליהנות מחוויית שימוש אופטימלית בכל אחד מהמוצרים הבאים של Firebase:
בוחרים חשבון Google Analytics קיים או יוצרים חשבון חדש.
אם יוצרים חשבון חדש, בוחרים את Analytics מיקום הדיווח ולאחר מכן מאשרים את ההגדרות של שיתוף הנתונים ואת התנאים של Google Analytics לפרויקט.
-
לוחצים על Create project (או על Add Firebase, אם משתמשים בפרויקט Google Cloud קיים).
מערכת Firebase מקצה משאבים באופן אוטומטי לפרויקט Firebase שלכם. בסיום התהליך, תועברו לדף הסקירה הכללית של הפרויקט ב-Firebase במסוף Firebase.
רישום האפליקציה ב-Firebase
כדי להשתמש ב-Firebase באפליקציה ל-Android, צריך לרשום את האפליקציה בפרויקט Firebase. לעיתים קרובות, רישום האפליקציה נקרא 'הוספת' האפליקציה לפרויקט.
נכנסים למסוף Firebase.
במרכז הדף 'סקירה כללית של הפרויקט', לוחצים על הסמל Android (
) או על הוספת אפליקציה כדי להפעיל את תהליך העבודה להגדרה.מזינים את שם החבילה של האפליקציה בשדה Android package name.
מהו שם חבילת אפליקציה ואיפה הוא מופיע?
שם החבילה מזהה באופן ייחודי את האפליקציה במכשיר ובחנות Google Play.
שם החבילה נקרא לרוב מזהה אפליקציה.
מחפשים את שם החבילה של האפליקציה בקובץ Gradle של המודול (ברמת האפליקציה), בדרך כלל
app/build.gradle
(שם חבילה לדוגמה:com.yourcompany.yourproject
).חשוב לזכור שהערך של שם החבילה תלוי אותיות רישיות, ולא ניתן לשנות אותו באפליקציית Firebase ל-Android אחרי שהיא תירשם בפרויקט Firebase.
(אופציונלי) מזינים פרטים נוספים על האפליקציה: הכינוי של האפליקציה וSHA-1 של אישור החתימה לניפוי באגים.
איך הכינוי של האפליקציה ואישור החתימה לצורך ניפוי באגים SHA-1 משמשים ב-Firebase?
כינוי לאפליקציה: מזהה פנימי לנוחות השימוש, שגלוי לכם רק במסוף Firebase.
SHA-1 לאישור החתימה לצורך ניפוי באגים: גיבוב SHA-1 נדרש ל-Firebase Authentication (כשמשתמשים בכניסה באמצעות חשבון Google או בכניסה באמצעות מספר טלפון) ול-Firebase Dynamic Links.
לוחצים על רישום האפליקציה.
הוספת קובץ תצורה של Firebase
מורידים את קובץ התצורה של Firebase ל-Android (
) ומוסיפים אותו לאפליקציה:google-services.json לוחצים על Download google-services.json כדי לקבל את קובץ התצורה של Firebase ל-Android.
מעבירים את קובץ התצורה לתיקיית השורש של המודול (ברמת האפליקציה) באפליקציה.
מה צריך לדעת על קובץ התצורה הזה?
קובץ התצורה של Firebase מכיל מזהים ייחודיים של הפרויקט, אבל הם לא סודיים. מידע נוסף על קובץ התצורה הזה זמין במאמר הסבר על פרויקטים ב-Firebase.
תמיד אפשר להוריד מחדש את קובץ התצורה של Firebase.
חשוב לוודא שלא מצורפים תווים נוספים לשם של קובץ התצורה, כמו
(2)
.
כדי לאפשר לערכות ה-SDK של Firebase לגשת לערכים בקובץ התצורה
, צריך את הפלאגין של Google services Gradle (google-services.json google-services
).בקובץ Gradle ברמת השורש (ברמת הפרויקט) (
<project>/build.gradle.kts
או<project>/build.gradle
), מוסיפים את הפלאגין של שירותי Google כתלייה: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 }
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 }
בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל
<project>/<app-module>/build.gradle.kts
או<project>/<app-module>/build.gradle
), מוסיפים את הפלאגין של שירותי Google:plugins { id("com.android.application") // Add the Google services Gradle plugin id("com.google.gms.google-services") // ... }
plugins { id 'com.android.application' // Add the Google services Gradle plugin id 'com.google.gms.google-services' // ... }
הוספת ערכות SDK של Firebase לאפליקציה
בקובץ 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.9.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.
מחפשים מודול ספרייה ספציפי ל-Kotlin? החל מ-אוקטובר 2023 (Firebase BoM 32.5.0), מפתחי Kotlin ומפתחי Java יוכלו להסתמך על מודול הספרייה הראשי (פרטים נוספים זמינים בשאלות הנפוצות בנושא היוזמה הזו).(חלופה) מוסיפים יחסי תלות לספריות של 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.2.0") }
סנכרון הפרויקט ב-Android עם קובצי Gradle.
האם מוצגת שגיאת build לגבי תמיכה ב-invoke-custom והפעלת ביטול הסוכרה (desugaring)? כך פותרים את הבעיה.
ב-builds של Gradle שמשתמשים בפלאגין Android Gradle (AGP) בגרסה 4.2 ואילך, צריך להפעיל תמיכה ב-Java 8. אחרת, בפרויקטים האלה ל-Android תופיע הודעת שגיאה ב-build כשמוסיפים את Firebase SDK.
כדי לפתור את התקלה ב-build, אפשר לפעול לפי אחת משתי האפשרויות הבאות:
- מוסיפים את הערך של
compileOptions
שמופיע בהודעת השגיאה לקובץbuild.gradle.kts
אוbuild.gradle
ברמת האפליקציה. - צריך להגדיל את הערך של
minSdk
בפרויקט Android ל-26 ומעלה.
מידע נוסף על הכישלון הזה ב-build זמין בתשובות לשאלות הנפוצות האלה.
- מוסיפים את הערך של
גישה לטוקן הרישום
כדי לשלוח הודעה למכשיר ספציפי, צריך לדעת את אסימון הרישום של המכשיר. כדי להשלים את המדריך הזה, תצטרכו להזין את האסימון בשדה במסוף ההתראות. לכן, חשוב להעתיק את האסימון או לאחסן אותו באופן מאובטח אחרי שאתם מאחזרים אותו.
בהפעלה הראשונית של האפליקציה, ה-SDK של FCM יוצר אסימון רישום למכונה של אפליקציית הלקוח. כדי לטרגט מכשירים ספציפיים או ליצור קבוצות של מכשירים, צריך לגשת לאסימון הזה על ידי הרחבה של
FirebaseMessagingService
ועקיפת onNewToken
.
בקטע הזה נסביר איך לאחזר את האסימון ואיך לעקוב אחרי השינויים באסימון. מכיוון שיכול להיות שתתבצע רוטציה של הטוקן אחרי ההפעלה הראשונית, מומלץ מאוד לאחזר את טוקן הרישום המעודכן האחרון.
אסימון הרישום עשוי להשתנות במקרים הבאים:
- האפליקציה משוחזרת במכשיר חדש
- המשתמש מסיר או מתקין מחדש את האפליקציה
- המשתמש מנקה את נתוני האפליקציה.
אחזור של טוקן הרישום הנוכחי
כשצריך לאחזר את האסימון הנוכחי, צריך להפעיל את הפונקציה
FirebaseMessaging.getInstance().getToken()
:
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() })
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
מופעלת בכל פעם שנוצר טוקן חדש.
/** * 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) }
/** * 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); }
אחרי שתקבלו את הטוקן, תוכלו לשלוח אותו לשרת האפליקציה ולאחסן אותו בשיטה המועדפת עליכם.
שליחת הודעת בדיקה
מתקינים את האפליקציה ומפעילים אותה במכשיר היעד. במכשירי Apple, תצטרכו לאשר את הבקשה לקבלת התראות מרחוק.
מוודאים שהאפליקציה פועלת ברקע במכשיר.
במסוף Firebase, פותחים את הדף Messaging.
אם זו ההודעה הראשונה שלכם, בוחרים באפשרות יצירת הקמפיין הראשון.
- בוחרים באפשרות הודעות התראה של Firebase ואז בוחרים באפשרות יצירה.
לחלופין, בכרטיסייה Campaigns (קמפיינים), בוחרים באפשרות New campaign (קמפיין חדש) ואז באפשרות Notifications (התראות).
מזינים את הטקסט של ההודעה. כל שאר השדות הם אופציונליים.
בוחרים באפשרות שליחת הודעת בדיקה בחלונית השמאלית.
בשדה Add an FCM registration token, מזינים את אסימון ההרשמה שקיבלתם בקטע הקודם במדריך הזה.
בוחרים באפשרות בדיקה.
אחרי שבוחרים באפשרות בדיקה, ההתראה אמורה להופיע במכשיר הלקוח המטורגט (עם האפליקציה ברקע).
כדי לקבל תובנות לגבי העברת ההודעות לאפליקציה, אפשר לעיין ב לוח הבקרה של הדוחות FCM, שבו מתועד מספר ההודעות שנשלחו ונפתחו במכשירי Apple ו-Android, וגם נתונים לגבי 'חשיפות' (התראות שמוצגות למשתמשים) באפליקציות ל-Android.
השלבים הבאים
שליחת הודעות לאפליקציות שבחזית
אחרי ששלחתם הודעות התראה בזמן שהאפליקציה הייתה ברקע, תוכלו לקרוא את המאמר קבלת הודעות באפליקציה ל-Android כדי להתחיל לשלוח הודעות לאפליקציות שבחזית.
מעבר להתראות
כדי להוסיף לאפליקציה התנהגות מתקדמת יותר מעבר להודעות התראות, כדאי לעיין במאמרים הבאים: