תבניות הגדרת תצורה מרחוק וניהול גרסאות

תבניות Remote Config הן קבוצות של פרמטרים ותנאים בפורמט JSON שיצרתם עבור פרויקט Firebase. אפשר ליצור תבניות לקוח, שהאפליקציה שולפת מהן ערכים, ותבניות שרת, ששרתי לקוח יכולים לשלוף מהן ערכים.

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

אפשר גם להשתמש ב-Remote Config API בארכיטקטורת REST וב-SDK לאדמינים או ב-Firebase CLI כדי לשנות ולנהל את תבנית הלקוח.

דוגמה לקובץ תבנית של שרת:

{
  "parameters": {
    "preamble_prompt": {
      "defaultValue": {
        "value": "You are a helpful assistant who knows everything there is to know about Firebase! "
      },
      "description": "Add this prompt to the user's prompt",
      "valueType": "STRING"
    },
    "model_name": {
      "defaultValue": {
        "value": "gemini-pro-test"
      },
      "valueType": "STRING"
    },
    "generation_config": {
      "defaultValue": {
        "value": "{\"temperature\": 0.9, \"maxOutputTokens\": 2048, \"topP\": 0.9, \"topK\": 20}"
      },
      "valueType": "JSON"
    },
  },
  "version": {
    "versionNumber": "19",
    "isLegacy": true
  }
}

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

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

יש מגבלה כוללת של 300 גרסאות מאוחסנות לכל סוג תבנית (300 תבניות לקוח ו-300 תבניות שרת), כולל מספרי גרסאות מאוחסנים של תבניות שנמחקו. אם מפרסמים יותר מ-300 גרסאות של תבנית לכל סוג תבנית במהלך חיי הפרויקט, הגרסאות המוקדמות ביותר נמחקות, כך שיישארו לכל היותר 300 גרסאות מהסוג הזה.

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

אפשר למחוק תבניות Remote Config לפי הצורך בדף היסטוריית שינויים בDevOps & Engagement > הגדרת תצורה מרחוק >

ניהול גרסאות של תבניות Remote Config

בקטע הזה מוסבר איך לנהל גרסאות של Remote Configתבנית.

רשימה של כל הגרסאות השמורות של התבנית Remote Config

אפשר לאחזר רשימה של כל הגרסאות השמורות של תבנית Remote Config. כך עושים את זה:

firebase remoteconfig:versions:list

function listAllVersions() {
  admin.remoteConfig().listVersions()
    .then((listVersionsResult) => {
      console.log("Successfully fetched the list of versions");
      listVersionsResult.versions.forEach((version) => {
        console.log('version', JSON.stringify(version));
      });
    })
    .catch((error) => {
      console.log(error);
    });
}

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:listVersions

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

```json
{
  "versions": [{
    "version_number": "6",
    "update_time": "2022-05-12T02:38:54Z",
    "update_user": {
      "name": "Jane Smith",
      "email": "jane@developer.org",
      "imageUrl": "https://lh3.googleusercontent.com/a-/..."
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]
}
```

אחזור של גרסה ספציפית של תבנית Remote Config

אפשר לאחזר כל גרסה ספציפית של תבנית Remote Config שאוחסנה. כך מאחזרים גרסה שמורה של תבנית:

firebase remoteconfig:get -v VERSION_NUMBER

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
  .then((template) => {
    console.log("Successfully fetched the template with ETag: " + template.etag);
  })
  .catch((error) => {
    console.log(error);
  });

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig?version_number=6

חזרה לגרסה ספציפית של תבנית Remote Config שנשמרה

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

firebase remoteconfig:rollback -v VERSION_NUMBER

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

curl --compressed -D headers -H "Authorization: Bearer token" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:rollback -d '{"version_number": 6}'

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

מחיקת תבנית Remote Config

אפשר למחוק תבניות Remote Config באמצעות מסוף Firebase. כך מוחקים תבנית:

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

2. לוחצים על history היסטוריית שינויים.

3. עוברים לתבנית שרוצים למחוק, לוחצים על more_vert אפשרויות נוספות ובוחרים באפשרות מחיקה.

4. כשמופיעה בקשה לאישור המחיקה, לוחצים על מחיקה.

הורדה ופרסום של תבניות Remote Config

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

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

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

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

פרמטרים וערכי פרמטרים שנוצרו במיוחד כווריאציות בניסוי A/B Testing לא נכללים בתבניות שמיוצאות.

כדי לייצא ולייבא תבניות של Remote Config:

1. מורידים את תבנית ההגדרות הנוכחית Remote Config.
2. מאמתים את התבנית Remote Config.
3. פרסום התבנית של Remote Config.

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

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

firebase remoteconfig:get -o filename

function getTemplate() {
  var config = admin.remoteConfig();
  config.getTemplate()
      .then(function (template) {
        console.log('ETag from server: ' + template.etag);
        var templateStr = JSON.stringify(template);
        fs.writeFileSync('config.json', templateStr);
      })
      .catch(function (err) {
        console.error('Unable to get template');
        console.error(err);
      });
}

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

אימות תבנית הגדרת תצורה מרחוק

תהליך האימות של התבנית בודק אם יש שגיאות כמו מפתחות כפולים לפרמטרים ולתנאים, שמות תנאים לא חוקיים או תנאים שלא קיימים, או תגי ET שמופיעים בפורמט שגוי. לדוגמה, אם בקשה מכילה יותר ממספר המפתחות המותר – 2, 000 – תוחזר הודעת השגיאה Param count too large.

function validateTemplate(template) {
  admin.remoteConfig().validateTemplate(template)
      .then(function (validatedTemplate) {
        // The template is valid and safe to use.
        console.log('Template was valid and safe to use');
      })
      .catch(function (err) {
        console.error('Template is invalid and cannot be published');
        console.error(err);
      });
}

try {
  Template validatedTemplate = FirebaseRemoteConfig.getInstance()
          .validateTemplateAsync(template).get();
  System.out.println("Template was valid and safe to use");
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Template is invalid and cannot be published");
    System.out.println(rcError.getMessage());
  }
}

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig?validate_only=true -d @filename

פרסום תבנית Remote Config

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

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

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

כדי לפרסם את התבנית, משתמשים בפקודות הבאות:

function publishTemplate() {
  var config = admin.remoteConfig();
  var template = config.createTemplateFromJSON(
      fs.readFileSync('config.json', 'UTF8'));
  config.publishTemplate(template)
      .then(function (updatedTemplate) {
        console.log('Template has been published');
        console.log('ETag from server: ' + updatedTemplate.etag);
      })
      .catch(function (err) {
        console.error('Unable to publish template.');
        console.error(err);
      });
}

try {
  Template publishedTemplate = FirebaseRemoteConfig.getInstance()
          .publishTemplateAsync(template).get();
  System.out.println("Template has been published");
  // See the ETag of the published template.
  System.out.println("ETag from server: " + publishedTemplate.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Unable to publish template.");
    System.out.println(rcError.getMessage());
  }
}

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename

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

• אי אפשר לייבא התאמות אישיות מפרויקט לפרויקט.

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

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

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

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

הורדת ברירות המחדל של תבנית Remote Config

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

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

אפשר להוריד את הקבצים האלה בפורמט XML לאפליקציות ל-Android, בפורמט plist לאפליקציות ל-iOS ובפורמט JSON לאפליקציות אינטרנט.

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

כך מורידים קובץ שמכיל את ברירות המחדל של התבנית:

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

מידע נוסף על ייבוא ערכי ברירת מחדל של Remote Config לאפליקציה

• הגדרת ערכי ברירת מחדל של פרמטרים באפליקציה ל-Android

• הגדרת ערכי ברירת מחדל של פרמטרים באפליקציה ל-iOS

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

• הגדרת ערכי ברירת מחדל של פרמטרים באפליקציה ב-Unity

• הגדרת ערכי ברירת מחדל של פרמטרים באפליקציה ל-C++‎