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

1. מבוא

עדכון אחרון: 2021-03-09

מהי הגדרת תצורה מרחוק ב-Firebase?

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

איך זה עובד

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

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

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

מה תלמדו

• איך מטמיעים את הגדרת התצורה מרחוק ב-Firebase
• איך משתמשים בהגדרת תצורה מרחוק ב-Firebase כדי לשנות ערכים בלי לעדכן את האפליקציה

מה תצטרכו

• הגרסה העדכנית של Android Studio
• חשבון Firebase
• (מומלץ, אבל אופציונלי) מכשיר Android פיזי להרצת האפליקציה
• ידע בסיסי ב-Java או ב-Kotlin

2. הגדרה

(אופציונלי) הורדת קוד לדוגמה

ב-Codelab הזה תבנו אפליקציית בדיקה משלכם, אבל אם אתם רוצים לראות ולהריץ את האפליקציה לדוגמה הקיימת, אתם יכולים להוריד את קוד לדוגמה למדריך למתחילים.

כדי להוריד את כל הקוד של ה-codelab הזה, לוחצים על הלחצן הבא:

הורדת קוד המקור

מחלצים את קובץ ה-ZIP שהורד. הפעולה הזו תגרום לפריקה של תיקיית שורש בשם quickstart-android-master.

…או משכפלים את המאגר ב-GitHub משורת הפקודה.

$ git clone https://github.com/firebase/quickstart-android.git

המאגר מכיל כמה תיקיות. נשתמש בתיקייה config.

(אופציונלי) ייבוא קוד לדוגמה

מפעילים את Android Studio ובוחרים באפשרות Import project (ייבוא פרויקט) במסך הפתיחה. אחר כך פותחים את התיקייה שהורדה ובוחרים את התיקייה config. ואז לוחצים על 'פתיחה'.

יצירת פרויקט Android חדש

1. ב-Android Studio, מתחילים פרויקט חדש.
2. בחירת פעילות בסיסית
3. במסך 'הגדרת הפרויקט':
4. נותנים שם לפרויקט. שם החבילה ומיקום השמירה ייווצרו באופן אוטומטי.
5. שפה: Java
6. ‫Minimum SDK 16

3. הוספת Firebase ו-Firebase Analytics לפרויקט Android

יצירת פרויקט Firebase

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

1. במסוף Firebase, לוחצים על הוספת פרויקט, ואז בוחרים או מזינים שם פרויקט.

אם יש לכם פרויקט קיים ב-Google Cloud Platform‏ (GCP), אתם יכולים לבחור את הפרויקט מהתפריט הנפתח כדי להוסיף לו משאבי Firebase.

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

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

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

3. לוחצים על המשך.
4. הגדרתם את Google Analytics לפרויקט, כך שתוכלו ליהנות מחוויה אופטימלית בשימוש בכל אחד מהמוצרים הבאים של Firebase:

• Firebase Crashlytics
• Firebase Predictions
• העברת הודעות בענן ב-Firebase
• העברת הודעות בתוך האפליקציה ב-Firebase
• הגדרת תצורה מרחוק ב-Firebase
• Firebase A/B Testing

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

5. לוחצים על יצירת פרויקט (או על הוספת Firebase אם משתמשים בפרויקט קיים ב-GCP).

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

רישום האפליקציה ב-Firebase

אחרי שיש לכם פרויקט Firebase, אתם יכולים להוסיף אליו את אפליקציית Android.

במאמר הסבר על פרויקטים ב-Firebase מפורטות שיטות מומלצות ושיקולים להוספת אפליקציות לפרויקט ב-Firebase, כולל הסבר על טיפול בכמה וריאציות של בנייה.

1. עוברים אל מסוף Firebase.
2. בחלק העליון של הדף Project Overview (סקירת הפרויקט), לוחצים על סמל Android כדי להפעיל את תהליך ההגדרה. אם כבר הוספתם אפליקציה לפרויקט Firebase, לוחצים על 'הוספת אפליקציה' כדי להציג את אפשרויות הפלטפורמה.
3. מזינים את שם החבילה של האפליקציה בשדה שם החבילה של Android.
4. (אופציונלי) מזינים כינוי לאפליקציה.
5. משאירים את השדה SHA-1 ריק כי לא נדרש SHA-1 לפרויקט הזה.
6. לוחצים על Register app (רישום האפליקציה).

הוספת קובץ ההגדרות של Firebase

לאחר מכן, תתבקשו להוריד קובץ תצורה שמכיל את כל המטא-נתונים הדרושים של Firebase לאפליקציה שלכם. לוחצים על הורדת google-services.json כדי לקבל את קובץ התצורה של Firebase Android (google-services.json).

בקובץ Gradle ברמת הפרויקט (build.gradle), מוסיפים כללים להכללת הפלאגין Google Services Gradle. כדאי גם לבדוק שיש לכם את מאגר ה-Maven של Google.

קובץ build.gradle ברמת הפרויקט (<project>/build.gradle):

buildscript {

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
  }

  dependencies {
    // ...

    // Add the following line:
    classpath 'com.google.gms:google-services:4.3.5'  // Google Services plugin
  }
}

allprojects {
  // ...

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
    // ...
  }
}

בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל app/build.gradle), מפעילים את הפלאגין Google Services Gradle:

build.gradle ברמת האפליקציה (<project>/<app-module>/build.gradle):

apply plugin: ‘com.android.application'

‎// Add the following line:

apply plugin: ‘com.google.gms.google-services' // Google Services plugin

android {

‪// ...

}

הוספת Firebase SDK לאפליקציית Android

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

(הפעולה הזו כבר מתבצעת בקוד לדוגמה של ההפעלה המהירה)

בעזרת Firebase Android BoM, צריך להצהיר על התלות של ספריית Android להגדרת תצורה מרחוק בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל app/build.gradle). באמצעות Firebase Android BoM, האפליקציה תמיד תשתמש בגרסאות תואמות של ספריות Firebase Android.

בנוסף, כחלק מהגדרת Analytics, צריך להוסיף את Firebase SDK for Google Analytics לאפליקציה. בקטע dependencies, מוסיפים את הקוד הבא:

app/build.gradle

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:26.6.0')

    // Declare 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'
}

סנכרון הפרויקט עם קובצי gradle

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

4. בדיקת הרכיבים העיקריים של הגדרת תצורה מרחוק

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

1. משיגים את אובייקט Singleton של הגדרת התצורה מרחוק

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

MainActivity.java

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

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

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

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

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

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

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

1. יוצרים תיקייה בשם xml בתיקייה res.

2. לוחצים לחיצה ימנית על התיקייה xml שנוצרה ויוצרים קובץ.

3. מגדירים את ערכי ברירת המחדל. בקטע הבא תנסו לשנות את ערכי ברירת המחדל בקובץ ה-XML של ההפעלה המהירה של הגדרת התצורה מרחוק.
4. מוסיפים את הערכים האלה לאובייקט של הגדרת התצורה מרחוק באמצעות setDefaultsAsync(int), כמו שמוצג כאן:

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

3. קבלת ערכי פרמטרים לשימוש באפליקציה

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

• getBoolean()
• getDouble()
• getLong()
• getString()

4. מאחזרים ומפעילים ערכים

1. כדי לאחזר ערכי פרמטרים מהקצה העורפי של הגדרת התצורה מרחוק, קוראים ל-method‏ fetch(). כל הערכים שאתם מגדירים בקצה העורפי מאוחזרים ונשמרים באובייקט של הגדרת התצורה מרחוק.
2. כדי שערכי הפרמטרים שאוחזרו יהיו זמינים באפליקציה, צריך להפעיל את השיטה activate(). במקרים שבהם רוצים לאחזר ולהפעיל ערכים בקריאה אחת, אפשר להשתמש בבקשת fetchAndActivate()‎ כדי לאחזר ערכים מהקצה העורפי של הגדרת התצורה מרחוק ולהפוך אותם לזמינים לאפליקציה:

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

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

הערה: אם האפליקציה לא נוצרת באמצעות Gradle, צריך להוסיף לאפליקציה באופן ידני את משאב מחרוזות google_app_id הנכון כדי שהגדרת תצורה מרחוק תוכל להתבצע. הפלאגין google-services Gradle בדרך כלל מוסיף את הערך הזה באופן אוטומטי, אבל אפשר למצוא את הערך המתאים בקובץ google-services.json שמורידים מ-Firebase Console. מידע נוסף על קבלת הערך של google_app_id מהקובץ google-services.json זמין במאמר בנושא עיבוד קובץ ה-JSON.

הגבלת קצב העברת הנתונים

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

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

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

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

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

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

5. שינוי התנהגות האפליקציה באמצעות הגדרת תצורה מרחוק

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

פותחים את res/xml/remote_config_defaults.xml ומשנים את ערכי ברירת המחדל למשהו אחר.

res/xml/remote_config_defaults.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- START xml_defaults -->
<defaultsMap>
    <entry>
        <key>loading_phrase</key>
        <value>Fetching config...</value>
    </entry>
    <entry>
        <key>welcome_message_caps</key>
        <value>false</value>
    </entry>
    <entry>
        <key>welcome_message</key>
        <value>Welcome to my awesome app!</value>
    </entry>
</defaultsMap>
    <!-- END xml_defaults -->

אימות השינוי בערך ברירת המחדל באפליקציה

1. מריצים את הפרויקט באמולטור או באמצעות מכשיר בדיקה כדי לאשר את ההתנהגות.
2. לוחצים על Open (פתיחה) בגרסת Java או בגרסת Kotlin.

3. קוראים את הודעת הפתיחה בתצוגה הראשית.

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

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

1. פותחים את מסוף Firebase ופותחים את הפרויקט.
2. בתפריט הצד שמימין, בקטע Engage, בוחרים באפשרות הגדרת תצורה מרחוק כדי להציג את מרכז הבקרה של הגדרת תצורה מרחוק.
3. בקטע Add a parameter (הוספת פרמטר), מזינים את Parameter key. בקטע Default value מוסיפים את הטקסט הרצוי. אחר כך לוחצים על 'הוספת פרמטר'. ב-codelab הזה נשתמש במפתחות הפרמטרים בקובץ res/xml/remote_config_defaults.xml. פרטים נוספים מופיעים בטבלה הבאה:

מפתח פרמטר	ערך ברירת המחדל (remote_config_defaults.xml)	תיאור
loading_phrase	אחזור ההגדרה מתבצע...	מחרוזת; מוצג כשמאחזרים ערכים של הגדרת התצורה מרחוק.
welcome_message_caps	false	בוליאני; אם הערך הוא true, ההודעה welcome_message משתנה לאותיות רישיות
welcome_message	ברוכים הבאים לאפליקציה המדהימה שלי!	מחרוזת; הודעת פתיחה

צילום מסך לדוגמה:

4. כשמסיימים להוסיף פרמטרים, לוחצים על 'פרסום שינויים'.
5. מריצים שוב את האפליקציה באמולטור או במכשיר ולוחצים על הלחצן Fetch Remote Welcome (אחזור הודעת פתיחה מרחוק).

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

6. מזל טוב

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

• תחילת העבודה עם הגדרת תצורה מרחוק ב-Firebase
• מה אפשר לעשות עם הגדרת תצורה מרחוק?
• Firebase Remote Config API
• יצירת ניסויים של הגדרת תצורה מרחוק ב-Firebase עם בדיקות A/B