תחילת העבודה עם הגדרת תצורה מרחוק ב-Firebase

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

שלב 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 ל-Android. מומלץ להשתמש ב-Firebase Android BoM כדי לשלוט בניהול הגרסאות של הספריות.

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

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.16.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:22.1.2")
       implementation("com.google.firebase:firebase-analytics:22.5.0")
   }

   מחפשים מודול ספריות ספציפי ל-Kotlin? החל מאוקטובר 2023 (Firebase BoM 32.5.0), מפתחים ב-Kotlin וב-Java יכולים להסתמך על מודול הספרייה הראשי (פרטים נוספים זמינים במאמר שאלות נפוצות בנושא).

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

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

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

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

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

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

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

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

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

   אם כבר הגדרתם ערכי פרמטרים של Remote Config backend, תוכלו להוריד קובץ 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
   

   Firebase console

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

   2. כשמוצגת בקשה, מפעילים את האפשרות .xml for Android ואז לוחצים על Download file (הורדת הקובץ).

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

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

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

   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. כדי לאחזר ערכי פרמטרים מהקצה העורפי Remote Config, קוראים לשיטה fetch(). כל הערכים שאתם מגדירים בקצה העורפי מאוחזרים ומאוחסנים באובייקט Remote Config.

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

   במקרים שבהם רוצים לאחזר ולהפעיל ערכים בקריאה אחת, אפשר להשתמש בבקשת fetchAndActivate() כדי לאחזר ערכים מהקצה העורפי 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();
               }
           });

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

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

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

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

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

   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 דקות (בגרסאות חדשות יותר המגבלות מקלות יותר).

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

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

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

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

השלבים הבאים

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

• ניהול גרסאות של תבניות Remote Config
• אסטרטגיות לטעינת תצורות