איך מתחילים להשתמש בהגדרת תצורה מרחוק ב-Android

אתם יכולים להשתמש ב-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 ו-Analytics ל-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:34.14.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:23.1.0")
       implementation("com.google.firebase:firebase-analytics:23.2.0")
   }

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

משיגים מופע של אובייקט 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 להפעלה מהירה נעשה שימוש בקובץ 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
   

   אפשר ליצור טוקן מסוג Bearer באמצעות הפקודה הבאה ב-Google Cloud CLI או ב-Cloud Shell:

   gcloud auth print-access-token
   

   תוקף הטוקן קצר, ולכן יכול להיות שתצטרכו ליצור אותו מחדש אם תקבלו שגיאת אימות.

   מסוף Firebase

   1. במסוף Firebase, עוברים אל DevOps & Engagement (פיתוח אפליקציות ואינטראקציה עם משתמשים) > הגדרת תצורה מרחוק > הדף Parameters (פרמטרים).

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

   3. כשמופיעה בקשה, מפעילים את האפשרות .xml for Android (קובץ XML ל-Android) ואז לוחצים על הורדת הקובץ.

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, עוברים אל DevOps & Engagement (פיתוח אפליקציות ואינטראקציה עם משתמשים) > הגדרת תצורה מרחוק > הדף Parameters (פרמטרים).

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

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

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

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

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

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

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

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

   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.

ויסות נתונים

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