مدیریت الگوهای کارخواه «پیکربندی از راه دور» و نسخه‌گذاری

Remote Config الگوها مجموعه‌ای از پارامترها و شرایط با قالب JSON هستند که برای پروژه Firebase شما ایجاد شده‌اند. الگوهای کارخواه پیکربندی‌ها را به نمونه‌های برنامه‌ای ارائه می‌دهند که کیت‌های توسعه نرم‌افزار کارخواه Firebase را برای Remote Config پیاده‌سازی می‌کنند، ازجمله برنامه‌های Apple،‏ Android،‏ Web،‏ Flutter،‏ Unity، و C++.

می‌توانید از کنسول Firebase برای اصلاح و مدیریت الگوی کارخواهتان استفاده کنید. به DevOps و تعامل > پیکربندی از راه دور بروید تا محتوای الگو را در قالب گرافیکی در صفحه پارامترها و صفحه شرایط مشاهده کنید.

همچنین می‌توانید از Remote Config REST API و Admin SDK یا Firebase CLI برای اصلاح و مدیریت الگوی کارخواه خود استفاده کنید.

در اینجا نمونه‌ای از فایل الگوی کارخواه آورده شده است:

{
  "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 و تعامل > پیکربندی از راه دور بروید):

• فهرست کردن همه نسخه‌های ذخیره‌شده الگو
• بازیابی نسخه‌ای خاص
• برگشتن به نسخه مشتری خاص
• Remote Config الگو را از صفحه «سابقه تغییرات» حذف کنید.

همچنین می‌توانید بااستفاده از میاناهای برنامه‌سازی کاربردی Firebase CLI و Remote Config backend، الگوها را فهرست کنید، الگوها را بازیابی کنید، و الگوها را برگردانید.

درمجموع محدودیت ۳۰۰ نسخه ذخیره‌شده مادام‌العمر برای هر نوع الگو وجود دارد (۳۰۰ الگوی کارخواه و ۳۰۰ الگوی سرور)، که شامل شماره نسخه‌های ذخیره‌شده برای الگوهای حذف‌شده می‌شود. اگر در طول عمر پروژه بیش‌از ۳۰۰ نسخه الگو برای هر نوع الگو منتشر کنید، نسخه‌های اولیه حذف می‌شوند و حداکثر ۳۰۰ نسخه از آن نوع حفظ می‌شود.

هربار که پارامترها را به‌روز می‌کنید، Remote Config الگوی Remote Config نسخه‌دار جدیدی ایجاد می‌کند و الگوی قبلی را به‌عنوان نسخه‌ای ذخیره می‌کند که می‌توانید درصورت نیاز آن را بازیابی کنید یا به آن برگردید. شماره‌های نسخه به‌صورت متوالی از مقدار اولیه ذخیره‌شده توسط Remote Config افزایش می‌یابند. همه الگوها شامل یک فیلد version هستند که فراداده مربوط به آن نسخه خاص را دربرمی‌گیرد.

درصورت نیاز می‌توانید الگوهای Remote Config را در صفحه DevOps و تعامل > پیکربندی از راه دور > سابقه تغییر در کنسول Firebase حذف کنید.

مدیریت کردن نسخه‌های الگوی Remote Config

این بخش نحوه مدیریت نسخه‌های الگوی 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

فهرست الگوها شامل فراداده برای همه نسخه‌های ذخیره‌شده است، ازجمله زمان به‌روزرسانی، کاربری که آن را انجام داده است، و نحوه انجام آن. در اینجا مثالی از عنصر نسخه آورده شده است:

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

توجه داشته باشید که این عملیات بازگرداندن درواقع نسخه شماره‌دار جدیدی ایجاد می‌کند. برای مثال، بازگرداندن از نسخه ۱۰ به نسخه ۶ به‌طور مؤثری کپی جدیدی از نسخه ۶ ایجاد می‌کند که تنها تفاوت آن با نسخه اصلی این است که شماره نسخه آن ۱۱ است. نسخه اصلی ۶ هنوز ذخیره است، با فرض اینکه به تاریخ انقضایش نرسیده باشد، و نسخه ۱۱ به الگوی فعال تبدیل می‌شود.

حذف کردن الگوی Remote Config

می‌توانید الگوهای Remote Config را بااستفاده از کنسول Firebase حذف کنید. نحوه حذف الگو در اینجا آمده است:

1. در کنسول Firebase، به صفحه DevOps و تعامل > پیکربندی از راه دور > پارامترها بروید.

2. روی history سابقه تغییر کلیک کنید.

3. به الگویی که می‌خواهید حذف کنید بروید، روی more_vert بیشتر کلیک کنید، سپس حذف را انتخاب کنید.

4. وقتی از شما خواسته شد حذف را تأیید کنید، روی حذف کلیک کنید.

بارگیری و انتشار الگوهای Remote Config

الگوهای Remote Config را بارگیری و منتشر کنید تا آن‌ها را در سیستم‌های ساخت و کنترل منبع خود ادغام کنید، به‌روزرسانی‌های پیکربندی را خودکار کنید، و پارامترها و مقادیر را در چندین پروژه همگام‌سازی کنید.

می‌توانید الگوی Remote Config فعال کنونی را به‌صورت برنامه‌نویسی‌شده یا از کنسول Firebase بارگیری کنید. سپس می‌توانید فایل JSON صادرشده را به‌روز کنید و آن را در همان پروژه منتشر کنید، یا آن را در پروژه جدید یا موجودی منتشر کنید.

برای مثال، فرض کنید چند پروژه دارید که مراحل مختلف چرخه حیات توسعه نرم‌افزارتان را نشان می‌دهند، مثل محیط‌های توسعه، آزمایش، آماده‌سازی، و تولید. در این حالت، می‌توانید الگوی کاملاً آزمایش‌شده‌ای را از محیط آماده‌سازی به محیط تولید ارتقا دهید. برای این کار، الگو را از پروژه آماده‌سازی بارگیری کنید و آن را در پروژه تولید منتشر کنید.

همچنین می‌توانید از این روش برای انتقال پیکربندی‌ها از یک پروژه به پروژه دیگر یا پر کردن پروژه جدید با پارامترها و مقادیر یک پروژه ایجادشده استفاده کنید.

پارامترها و مقادیر پارامتر که به‌طور خاص به‌عنوان متغیر در آزمایش A/B Testing ایجاد شده‌اند در الگوهای صادرشده گنجانده نمی‌شوند.

برای صادر کردن و وارد کردن الگوهای Remote Config:

1. الگوی Remote Config فعلی را بارگیری کنید.
2. الگوی Remote Config را اعتبارسنجی کنید.
3. الگوی Remote Config را منتشر کنید.

بارگیری الگوی 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

اعتبارسنجی الگوی Remote Config

می‌توانید به‌روزرسانی‌های الگو را قبل‌از انتشار بااستفاده از Firebase Admin SDK یا REST API اعتبارسنجی کنید. وقتی می‌خواهید ازطریق CLI Firebase یا کنسول Firebase منتشر کنید، الگوها نیز اعتبارسنجی می‌شوند.

فرایند اعتبارسنجی الگو خطاهایی مانند کلیدهای تکراری برای پارامترها و شرایط، نام‌های شرط نامعتبر یا شرایط غیرموجود، یا ETags با قالب‌بندی نادرست را بررسی می‌کند. برای مثال، درخواستی که حاوی بیش‌از تعداد مجاز کلیدها (۲۰۰۰) باشد، پیام خطای 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 همگام‌سازی شده‌اند.

در اینجا نحوه بارگیری فایلی که حاوی پیش‌فرض‌های الگو است آورده شده است:

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++‎