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

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

يمكنك استخدام وحدة تحكّم Firebase لتعديل النموذج وإدارته. انتقِل إلى DevOps & Engagement > Remote Config لعرض محتوى النموذج بتنسيق رسومي في صفحة المَعلمات وصفحة الشروط

يمكنك أيضًا استخدام 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 (انتقِل إلى DevOps ومعدّل الاهتمام بالتطبيق > الإعداد عن بُعد):

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

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

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

يمكنك حذف نماذج Remote Config حسب الحاجة في صفحة عمليات DevOps ومعدّل الاهتمام بالتطبيق > الإعداد عن بُعد > سجل التغييرات في وحدة تحكّم Firebase.

إدارة نُسخ نموذج 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

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

```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 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}'

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

حذف نموذج Remote Config

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

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة عمليات التطوير والتشغيل والتفاعل > Remote Config > المَعلمات.

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 النشط بتنسيق 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++‎