إدارة نماذج عملاء "الإعداد عن بُعد" وإصداراتها

نماذج Remote Config هي مجموعات من المَعلمات والشروط بتنسيق JSON تم إنشاؤها لمشروع Firebase. توفّر نماذج العملاء الإعدادات لمثيلات التطبيقات التي تستخدم حِزم تطوير البرامج (SDK) لعملاء Firebase في Remote Config، بما في ذلك تطبيقات Apple وAndroid والويب وFlutter وUnity وC++.

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

يمكنك أيضًا استخدام واجهة برمجة التطبيقات REST API في Remote Config وAdmin SDK أو واجهة سطر الأوامر (CLI) في Firebase لتعديل نموذج العميل وإدارته.

في ما يلي مثال على ملف نموذج عميل:

{
  "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 من صفحة "سجلّ التغييرات".

يمكنك أيضًا عرض النماذج واستردادها والتراجع عنها باستخدام واجهة سطر الأوامر (CLI) في Firebase وواجهات برمجة التطبيقات في الخلفية في Remote Config.

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

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

يمكنك حذف نماذج Remote Config حسب الحاجة في DevOps & Engagement > الإعداد عن بُعد > صفحة سجلّ التغييرات في وحدة تحكّم 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}'

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

حذف نموذج Remote Config

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

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

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. يتم أيضًا التحقّق من صحة النماذج عند محاولة النشر من واجهة سطر أوامر Firebase أو وحدة تحكّم Firebase.

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