תחילת העבודה עם הגדרת תצורה מרחוק ב-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.2.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.0")
    implementation("com.google.firebase:firebase-analytics:22.1.0")
}
         מחפשים מודול ספרייה ספציפי ל-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

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

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

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

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

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

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

עדכונים בזמן אמת נתמכים על ידי 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)

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