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

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

שלב 1: מוסיפים ומפעילים את ה-SDK של Remote Config

1. אם עדיין לא עשיתם זאת, התקינו את Firebase JS SDK והפעילו את Firebase.

2. מוסיפים את ה-JS SDK של Remote Config ומפעילים את Remote Config:

import { initializeApp } from "firebase/app";
import { getRemoteConfig } from "firebase/remote-config";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);


// Initialize Remote Config and get a reference to the service
const remoteConfig = getRemoteConfig(app);

import firebase from "firebase/compat/app";
import "firebase/compat/remote-config";

// TODO: Replace the following with your app's Firebase project configuration
// See: https://firebase.google.com/docs/web/learn-more#config-object
const firebaseConfig = {
  // ...
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);


// Initialize Remote Config and get a reference to the service
const remoteConfig = firebase.remoteConfig();

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

שלב 2: הגדרת המרווח המינימלי לאחזור

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

// The default and recommended production fetch interval for Remote Config is 12 hours
remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
rc_set_minimum_fetch_time.js

remoteConfig.settings.minimumFetchIntervalMillis = 3600000;
index.js

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

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

remoteConfig.defaultConfig = {
  "welcome_message": "Welcome"
};
rc_set_default_values.js

remoteConfig.defaultConfig = {
  "welcome_message": "Welcome"
};
index.js

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

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=JSON -o remote_config_defaults.json

gcloud auth print-access-token

בדוגמאות הבאות מוצגות שתי דרכים שונות לייבא ולהגדיר ערכי ברירת מחדל באפליקציה. בדוגמה הראשונה נעשה שימוש ב-fetch, שיבצע בקשת HTTP לקובץ ברירות המחדל שנכלל בחבילת האפליקציה:

  const rcDefaultsFile = await fetch('remote_config_defaults.json');
  const rcDefaultsJson = await rcDefaultsFile.json();
  remoteConfig.defaultConfig = rcDefaultsJson;
  

בדוגמה הבאה נעשה שימוש ב-require, שמקמפל את הערכים לאפליקציה בזמן ה-build:

  let rcDefaults = require('./remote_config_defaults.json');
  remoteConfig.defaultConfig = rcDefaults;

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

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

import { getValue } from "firebase/remote-config";

const val = getValue(remoteConfig, "welcome_messsage");
rc_get_values.js

const val = remoteConfig.getValue("welcome_messsage");
index.js

שלב 5: מגדירים ערכי פרמטרים

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

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

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

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

     let customSignals = {
        "city": "Tokyo",
        "preferred_event_category": "sports"
     }
   
     setCustomSignals(config, customSignals);

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

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

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

import { fetchAndActivate } from "firebase/remote-config";

fetchAndActivate(remoteConfig)
  .then(() => {
    // ...
  })
  .catch((err) => {
    // ...
  });
rc_fetch_config_callback.js

remoteConfig.fetchAndActivate()
  .then(() => {
    // ...
  })
  .catch((err) => {
    // ...
  });
index.js

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

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

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

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

     onConfigUpdate(remoteConfig, {
        next: (configUpdate) => {
           console.log("Updated keys:", configUpdate.getUpdatedKeys());
           if (configUpdate.getUpdatedKeys().has("welcome_message")) {
              activate(remoteConfig).then(() => {
              showWelcomeMessage();
              });
           }
        },
        error: (error) => {
           console.log("Config update error:", error);
        },
        complete: () => {
           console.log("Listening stopped.");
        }
     });

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

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

אם אפליקציה מאחזרת יותר מדי פעמים בפרק זמן קצר, יכול להיות שקריאות האחזור יוגבלו. במקרים כאלה, ה-SDK מחזיר שגיאת FETCH_THROTTLE. מומלץ לזהות את השגיאה הזו ולנסות שוב במצב השהיה מעריכית לפני ניסיון חוזר (exponential backoff), כלומר להמתין פרקי זמן ארוכים יותר בין בקשות אחזור עוקבות.

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

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

1. הפרמטר ב-Settings.minimumFetchIntervalMillis.
2. ערך ברירת המחדל הוא 12 שעות.