התחל עם Firebase Remote Config


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

שלב 1: הוסף את Firebase ואת ה-Remote Config SDK לאפליקציה שלך

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

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

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

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

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.7.4"))
    
        // 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:21.6.3")
        implementation("com.google.firebase:firebase-analytics:21.5.1")
    }
    
    מחפש מודול ספרייה ספציפי לקוטלין? החל מאוקטובר 2023 (Firebase BoM 32.5.0) , מפתחי Kotlin ו-Java יכולים להיות תלויים במודול הספרייה הראשי (לפרטים, עיין בשאלות הנפוצות לגבי יוזמה זו ).

שלב 2: קבל את אובייקט ה-Remote Config Singleton

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

Kotlin+KTX

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

Java

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

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

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

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

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

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

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

    מנוחה

    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 עבור Android ולאחר מכן לחץ על הורד קובץ .

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

    Kotlin+KTX

    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

    Java

    mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

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

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

שלב 5: הגדר ערכי פרמטרים ב-Remote Config Backend

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

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

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

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

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

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

עדכונים בזמן אמת נתמכים על ידי Firebase SDK עבור Android v21.3.0+ (Firebase BoM v31.2.4+).

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

    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() {
                @Override
                public void onComplete(@NonNull Task task) {
                    displayWelcomeMessage();
                }
            });
        }
    
        @Override
        public void onError(FirebaseRemoteConfigException error) {
            Log.w(TAG, "Config update error with code: " + error.getCode(), error);
        }
    });
    
  2. בפעם הבאה שתפרסם גרסה חדשה של התצורה המרוחקת שלך, מכשירים שמריצים את האפליקציה שלך ומאזינים לשינויים יתקשרו ל- ConfigUpdateListener .

מצערת

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

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

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

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

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

הצעדים הבאים

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