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

1. מבוא

עדכון אחרון:9 במרץ 2021

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

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

איך זה עובד

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

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

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

מה תלמדו

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

איך יוצרים פרויקט חדש ב-Android

1. מתחילים פרויקט חדש ב-Android Studio
2. בחירת פעילות בסיסית
3. בקטע Configure Your Project (הגדרת הפרויקט) screen:
4. נותנים שם לפרויקט. שם החבילה ושמירת המיקום ייווצרו בשבילך באופן אוטומטי.
5. שפה: Java
6. גרסת SDK מינימום 16

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

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

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

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

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

2. (אופציונלי) אם יוצרים פרויקט חדש, אפשר לערוך את Project ID.

מערכת 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, כולל הנחיות לטיפול בכמה וריאנטים של build.

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

מוסיפים את קובץ התצורה של Firebase

בשלב הבא, תתבקשו להוריד קובץ תצורה שמכיל את כל המטא-נתונים של Firebase הנחוצים לאפליקציה שלכם. לוחצים על Download 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):

החלת הפלאגין: 'com.android.application'

// Add the next line:

החלת הפלאגין: ‘com.google.gms.google-services' // Google Services פלאגין

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. בקטע 'יחסי תלות', מוסיפים את הקוד הבא:

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

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

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

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

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

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

MainActivity.java

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

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

במהלך הפיתוח מומלץ להגדיר מרווח מינימלי לאחזור מינימלי נמוך יחסית. מידע נוסף זמין במאמר ויסות נתונים (throttle).

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

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

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

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

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

ויסות נתונים (throttle)

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

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

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

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

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

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

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

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

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

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

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

6. מזל טוב

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

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