قوالب التكوين عن بعد والإصدارات

قالب التكوين عن بعد هو مجموعة من المعلمات والشروط بتنسيق 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"
    }
  }

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

باستخدام وحدة تحكم Firebase، أو Firebase CLI، أو واجهات برمجة التطبيقات الخلفية للتكوين عن بعد، يمكنك تنفيذ مهام إدارة الإصدار التالية:

  • قم بإدراج كافة إصدارات القالب المخزنة
  • استرداد نسخة محددة
  • العودة إلى إصدار معين

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

إدارة إصدارات قالب التكوين عن بعد

يصف هذا القسم كيفية إدارة إصدارات قالب التكوين عن بعد. لمزيد من التفاصيل حول كيفية إنشاء القوالب وتعديلها وحفظها برمجيًا، راجع تعديل التكوين عن بعد برمجيًا .

قم بإدراج كافة الإصدارات المخزنة من قالب التكوين عن بعد

يمكنك استرداد قائمة بجميع الإصدارات المخزنة من قالب التكوين عن بعد. على سبيل المثال:

Node.js

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

وحدة تحكم Firebase

في علامة التبويب " المعلمات" ، حدد أيقونة "الساعة" المعروضة في أعلى اليمين. يؤدي هذا إلى فتح صفحة سجل التغيير التي تسرد جميع إصدارات القالب المخزنة في قائمة القائمة على اليمين.

تتضمن التفاصيل المعروضة لكل إصدار مخزن معلومات حول ما إذا كانت التغييرات قد نشأت من وحدة التحكم، أو من خلال REST API، أو من التراجع، أو ما إذا كانت تغييرات تدريجية من الحفظ الإجباري للقالب.

Firebase CLI

firebase remoteconfig:versions:list

استخدم الخيار --limit لتحديد عدد الإصدارات التي يتم إرجاعها. مرر "0" لجلب كافة الإصدارات.

تتضمن قائمة القوالب بيانات تعريفية لجميع الإصدارات المخزنة، بما في ذلك وقت التحديث، والمستخدم الذي قام بذلك، وما إذا كان قد تم إجراؤه عبر وحدة التحكم أو REST API. فيما يلي مثال لعنصر الإصدار:

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

استرداد إصدار محدد من قالب التكوين عن بعد

يمكنك استرداد أي إصدار مخزن محدد من قالب التكوين عن بعد. على سبيل المثال:

Node.js

قم بتمرير getTemplate() بدون أية وسائط لاسترداد أحدث إصدار من القالب، أو لاسترداد إصدار معين، استخدم getTemplateAtVersion() .

// 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

معلمة URL ?version_number صالحة فقط لعمليات GET ؛ ولا يمكنك استخدامه لتحديد أرقام الإصدارات للتحديثات. سيؤدي طلب الحصول المماثل بدون المعلمة ?version_number إلى استرداد القالب النشط الحالي.

وحدة تحكم Firebase

افتراضيًا، يعرض جزء التفاصيل في علامة تبويب محفوظات التغيير القالب النشط الحالي. لعرض تفاصيل إصدار آخر في القائمة، حدده من القائمة اليمنى.

يمكنك عرض الفرق التفصيلي بين الإصدار المحدد حاليًا وأي إصدار مخزن آخر عن طريق التمرير فوق قائمة السياق لأي إصدار غير محدد وتحديد مقارنة مع الإصدار المحدد.

Firebase CLI

firebase remoteconfig:get -v VERSION_NUMBER

اختياريًا، يمكنك كتابة الإخراج إلى ملف محدد باستخدام -o, FILENAME .

ارجع إلى إصدار مخزن محدد من قالب التكوين عن بعد

يمكنك العودة إلى أي نسخة مخزنة من القالب. على سبيل المثال:

Node.js

// 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());
  }
}

استراحة

للعودة إلى قالب التكوين عن بعد المخزن، قم بإصدار HTTP POST بالطريقة المخصصة :rollback ، وفي نص الطلب، الإصدار المحدد المطلوب تطبيقه. على سبيل المثال:

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

تحتوي الاستجابة على محتويات القالب المخزن النشط الآن، مع بيانات التعريف الخاصة بالإصدار الجديد.

وحدة تحكم Firebase

بالنسبة لإصدارات القالب السابقة المؤهلة للتراجع، يتم عرض زر خيار للرجوع إلى ذلك الإصدار في الجزء العلوي الأيسر من صفحة سجل التغيير . انقر فوق هذا وقم بتأكيده فقط إذا كنت متأكدًا من رغبتك في العودة إلى هذا الإصدار واستخدام هذه القيم على الفور لجميع التطبيقات والمستخدمين.

Firebase CLI

firebase remoteconfig:rollback -v VERSION_NUMBER

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

حذف قالب التكوين عن بعد

يمكنك حذف قوالب التكوين عن بعد من وحدة تحكم Firebase. لحذف قالب التكوين عن بعد:

  1. من صفحة معلمات التكوين عن بعد، انقر فوق تغيير السجل .

  2. قم بالتبديل إلى القالب الذي تريد حذفه، وانقر فوق المزيد ، ثم حدد حذف .

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

قم بتنزيل ونشر قوالب التكوين عن بعد

قم بتنزيل ونشر قوالب التكوين عن بعد لدمجها في التحكم بالمصدر الخاص بك وبناء الأنظمة، وأتمتة تحديثات التكوين، والحفاظ على مزامنة المعلمات والقيم عبر مشاريع متعددة.

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

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

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

لا يتم تضمين المعلمات وقيم المعلمات التي تم إنشاؤها خصيصًا كمتغيرات في تجربة اختبار A/B في القوالب التي تم تصديرها.

لتصدير واستيراد قوالب التكوين عن بعد:

  1. قم بتنزيل قالب تكوين التكوين عن بعد الحالي .
  2. التحقق من صحة قالب التكوين عن بعد .
  3. نشر قالب التكوين عن بعد .

قم بتنزيل قالب التكوين عن بعد الحالي

يمكنك تنزيل قالب Remote Config الحالي والنشط برمجيًا، أو باستخدام وحدة تحكم Firebase.

استخدم الأوامر التالية لتنزيل قالب التكوين عن بعد النشط بتنسيق JSON:

Node.js

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

يقوم هذا الأمر بإخراج حمولة JSON إلى ملف واحد، والرؤوس (بما في ذلك ETag) إلى ملف headers منفصل.

وحدة تحكم Firebase

  1. من علامة التبويب "معلمات أو شروط التكوين عن بعد" ، افتح قائمة وحدد تنزيل ملف التكوين الحالي .
  2. عندما يُطلب منك ذلك، انقر فوق "تنزيل ملف التكوين" ، واختر الموقع الذي تريد حفظ الملف فيه، ثم انقر فوق "حفظ" .

Firebase CLI

firebase remoteconfig:get -o filename

التحقق من صحة قالب التكوين عن بعد

يمكنك التحقق من صحة تحديثات القالب قبل نشرها باستخدام Firebase Admin SDK أو REST API. يتم أيضًا التحقق من صحة القوالب عند محاولة النشر من Firebase CLI أو وحدة تحكم Firebase.

تتحقق عملية التحقق من صحة القالب من وجود أخطاء مثل المفاتيح المكررة للمعلمات والشروط، أو أسماء الشروط غير الصالحة أو الشروط غير الموجودة، أو علامات ETags المنسقة بشكل غير صحيح. على سبيل المثال، قد يؤدي الطلب الذي يحتوي على أكثر من العدد المسموح به من المفاتيح — 2000 — إلى إرجاع رسالة الخطأ، Param count too large .

Node.js

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());
  }
}

استراحة

التحقق من صحة تحديثات القالب عن طريق إلحاق معلمة URL ?validate_only=true بطلب النشر الخاص بك:

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

إذا تم التحقق من صحة القالب الخاص بك بنجاح، فسيقوم أمر الضفيرة بإرجاع قالب JSON الذي أرسلته، وفي ملف headers المحفوظ، ستجد حالة HTTP/2 200 وETag محدثة مع اللاحقة -0 . إذا لم يتم التحقق من صحة القالب الخاص بك، فسوف تتلقى خطأ التحقق من الصحة في استجابة JSON وسيحتوي ملف headers الخاص بك على استجابة غير 200 (ولا يوجد ETag).

نشر قالب التكوين عن بعد

بعد تنزيل القالب وإجراء أي تغييرات مطلوبة على محتوى JSON والتحقق من صحته، يمكنك نشره في مشروع.

يؤدي نشر القالب إلى استبدال قالب التكوين الموجود بالكامل بالملف المحدث وزيادة إصدار القالب بمقدار واحد. نظرًا لأنه تم استبدال التكوين بالكامل، إذا قمت بحذف معلمة من ملف JSON ونشرتها، فسيتم حذف المعلمة من الخادم ولن تعد متاحة للعملاء.

بعد النشر، تصبح التغييرات التي يتم إجراؤها على المعلمات والقيم متاحة على الفور لتطبيقاتك ومستخدميك. إذا لزم الأمر، يمكنك العودة إلى الإصدار السابق .

استخدم الأوامر التالية لنشر القالب الخاص بك:

Node.js

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

بالنسبة لأمر curl هذا، يمكنك تحديد المحتوى باستخدام الحرف "@"، متبوعًا باسم الملف.

وحدة تحكم Firebase

  1. من علامة التبويب "معلمات أو شروط التكوين عن بعد" ، افتح قائمة وحدد "نشر من ملف" .
  2. عندما يُطلب منك ذلك، انقر فوق "استعراض" ، وانتقل إلى ملف "التكوين عن بُعد" الذي تريد نشره وحدده، ثم انقر فوق "تحديد" .
  3. سيتم التحقق من صحة الملف، وفي حالة نجاحه، يمكنك النقر فوق "نشر" لجعل التكوين متاحًا على الفور لتطبيقاتك ومستخدميك.

يتم تضمين تخصيصات وشروط التكوين عن بعد في القوالب التي تم تنزيلها، لذا من المهم أن تكون على دراية بالقيود التالية عند محاولة النشر إلى مشروع مختلف:

  • لا يمكن استيراد التخصيصات من مشروع إلى آخر.

    على سبيل المثال، إذا قمت بتمكين التخصيصات في مشروعك وقمت بتنزيل قالب وتحريره، فيمكنك نشره على نفس المشروع، ولكن لا يمكنك نشره إلى مشروع مختلف إلا إذا قمت بحذف التخصيصات من القالب.

  • يمكن استيراد الشروط من مشروع إلى آخر، ولكن لاحظ أن أي قيم شرطية محددة (مثل معرفات التطبيق أو الجماهير) يجب أن تكون موجودة في المشروع المستهدف قبل النشر.

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

  • إذا كان القالب الذي تخطط لنشره يحتوي على شروط تعتمد على Google Analytics، فيجب تمكين Analytics في المشروع المستهدف.

قم بتنزيل الإعدادات الافتراضية لقالب التكوين عن بُعد

نظرًا لأن تطبيقك قد لا يكون متصلاً دائمًا بالإنترنت، فيجب عليك تكوين القيم الافتراضية للتطبيق من جانب العميل لجميع معلمات التكوين عن بُعد. يجب عليك أيضًا مزامنة القيم الافتراضية لعميل التطبيق الخاص بك بشكل دوري وقيم المعلمات الافتراضية للواجهة الخلفية للتكوين عن بعد، لأنها قد تتغير بمرور الوقت.

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

يمكنك تنزيل هذه الملفات بتنسيق 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'

استخدم XML أو PLIST أو JSON كقيمة format ، اعتمادًا على تنسيق الملف الذي تريد تنزيله.

وحدة تحكم Firebase

  1. في علامة التبويب "المعلمات" ، افتح قائمة ، وحدد تنزيل القيم الافتراضية .
  2. عندما يُطلب منك ذلك، انقر فوق زر الاختيار الذي يتوافق مع تنسيق الملف الذي تريد تنزيله، ثم انقر فوق تنزيل الملف .

لمزيد من المعلومات حول استيراد القيم الافتراضية للتكوين عن بعد إلى تطبيقك، راجع: