שינוי הגדרת התצורה מרחוק באופן פרוגרמטי

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

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

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

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

  

בקטעים הבאים במדריך מפורטות הפעולות שאפשר לבצע באמצעות ממשקי ה-API לקצה העורפי של Remote Config. כדי לראות קוד שמבצע את המשימות האלה דרך ה-API ל-REST, אפשר לעיין באחת מהאפליקציות לדוגמה הבאות:

• מדריך למתחילים ב-Java ל-Firebase Remote Config API ל-REST
• מדריך למתחילים ב-Node.js ל-Firebase Remote Config REST API
• תחילת העבודה עם Firebase Remote Config API ל-REST ב-Python

שינוי של הגדרת תצורה מרחוק באמצעות Firebase Admin SDK

Admin SDK היא קבוצה של ספריות שרת שמאפשרות לכם ליצור אינטראקציה עם Firebase מסביבות בעלות הרשאות. בנוסף לביצוע עדכונים ב-Remote Config, באמצעות Admin SDK אפשר ליצור ולאמת אסימוני אימות של Firebase, לקרוא ולכתוב ב-Realtime Database וכן הלאה. למידע נוסף על הדרישות המוקדמות וההגדרה של Admin SDK, ראו הוספת Firebase Admin SDK לשרת.

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

אתחול ה-SDK והרשאה לבקשות API

כשמאתחלים את Admin SDK ללא פרמטרים, ה-SDK משתמש ב-Application Default Credentials של Google וקורא אפשרויות ממשתנה הסביבה FIREBASE_CONFIG. אם התוכן של המשתנה FIREBASE_CONFIG מתחיל ב-{, הוא ינותח כאובייקט JSON. אחרת, ה-SDK יחשוב שהמחרוזת היא השם של קובץ JSON שמכיל את האפשרויות.

לדוגמה:

const admin = require('firebase-admin');
admin.initializeApp();

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

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

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

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

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

כדי לקבל את התבנית:

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

שינוי הפרמטרים של Remote Config

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

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

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

שינוי התנאים של Remote Config

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

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שינוי של Remote Config באמצעות ה-API ל-REST

בקטע הזה מתוארות היכולות העיקריות של API ל-REST של Remote Config בכתובת https://firebaseremoteconfig.googleapis.com. פרטים מלאים זמינים בהפניית ה-API.

קבלת אסימון גישה לאימות ולאישור בקשות API

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

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

כדי ליצור קובץ מפתח פרטי לחשבון השירות:

1. במסוף Firebase, פותחים את Settings (הגדרות) > Service Accounts (חשבונות שירות).

2. לוחצים על Generate New Private Key (יצירת מפתח פרטי חדש) ואז על Generate Key (יצירת מפתח) כדי לאשר.

3. מאחסנים באופן מאובטח את קובץ ה-JSON שמכיל את המפתח.

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

כדי להגדיר את משתנה הסביבה:

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

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

אחרי שתשלימו את השלבים שלמעלה, השירות Application Default Credentials (ADC) יוכל לקבוע באופן משתמע את פרטי הכניסה שלכם, כך שתוכלו להשתמש בפרטי הכניסה של חשבון השירות בזמן בדיקה או הפעלה בסביבות שאינן של Google.

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

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

public static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
FirebaseRemoteConfigSnippets.java

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

כדי לתת הרשאת גישה ל-Remote Config, צריך לבקש את ההיקף https://www.googleapis.com/auth/firebase.remoteconfig.

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

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

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

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

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

משתמשים בפקודות הבאות:

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

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

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

אם רוצים, אפשר לאמת את העדכונים לפני הפרסום שלהם. כדי לאמת את עדכוני התבניות, מוסיפים לבקשת הפרסום את הפרמטר של כתובת ה-URL ?validate_only=true. אם התשובה כוללת את קוד הסטטוס 200 ואת ה-etag המעודכן עם הסיומת -0, סימן שהעדכון אומת בהצלחה. כל תגובה שאינה 200 מציינת שנתוני ה-JSON מכילים שגיאות שצריך לתקן לפני הפרסום.

עדכון התבנית של Remote Config

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

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

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

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

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

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

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

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

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

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

שינוי התנאים של Remote Config

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

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

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

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

קודי שגיאה של HTTP

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

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

שימוש ב-ETag ועדכונים מאולצים

ב-API ל-REST של Remote Config נעשה שימוש בתג ישות (ETag) כדי למנוע מרוץ תהליכים ועדכונים חופפים של משאבים. למידע נוסף על תגי ETag, ראו ETag – HTTP.

ב-API ל-REST, Google ממליצה לשמור במטמון את ה-ETag שסופק על ידי הפקודה GET האחרונה, ולהשתמש בערך ה-ETag הזה בכותרת הבקשה If-Match כשמפעילים פקודות PUT. אם הפקודה PUT מובילה לקוד סטטוס HTTPS‏ 409, צריך להפעיל שוב את הפקודה GET כדי לקבל תבנית ו-ETag חדשים לשימוש בפקודה הבאה של PUT.

אפשר לעקוף את ה-ETag ואת ההגנה שהוא מספק על ידי אילוץ העדכון של התבנית Remote Config באופן הבא: If-Match: * עם זאת, לא מומלץ להשתמש בגישה הזו כי היא עלולה לגרום לאובדן עדכונים של התבנית Remote Config אם כמה לקוחות מעדכנים את התבנית Remote Config. סוג כזה של התנגשויות יכול להתרחש עם כמה לקוחות שמשתמשים ב-API, או עם עדכונים סותרים מלקוחות API וממשתמשי מסוף Firebase.

למידע נוסף על ניהול גרסאות של תבניות Remote Config, ראו תבניות וניהול גרסאות של Remote Config.