نماذج "الإعداد عن بُعد" وتحديد الإصدارات

نماذج Remote Config هي مجموعات من المَعلمات والشروط بتنسيق JSON التي أنشأتها لمشروعك على Firebase. يمكنك إنشاء نماذج للعملاء يسترجع تطبيقك القيم منها، وللخوادم يمكن لعملاء الخادم استرداد القيم منها.

يمكنك تعديل النموذج وإدارته باستخدام وحدة تحكّم Firebase التي تعرِض محتويات النموذج بتنسيق رسومي في علامتَي التبويب علامتا التبويب المَعلمات و الشروط

يمكنك أيضًا استخدام Remote Config REST API وAdmin 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:

• عرض جميع إصدارات النماذج المخزّنة
• استرداد إصدار معيّن
• الرجوع إلى إصدار محدّد من العميل
• حذف Remote Config نموذج من صفحة سجلّ التغييرات

هناك حدّ أقصى إجمالي يبلغ 300 إصدار محفوظ مدى الحياة لكلّ نوع نموذج (300 نموذج عميل و300 نموذج خادم)، بما في ذلك أرقام الإصدارات المحفوظة للنماذج المحذوفة. إذا نشرت أكثر من 300 نسخة من النموذج لكل نوع من النماذج خلال مدة إنشاء المشروع، يتم حذف النسخ الأقدم، مع الاحتفاظ بحد أقصى 300 نسخة من هذا النوع.

في كل مرة تعدّل فيها المَعلمات، تنشئ Remote Config نموذج Remote Config جديدًا بالإصدار وتخزِّن النموذج السابق كأحد الإصدارات التي يمكنك استردادها أو الرجوع إليها حسب الحاجة. يتمّ الزيادة في أرقام الإصدارات بشكل تسلسلي من القيمة الأولية التي تخزّنها Remote Config. تتضمّن جميع النماذج حقل version كما هو موضّح، والذي يحتوي على بيانات وصفية عن الإصدار المحدّد.

يمكنك حذف نماذج Remote Config حسب الحاجة من سجلّ التغييرات صفحة وحدة تحكّم 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 <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/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 <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/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 <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'

يُرجى العلم أنّ عملية التراجع هذه تؤدي إلى إنشاء إصدار جديد مرقّم. على سبيل المثال، يؤدي الرجوع من الإصدار 10 إلى الإصدار 6 إلى إنشاء نسخة جديدة من الإصدار 6، تختلف عن النسخة الأصلية فقط من حيث أنّ رقم الإصدار هو 11. سيظلّ الإصدار الأصلي 6 مخزّنًا، بافتراض أنّه لم يصل إلى تاريخ انتهاء صلاحيته، وسيصبح الإصدار 11 هو النموذج النشط.

حذف نموذج Remote Config

يمكنك حذف نماذج Remote Config من وحدة تحكّم Firebase. ل حذف نموذج Remote Config:

1. انتقِل إلى النموذج الذي تريد حذفه، وانقر على رمز more_vertالمزيد، ثم اختَر حذف.

2. عندما يُطلب منك تأكيد الحذف، انقر على حذف.

تنزيل نماذج Remote Config ونشرها

نزِّل ونشر نماذج Remote Config لدمجها في أنظمة التحكّم في المصدر وأنظمة الإنشاء، ولإجراء تعديلات تلقائية على الإعدادات، والتزامن بين المَعلمات والقيم في مشاريع متعدّدة.

يمكنك تنزيل نموذج Remote Config النشط حاليًا من وحدة تحكّم Firebase. يمكنك بعد ذلك تعديل ملف JSON الذي تم تصديره ونشره في المشروع نفسه، أو نشره في مشروع جديد أو حالي.

لنفترض أنّ لديك مشاريع متعددة تمثّل مراحل مختلفة من دورة حياة تطوير البرامج، مثل بيئات التطوير والاختبار والنشر والإنتاج. في هذه الحالة، يمكنك ترقية نموذج تم اختباره بالكامل من بيئة الاختبار إلى بيئة الإنتاج من خلال تنزيله من مشروع الاختبار ونشره في مشروع الإنتاج.

يمكنك أيضًا استخدام هذه الطريقة لنقل الإعدادات من مشروع إلى آخر، أو تعبئة مشروع جديد بالمَعلمات والقيم من مشروع تم إنشاؤه.

لا يتم تضمين المَعلمات وقيم المَعلمات التي تم إنشاؤها على وجه التحديد كخيارات في تجربة A/B Testing في النماذج التي يتم تصديرها.

لتصدير نماذج Remote Config واستيرادها:

1. نزِّل نموذج Remote Config 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

التحقّق من صحة نموذج "الإعداد عن بُعد"

تتحقّق عملية التحقّق من النموذج من الأخطاء، مثل المفاتيح المكرّرة للمَعلمات والشروط، أو أسماء الشروط غير الصالحة أو الشروط غير المتوفّرة، أو علامات ETag بتنسيق غير صحيح. على سبيل المثال، سيؤدي الطلب الذي يحتوي على عدد مفاتيح أكبر من العدد المسموح به، وهو 2000، إلى عرض رسالة الخطأ 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++