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

בחירת סוג התבנית: תבניות בצד הלקוח תבניות בצד השרת


תבניות Remote Config הן קבוצות של פרמטרים ותנאים בפורמט JSON שנוצרו בשביל פרויקט Firebase שלכם. תבניות לקוח מספקות הגדרות אישיות למכונות של אפליקציות שמטמיעות את ערכות ה-SDK של לקוח Firebase ל-Remote Config, כולל אפליקציות ל-Apple, ל-Android, לאינטרנט, ל-Flutter, ל-Unity ול-C++‎.

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

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

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

{
  "conditions": [
    {
      "name": "ios",
      "expression": "device.os == 'ios'"
    }
  ],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "ios": {
          "value": "Welcome to this sample iOS app"
        }
      }
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      }
    },
    "header_text": {
      "defaultValue": {
        "useInAppDefault": true
      }
    }
  },
  "version": {
    "versionNumber": "28",
    "updateTime": "2020-05-14T18:39:38.994Z",
    "updateUser": {
      "email": "user@google.com"
    },
    "updateOrigin": "CONSOLE",
    "updateType": "INCREMENTAL_UPDATE"
  }
}

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

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

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

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

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

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

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

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

במאמר שינוי של Remote Config באופן פרוגרמטי מוסבר איך ליצור, לשנות ולשמור תבניות באופן פרוגרמטי.

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

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

מסוף Firebase

  1. במסוף Firebase, נכנסים לדף DevOps & Engagement ‏> הגדרת תצורה מרחוק ‏> Parameters.

  2. לוחצים על סמל השעון שמוצג בפינה השמאלית העליונה.

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

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

Firebase CLI

firebase remoteconfig:versions:list

אפשר להשתמש באפשרות --limit כדי להגביל את מספר הגרסאות שמוחזרות. כדי לאחזר את כל הגרסאות, צריך להעביר את הערך "0".

Node.js

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);
});
}

Java

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

REST

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

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

{
  "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

  1. במסוף Firebase, נכנסים לדף DevOps & Engagement >‏ Remote Config >‏ Change history.

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

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

Firebase CLI

firebase remoteconfig:get -v VERSION_NUMBER

אפשר גם לכתוב את הפלט בקובץ מסוים באמצעות -o, FILENAME.

Node.js

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

// 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);
});

Java

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());

REST

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

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

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

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

מסוף Firebase

  1. במסוף Firebase, נכנסים לדף DevOps & Engagement >‏ Remote Config >‏ Change history.

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

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

Firebase CLI

firebase remoteconfig:rollback -v VERSION_NUMBER

Node.js

// 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);
  })

Java

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

REST

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

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. לוחצים על היסטוריית שינויים.

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

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

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

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

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

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

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

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

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

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

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

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

מסוף Firebase

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

  2. פותחים את תפריט ובוחרים באפשרות הורדת קובץ התצורה הנוכחי.

  3. כשמופיעה בקשה, לוחצים על הורדת קובץ תצורה, בוחרים את המיקום שבו רוצים לשמור את הקובץ ולוחצים על שמירה.

Firebase CLI

firebase remoteconfig:get -o filename

Node.js

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);
      });
}

Java

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

REST

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

הפקודה הזו מוציאה את המטען הייעודי (payload) של ה-JSON לקובץ אחד, ואת הכותרות (כולל ה-ETag) לקובץ headers נפרד.

אימות התבנית של Remote Config

אתם יכולים לאמת את העדכונים של התבניות לפני הפרסום שלהן באמצעות Firebase Admin SDK או API בארכיטקטורת REST. התבניות מאומתות גם כשמנסים לפרסם מ-CLI של Firebase או ממסוף Firebase.

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

Node.js

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);
      });
}

Java

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

REST

כדי לאמת את העדכונים בתבנית, מוסיפים את הפרמטר של כתובת ה-URL‏ ?validate_only=true לבקשת הפרסום:

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

אם התבנית אומתה בהצלחה, הפקודה curl תחזיר את תבנית ה-JSON ששלחתם, ובקובץ headers השמור תמצאו סטטוס HTTP/2‏ 200 ותג ישות (ETag) מעודכן עם הסיומת -0. אם התבנית לא אומתה, תקבלו את שגיאת האימות בתגובת ה-JSON, וקובץ ה-headers יכיל תגובה שהיא לא 200 (ולא ETag).

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

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

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

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

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

מסוף Firebase

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

  2. פותחים את התפריט ובוחרים באפשרות פרסום מקובץ.

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

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

Node.js

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);
      });
}

Java

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

REST

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

בפקודה curl, אפשר לציין את התוכן באמצעות התו "@" ואחריו שם הקובץ.

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

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

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

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

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

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

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

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

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

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

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

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

REST

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

משתמשים בערך XML,‏ PLIST או JSON בתור הערך של format, בהתאם לפורמט הקובץ שרוצים להוריד.

מסוף Firebase

  1. במסוף Firebase, נכנסים לדף DevOps & Engagement ‏> הגדרת תצורה מרחוק ‏> Parameters.

  2. פותחים את Menu ובוחרים באפשרות Download default values.

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

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