איך מתחילים להשתמש בהגדרת תצורה מרחוק ב-Android

בחירת פלטפורמה:

iOS+‎ Android אינטרנט Flutter Unity C++‎

אתם יכולים להשתמש ב-Firebase Remote Config כדי להגדיר פרמטרים באפליקציה ולעדכן את הערכים שלהם בענן, וכך לשנות את המראה וההתנהגות של האפליקציה בלי להפיץ עדכון לאפליקציה. במדריך הזה נסביר איך להתחיל לעבוד עם Firebase, ונספק קוד לדוגמה שאפשר לשכפל או להוריד ממאגר firebase/quickstart-android ב-GitHub.

שלב 1: מוסיפים לאפליקציה את Firebase ואת ה-SDK של הגדרת התצורה מרחוק

1. אם עדיין לא הוספתם את Firebase לפרויקט Android, אתם צריכים להוסיף אותו.

2. כדי להשתמש ב-Remote Config, צריך להשתמש ב-Google Analytics בשביל הטירגוט המותנה של מופעי האפליקציה למאפייני משתמשים וקהלים. חשוב לוודא שהפעלתם את Google Analytics בפרויקט.

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

   בנוסף, כחלק מההגדרה של Analytics, צריך להוסיף לאפליקציה את Firebase SDK ל-Google Analytics.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:35.1.0"))
   
       // Add the dependencies for the Remote Config and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config")
   implementation("com.google.firebase:firebase-analytics")
   }

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

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

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

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

   dependencies {
       // Add the dependencies for the Remote Config and Analytics libraries
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config:24.0.1")
       implementation("com.google.firebase:firebase-analytics:24.0.0")
   }

הערה: מכיוון ש-Android SDK תלוי ב-API בארכיטקטורת REST של Remote Config, חשוב לא להשבית את ה-API הזה, שמופעל כברירת מחדל בפרויקט רגיל.

שלב 2: משיגים את אובייקט singleton של Remote Config

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

Kotlin

val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)
MainActivity.kt

Java

FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);
MainActivity.java

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

במהלך הפיתוח, מומלץ להגדיר מרווח אחזור מינימלי נמוך יחסית. מידע נוסף זמין במאמר ויסות נתונים.

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

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

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

1. מגדירים קבוצה של שמות פרמטרים וערכי ברירת מחדל לפרמטרים באמצעות אובייקט Map או קובץ משאבים בפורמט XML שמאוחסן בתיקייה res/xml של האפליקציה. באפליקציה לדוגמה למתחילים של Remote Config נעשה שימוש בקובץ XML כדי להגדיר שמות וערכים של פרמטרים כברירת מחדל.

   אם כבר הגדרתם ערכים לפרמטרים של הקצה העורפי של Remote Config, אתם יכולים להוריד קובץ XML שנוצר וכולל את כל ערכי ברירת המחדל, ולשמור אותו בספרייה res/xml של האפליקציה:

   REST

   curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=XML -o remote_config_defaults.xml
   

   כדי ליצור טוקן למוכ"ז, מריצים את הפקודה הבאה באמצעות Google Cloud CLI או Cloud Shell:

   gcloud auth print-access-token
   

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

   מסוף Firebase

   1. במסוף Firebase, נכנסים לדף DevOps & Engagement (DevOps ומעורבות) > Remote Config (הגדרת תצורה מרחוק) > Parameters (פרמטרים).

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

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

2. מוסיפים את הערכים האלה לאובייקט Remote Config באמצעות setDefaultsAsync(int), כמו שמוצג כאן:

   Kotlin

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

שלב 4: מקבלים ערכי פרמטר לשימוש באפליקציה

עכשיו אפשר לקבל ערכי פרמטרים מהאובייקט Remote Config. אם מגדירים ערכים בקצה העורפי, מאחזרים אותם ואז מפעילים אותם, הערכים האלה זמינים לאפליקציה. אחרת, מקבלים את ערכי הפרמטרים בתוך האפליקציה שהוגדרו באמצעות setDefaultsAsync(int). כדי לקבל את הערכים האלה, צריך להפעיל את השיטה שמופיעה בקוד הבא, שממפה לסוג הנתונים שהאפליקציה מצפה לקבל, ולספק את מפתח הפרמטר כארגומנט:

• getBoolean()
• getDouble()
• getLong()
• getString()

שלב 5: מגדירים ערכי פרמטרים בקצה העורפי של Remote Config

באמצעות מסוף Firebase או ממשקי ה-API לקצה העורפי של Remote Config, אתם יכולים ליצור ערכי ברירת מחדל חדשים בצד השרת שמחליפים את הערכים באפליקציה, בהתאם ללוגיקה המותנית או לטירגוט המשתמשים הרצויים. בקטע הזה מוסבר איך יוצרים את הערכים האלה במסוף Firebase.

1. במסוף Firebase, נכנסים לדף DevOps & Engagement (DevOps ומעורבות) > Remote Config (הגדרת תצורה מרחוק) > Parameters (פרמטרים).

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

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

   Kotlin

           val customSignals = customSignals {
               put("city", "Tokyo")
               put("preferred_event_category", "sports")
           }
   
           remoteConfig.setCustomSignals(customSignals)
       

   Java

           CustomSignals customSignals = new CustomSignals.Builder()
               .put("city", "Tokyo")
               .put("preferred_event_category", "sports")
               .build();
   
           mFirebaseRemoteConfig.setCustomSignals(customSignals);
   
       

שלב 6: מאחזרים ומפעילים את הערכים

1. כדי לאחזר ערכי פרמטרים מה-backend של Remote Config, צריך להפעיל את השיטה fetch(). כל הערכים שהגדרתם בקצה העורפי מאוחזרים ונשמרים באובייקט Remote Config.

2. כדי שערכי הפרמטרים שאוחזרו יהיו זמינים לאפליקציה, צריך להפעיל את השיטה activate().

   אם רוצים לאחזר ולהפעיל ערכים בקריאה אחת, אפשר להשתמש בבקשת fetchAndActivate() כדי לאחזר ערכים מה-backend של Remote Config ולהפוך אותם לזמינים באפליקציה:

   Kotlin

   remoteConfig.fetchAndActivate()
       .addOnCompleteListener(this) { task ->
           if (task.isSuccessful) {
               val updated = task.result
               Log.d(TAG, "Config params updated: $updated")
               Toast.makeText(
                   this,
                   "Fetch and activate succeeded",
                   Toast.LENGTH_SHORT,
               ).show()
           } else {
               Toast.makeText(
                   this,
                   "Fetch failed",
                   Toast.LENGTH_SHORT,
               ).show()
           }
           displayWelcomeMessage()
       }

   Java

   mFirebaseRemoteConfig.fetchAndActivate()
           .addOnCompleteListener(this, new OnCompleteListener<Boolean>() {
               @Override
               public void onComplete(@NonNull Task<Boolean> task) {
                   if (task.isSuccessful()) {
                       boolean updated = task.getResult();
                       Log.d(TAG, "Config params updated: " + updated);
                       Toast.makeText(MainActivity.this, "Fetch and activate succeeded",
                               Toast.LENGTH_SHORT).show();
   
                   } else {
                       Toast.makeText(MainActivity.this, "Fetch failed",
                               Toast.LENGTH_SHORT).show();
                   }
                   displayWelcomeMessage();
               }
           });

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

הערה: אם האפליקציה לא נוצרת באמצעות Gradle, צריך להוסיף באופן ידני את משאב המחרוזת הנכון של google_app_id לאפליקציה כדי ש-Remote Config יוכל לבצע אתחול. הפלאגין של google-services Gradle בדרך כלל מוסיף את זה באופן אוטומטי, אבל אפשר למצוא את הערך המתאים בקובץ התצורה של google-services.json שמורידים ממסוף Firebase. למידע נוסף על קבלת הערך של google_app_id מקובץ התצורה של google-services.json, ראו איך קובץ התצורה של JSON מעובד.

שלב 7: האזנה לעדכונים בזמן אמת

אחרי שאחזרתם את ערכי הפרמטרים, אתם יכולים להשתמש ב-Remote Config בזמן אמת כדי להאזין לעדכונים מה-backend של Remote Config. ‫Remote Config שולח אותות בזמן אמת למכשירים מחוברים כשיש עדכונים זמינים, ומאחזר אוטומטית את השינויים אחרי שמפרסמים גרסה חדשה של Remote Config.

עדכונים בזמן אמת נתמכים ב-SDK של Firebase ל-Android בגרסה 21.3.0 ואילך (Firebase BoM בגרסה 31.2.4 ואילך).

חשוב: כדי להשתמש ב-Remote Config בזמן אמת, צריך גם את Realtime API של Firebase Remote Config, שכבר אמור להיות מופעל. כדי לוודא שהם מופעלים, פותחים את מסוף Google Cloud, בוחרים את הפרויקט ופותחים את הדף APIs and Services. ה-API אמור להופיע כמופעל. אם הוא לא מופיע או לא מופעל, לוחצים על Enable APIs & Services, מחפשים את Firebase Remote Config Realtime API ומפעילים אותו.

1. באפליקציה, משתמשים ב-addOnConfigUpdateListener() כדי להתחיל להאזין לעדכונים ולאחזר באופן אוטומטי ערכי פרמטרים חדשים. מטמיעים את הקריאה החוזרת (callback) של onUpdate() כדי להפעיל את ההגדרות המעודכנות.

   Kotlin

   remoteConfig.addOnConfigUpdateListener(object : ConfigUpdateListener {
           override fun onUpdate(configUpdate : ConfigUpdate) {
           Log.d(TAG, "Updated keys: " + configUpdate.updatedKeys);
   
           if (configUpdate.updatedKeys.contains("welcome_message")) {
               remoteConfig.activate().addOnCompleteListener {
                   displayWelcomeMessage()
               }
           }
           }
   
           override fun onError(error : FirebaseRemoteConfigException) {
               Log.w(TAG, "Config update error with code: " + error.code, error)
           }
       })
       

   Java

       mFirebaseRemoteConfig.addOnConfigUpdateListener(new ConfigUpdateListener() {
           @Override
           public void onUpdate(ConfigUpdate configUpdate) {
               Log.d(TAG, "Updated keys: " + configUpdate.getUpdatedKeys());
               mFirebaseRemoteConfig.activate().addOnCompleteListener(new OnCompleteListener<Boolean>() {
                   @Override
                   public void onComplete(@NonNull Task<Boolean> task) {
                       displayWelcomeMessage();
                   }
               });
           }
           @Override
           public void onError(FirebaseRemoteConfigException error) {
               Log.w(TAG, "Config update error with code: " + error.getCode(), error);
           }
       });
       

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

ויסות נתונים (throttle)

אם אפליקציה מאחזרת יותר מדי פעמים בפרק זמן קצר, קריאות האחזור מוגבלות וה-SDK מחזיר את הערך FirebaseRemoteConfigFetchThrottledException. לפני גרסת SDK‏ 17.0.0, המגבלה הייתה 5 בקשות אחזור בחלון של 60 דקות (בגרסאות חדשות יותר המגבלות פחות מחמירות).

טיפ: החל מגרסה Android SDK v21.3.0 ואילך (Firebase BoM v31.3.0 ואילך), אפשר להשתמש ב-Remote Config בזמן אמת כדי לאחזר באופן אוטומטי ערכי פרמטרים מעודכנים מה-backend של Remote Config ברגע שהם מתפרסמים, ולעקוף כל הגדרה של מרווח אחזור מינימלי. מידע נוסף זמין במאמר האזנה לעדכונים בזמן אמת.

במהלך פיתוח האפליקציה, יכול להיות שתרצו לאחזר ולהפעיל הגדרות אישיות בתדירות גבוהה (הרבה פעמים בשעה) כדי שתוכלו לבצע חזרות במהירות בזמן הפיתוח והבדיקה של האפליקציה. עדכונים בזמן אמת של Remote Config עוקפים באופן אוטומטי את המטמון כשההגדרות האישיות מתעדכנות בשרת. כדי לאפשר חזרה מהירה על תהליך העבודה בפרויקט עם עד 10 מפתחים, אתם יכולים להגדיר באופן זמני אובייקט FirebaseRemoteConfigSettings עם מרווח זמן מינימלי נמוך לאחזור (setMinimumFetchIntervalInSeconds) באפליקציה.

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

1. הפרמטר ב-fetch(long)
2. הפרמטר ב- FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
3. ערך ברירת המחדל הוא 12 שעות

כדי להגדיר ערך מותאם אישית למרווח האחזור המינימלי, משתמשים ב-FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long).

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