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

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

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

يمكنك أيضًا استخدام 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:

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

يمكنك أيضًا إدراج النماذج واستردادها وإرجاعها باستخدام واجهة سطر الأوامر (CLI) من 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

يمكنك استرداد قائمة بجميع الإصدارات المخزّنة من نموذج 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 النشط حاليًا برمجيًا أو يمكنك بعد ذلك تعديل ملف 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++‎