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


אפשר להשתמש ב-Firebase Remote Config כדי להגדיר פרמטרים באפליקציה ולעדכן את הערכים שלהם בענן, וכך לשנות את המראה וההתנהגות של האפליקציה בלי להפיץ עדכון לאפליקציה. במדריך הזה נסביר איך מתחילים ומספקים כמה דוגמאות לקוד. כל הקוד הזה זמין לשכפול או להורדה מהמאגר 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 ל-Android. מומלץ להשתמש ב-Firebase Android BoM כדי לשלוט בגרסאות הספרייה.

    בנוסף, כחלק מהגדרת Analytics, צריך להוסיף לאפליקציה את Firebase SDK עבור 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 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.0.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
    מחפשים מודול ספרייה ספציפי ל-Kotlin? החל מ-אוקטובר 2023 (Firebase BoM 32.5.0), מפתחי Kotlin ומפתחי Java יוכלו להסתמך על מודול הספרייה הראשי (פרטים נוספים זמינים בשאלות הנפוצות לגבי היוזמה הזו).

שלב 2: אחזור של אובייקט ה-singleton Remote Config

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

Kotlin+KTX 

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

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

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

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

אפשר להגדיר ערכי ברירת מחדל של פרמטרים באפליקציה באובייקט 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

    Firebase מסוף

    1. בכרטיסייה Parameters, פותחים את Menu ובוחרים באפשרות Download default values.

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

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

    Kotlin+KTX 

    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

    Java 

    mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

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

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

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

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

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

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

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

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

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

    Kotlin+KTX 

    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.

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

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

    Kotlin+KTX 

    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 תרחישים לדוגמה ולקרוא את המסמכים בנושא מושגים מרכזיים ואסטרטגיות מתקדמות, כולל: