שילוב של הגדרת תצורה מרחוק ב-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 על ידי בחירה באפשרות File > Sync Project with Gradle Files (קובץ > סנכרון הפרויקט עם קובצי 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. כדי לאחזר ערכי פרמטרים מהקצה העורפי של הגדרת התצורה מרחוק, קוראים לשיטה 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	ברוכים הבאים לאפליקציה המדהימה שלי!	מחרוזת; הודעת פתיחה

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

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

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

6. מזל טוב

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

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