| בחירת סוג התבנית: | תבניות בצד הלקוח תבניות בצד השרת |
תבניות 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
במסוף Firebase, נכנסים לדף DevOps & Engagement > הגדרת תצורה מרחוק > Parameters.
לוחצים על סמל השעון שמוצג בפינה השמאלית העליונה.
דף היסטוריית השינויים נפתח, ומופיעה בו רשימה של כל הגרסאות השמורות של התבנית בתפריט הרשימה שמשמאל.
הפרטים שמוצגים לכל גרסה שנשמרה כוללים מידע על מקור השינויים: מסוף 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
במסוף Firebase, נכנסים לדף DevOps & Engagement > Remote Config > Change history.
כברירת מחדל, בדף מוצגת התבנית הפעילה הנוכחית. כדי לראות גרסה אחרת, בוחרים אותה בחלונית הפרטים שמשמאל.
כדי לראות השוואה מפורטת בין התבנית הפעילה לבין כל גרסה אחרת שנשמרה, מעבירים את העכבר מעל תפריט ההקשר של גרסה שלא נבחרה ובוחרים באפשרות השוואה לגרסה שנבחרה.
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
במסוף Firebase, נכנסים לדף DevOps & Engagement > Remote Config > Change history.
בפינה השמאלית העליונה של הדף, מאתרים את כפתור האפשרויות של גרסאות קודמות של התבנית שאפשר לחזור אליהן.
צריך ללחוץ ולאשר את הפעולה הזו רק אם רוצים לחזור לגרסה הזו ולהשתמש בערכים האלה באופן מיידי בכל האפליקציות והמשתמשים.
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. כדי למחוק תבנית:
במסוף Firebase, נכנסים לדף DevOps & Engagement > הגדרת תצורה מרחוק > Parameters.
לוחצים על
היסטוריית שינויים .עוברים לתבנית שרוצים למחוק, לוחצים על
אפשרויות נוספות ובוחרים באפשרות מחיקה.כשמופיעה בקשה לאשר את המחיקה, לוחצים על מחיקה.
הורדה ופרסום של Remote Config תבניות
אתם יכולים להוריד ולפרסם תבניות של Remote Config כדי לשלב אותן במערכות בקרת המקור וה-build, להפוך את עדכוני ההגדרות לאוטומטיים ולסנכרן את הפרמטרים והערכים בין כמה פרויקטים.
אתם יכולים להוריד את התבנית הפעילה של Remote Config באופן פרוגרמטי או ממסוף Firebase. אחר כך אפשר לעדכן את קובץ ה-JSON שיוצא ולפרסם אותו באותו פרויקט, או לפרסם אותו בפרויקט חדש או קיים.
לדוגמה, נניח שיש לכם כמה פרויקטים שמייצגים שלבים שונים במחזור החיים של פיתוח התוכנה, כמו סביבות פיתוח, בדיקה, Staging וייצור. במקרה כזה, אתם יכולים להעביר תבנית שנבדקה באופן מלא מסביבת ה-staging לסביבת הייצור. כדי לעשות את זה, אתם צריכים להוריד את התבנית מפרויקט ה-staging ולפרסם אותה בפרויקט הייצור.
אפשר גם להשתמש בשיטה הזו כדי להעביר הגדרות מפרויקט אחד לאחר, או לאכלס פרויקט חדש בפרמטרים ובערכים מפרויקט קיים.
פרמטרים וערכי פרמטרים שנוצרו במיוחד כווריאציות בניסוי ב-A/B Testing לא נכללים בתבניות שמייצאים.
כדי לייצא ולייבא תבניות של Remote Config:
- מורידים את התבנית הנוכחית של Remote Config.
- מאמתים את התבנית של Remote Config.
- מפרסמים את התבנית של Remote Config.
הורדת התבנית הנוכחית של Remote Config
כדי להוריד את התבנית הפעילה של Remote Config בפורמט JSON, משתמשים בקוד הבא:
מסוף Firebase
במסוף Firebase, נכנסים לדף DevOps & Engagement (DevOps ומעורבות) > Remote Config (הגדרת תצורה מרחוק) > Parameters or Conditions (פרמטרים או תנאים).
פותחים את
תפריט ובוחרים באפשרות הורדת קובץ התצורה הנוכחי.כשמופיעה בקשה, לוחצים על הורדת קובץ תצורה, בוחרים את המיקום שבו רוצים לשמור את הקובץ ולוחצים על שמירה.
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
במסוף Firebase, נכנסים לדף DevOps & Engagement (DevOps ומעורבות) > Remote Config (הגדרת תצורה מרחוק) > Parameters or Conditions (פרמטרים או תנאים).
פותחים את
התפריט ובוחרים באפשרות פרסום מקובץ.כשמופיעה בקשה, לוחצים על עיון, מנווטים אל קובץ ה-Remote Config שרוצים לפרסם, בוחרים אותו ולוחצים על בחירה.
מערכת 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
במסוף Firebase, נכנסים לדף DevOps & Engagement > הגדרת תצורה מרחוק > Parameters.
פותחים את
Menu ובוחרים באפשרות Download default values.כשמוצגת בקשה, לוחצים על כפתור הבחירה שמתאים לפורמט הקובץ שרוצים להוריד, ואז לוחצים על הורדת הקובץ.
מידע נוסף על ייבוא ערכי ברירת המחדל של Remote Config לאפליקציה זמין במאמרים הבאים: