תחילת העבודה עם הגדרת תצורה מרחוק ב-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, צריך להוסיף לאפליקציה את ה-SDK של Firebase של 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, האפליקציה תמיד תשתמש בגרסאות תואמות של ספריות Android של Firebase.

    (חלופה)  מוסיפים יחסי תלות לספריות של 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

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

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

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

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

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

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

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

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