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

عند استخدام وحدة تحكم Firebase أو واجهات برمجة التطبيقات الخلفية للتكوين عن بعد ، يمكنك تحديد معلمة واحدة أو أكثر (أزواج قيمة المفتاح) وتوفير القيم الافتراضية داخل التطبيق لتلك المعلمات. يمكنك تجاوز القيم الافتراضية داخل التطبيق عن طريق تحديد قيم المعلمات من جانب الخادم. مفاتيح المعلمات وقيم المعلمات عبارة عن سلاسل، ولكن يمكن تحويل قيم المعلمات كأنواع بيانات أخرى عند استخدام هذه القيم في تطبيقك.

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

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

الشروط والقواعد والقيم الشرطية

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

على سبيل المثال، يمكن للمعلمة التي تحدد صفحة البداية للتطبيق أن تعرض صورًا مختلفة بناءً على نوع نظام التشغيل باستخدام القاعدة البسيطة if device_os = Android :

لقطة شاشة لمعلمة "splash_page" في وحدة تحكم Firebase توضح قيمتها الافتراضية لنظام التشغيل iOS والقيمة الشرطية لنظام Android

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

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

أولوية قيمة المعلمة

قد تحتوي المعلمة على عدة قيم شرطية مرتبطة بها. تحدد القواعد التالية القيمة التي يتم جلبها من Remote Config Server، والقيمة المستخدمة في مثيل تطبيق معين في وقت معين:

يتم جلب قيم المعلمات من جانب الخادم وفقًا لقائمة الأولويات التالية

  1. أولاً، يتم تطبيق القيم الشرطية، إن وجدت، والتي تحتوي على شروط يتم تقييمها على أنها true لمثيل تطبيق معين. إذا تم تقييم عدة شروط على أنها true ، فإن الشرط الأول (العلوي) الموضح في واجهة مستخدم وحدة تحكم Firebase له الأولوية، ويتم توفير القيم الشرطية المرتبطة بهذا الشرط عندما يجلب التطبيق القيم من الواجهة الخلفية. يمكنك تغيير أولوية الشروط عن طريق سحب وإسقاط الشروط في علامة تبويب الشروط .

  2. إذا لم تكن هناك قيم شرطية بشروط يتم تقييمها على أنها true ، فسيتم توفير القيمة الافتراضية من جانب الخادم عندما يجلب التطبيق القيم من الواجهة الخلفية. إذا لم تكن المعلمة موجودة في الواجهة الخلفية، أو إذا تم تعيين القيمة الافتراضية على Use in-app default ، فلن يتم توفير قيمة لتلك المعلمة عندما يقوم التطبيق بجلب القيم.

في تطبيقك، يتم إرجاع قيم المعلمات من خلال أساليب get وفقًا لقائمة الأولويات التالية

  1. إذا تم جلب قيمة من الواجهة الخلفية ثم تنشيطها، فسيستخدم التطبيق القيمة التي تم جلبها. قيم المعلمات المنشطة ثابتة.
  2. إذا لم يتم جلب أي قيمة من الواجهة الخلفية، أو إذا لم يتم تنشيط القيم التي تم جلبها من الواجهة الخلفية للتكوين عن بعد، فسيستخدم التطبيق القيمة الافتراضية داخل التطبيق.

    لمزيد من المعلومات حول الحصول على القيم الافتراضية وتعيينها، راجع تنزيل الإعدادات الافتراضية لقالب التكوين عن بُعد .

  3. إذا لم يتم تعيين قيمة افتراضية داخل التطبيق، فسيستخدم التطبيق قيمة نوع ثابتة (مثل 0 لـ int و false لـ boolean ).

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

رسم تخطيطي يوضح التدفق الموصوف في القوائم المرتبة أعلاه

أنواع بيانات قيمة المعلمة

يتيح لك Remote Config تحديد نوع بيانات لكل معلمة، والتحقق من صحة جميع القيم من جانب الخادم مقابل هذا النوع قبل تحديث القالب. يتم تخزين نوع البيانات وإعادته بناءً على طلب getRemoteConfig .

الأنواع المدعومة حاليًا هي:

  • String
  • Boolean
  • Number
  • JSON

في واجهة مستخدم وحدة تحكم Firebase، يمكن تحديد نوع البيانات من القائمة المنسدلة بجوار مفتاح المعلمة. في REST API، يمكن تعيين الأنواع باستخدام حقل value_type داخل كائن المعلمة.

مجموعات المعلمة

يتيح لك Remote Config تجميع المعلمات معًا للحصول على واجهة مستخدم ونموذج ذهني أكثر تنظيمًا.

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

يمكنك إنشاء مجموعات معلمات باستخدام وحدة تحكم Firebase أو Remote Config REST API. كل مجموعة معلمات تقوم بإنشائها لها اسم فريد في قالب التكوين عن بعد. عند إنشاء مجموعات المعلمات، ضع في اعتبارك ما يلي:

  • يمكن تضمين المعلمات في مجموعة واحدة فقط في أي وقت، ويجب أن يظل مفتاح المعلمة فريدًا عبر جميع المعلمات.
  • تقتصر أسماء مجموعات المعلمات على 256 حرفًا.
  • إذا كنت تستخدم كلاً من REST API ووحدة تحكم Firebase، فتأكد من تحديث أي منطق REST API للتعامل مع مجموعات المعلمات عند النشر.

قم بإنشاء أو تعديل مجموعات المعلمات باستخدام وحدة تحكم Firebase

يمكنك تجميع المعلمات في علامة التبويب "المعلمات" بوحدة تحكم Firebase. لإنشاء مجموعة أو تعديلها:

  1. حدد إدارة المجموعات .
  2. حدد خانات الاختيار للمعلمات التي تريد إضافتها وحدد نقل إلى المجموعة .
  3. حدد مجموعة موجودة، أو قم بإنشاء مجموعة جديدة عن طريق إدخال الاسم والوصف، ثم تحديد إنشاء مجموعة جديدة . بعد حفظ المجموعة، تصبح متاحة للنشر باستخدام زر نشر التغييرات .

إنشاء مجموعات برمجياً

توفر Remote Config REST API طريقة تلقائية لإنشاء مجموعات المعلمات ونشرها. بافتراض أنك على دراية بـ REST وتم إعدادك للسماح بالطلبات إلى واجهة برمجة التطبيقات (API)، يمكنك تنفيذ الخطوات التالية لإدارة المجموعات برمجيًا:

  1. استرداد القالب الحالي
  2. أضف كائنات JSON لتمثيل مجموعات المعلمات الخاصة بك
  3. انشر مجموعات المعلمات باستخدام طلب HTTP PUT.

يحتوي كائن parameterGroups على مفاتيح المجموعة، مع وصف متداخل وقائمة من المعلمات المجمعة. لاحظ أن كل مفتاح مجموعة يجب أن يكون فريدًا عالميًا.

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

{
  "parameters": {},
  "version": {
    "versionNumber": "1",

    …


  },
  "parameterGroups": {
    "new menu": {
      "description": "New Menu",
      "parameters": {
        "pumpkin_spice_season": {
          "defaultValue": {
            "value": "true"
          },
          "description": "Whether it's currently pumpkin spice season."
        }
      }
    }
  }
}

أنواع قواعد الشرط

أنواع القواعد التالية مدعومة في وحدة تحكم Firebase. تتوفر وظيفة مكافئة في Remote Config REST API، كما هو مفصل في مرجع التعبير الشرطي .

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

استخدم هذه السمة على النحو التالي:
  • بالنسبة لمنصات Apple: استخدم CFBundleIdentifier الخاص بالتطبيق. يمكنك العثور على معرف الحزمة في علامة التبويب "عام" للهدف الأساسي لتطبيقك في Xcode.
  • لنظام Android: استخدم معرف التطبيق الخاص بالتطبيق. يمكنك العثور على applicationId في ملف build.gradle على مستوى التطبيق الخاص بك.
نسخة التطبيق لقيم السلسلة:
يتطابق تمامًا،
يتضمن،
لا يحتوي،
تعبير عادي

بالنسبة للقيم الرقمية:
=، ≠، >، ≥، <، ≥

حدد إصدار (إصدارات) تطبيقك الذي تريد استهدافه.

قبل استخدام هذه القاعدة، يجب عليك استخدام قاعدة معرف التطبيق لتحديد تطبيق Android/Apple المرتبط بمشروع Firebase الخاص بك.

بالنسبة لمنصات Apple: استخدم CFBundleShortVersionString الخاص بالتطبيق.

ملاحظة: تأكد من أن تطبيق Apple الخاص بك يستخدم إصدار SDK لمنصات Firebase Apple الإصدار 6.24.0 أو أعلى، حيث لا يتم إرسال CFBundleShortVersionString في الإصدارات السابقة (راجع ملاحظات الإصدار ).

لنظام التشغيل Android: استخدم اسم الإصدار الخاص بالتطبيق.

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

عند استخدام عامل التعبير العادي ، يمكنك إنشاء تعبيرات عادية بتنسيق RE2 . يمكن أن يتطابق تعبيرك العادي مع كل أو جزء من سلسلة الإصدار الهدف. يمكنك أيضًا استخدام نقاط الربط ^ و $ لمطابقة بداية السلسلة المستهدفة أو نهايتها أو مجملها.

اكمل العدد لقيم السلسلة:
يتطابق تمامًا،
يتضمن،
لا يحتوي،
تعبير عادي

بالنسبة للقيم الرقمية:
=، ≠، >، ≥، <، ≥

حدد بنية (إنشاءات) تطبيقك لاستهدافها.

قبل استخدام هذه القاعدة، يجب عليك استخدام قاعدة معرف التطبيق لتحديد تطبيق Apple أو Android المرتبط بمشروع Firebase الخاص بك.

هذا المشغل متاح لتطبيقات Apple وAndroid فقط. وهو يتوافق مع CFBundleVersion الخاص بالتطبيق لـ Apple و versionCode لنظام Android. تعتبر مقارنات السلسلة لهذه القاعدة حساسة لحالة الأحرف.

عند استخدام المطابقات التامة أو يحتوي على أو لا يحتوي على أو عامل تشغيل التعبير العادي ، يمكنك تحديد قيم متعددة.

عند استخدام عامل التعبير العادي ، يمكنك إنشاء تعبيرات عادية بتنسيق RE2 . يمكن أن يتطابق تعبيرك العادي مع كل أو جزء من سلسلة الإصدار الهدف. يمكنك أيضًا استخدام نقاط الربط ^ و $ لمطابقة بداية السلسلة المستهدفة أو نهايتها أو مجملها.

منصة == دائرة الرقابة الداخلية
ذكري المظهر
ويب
نظام التشغيل ==

حدد نظام (أنظمة) التشغيل المراد استهدافه.

قبل استخدام هذه القاعدة، يجب عليك استخدام قاعدة معرف التطبيق لتحديد تطبيق ويب مرتبط بمشروع Firebase الخاص بك.

يتم تقييم هذه القاعدة على أنها true لمثيل تطبيق ويب معين إذا كان نظام التشغيل وإصداره يتطابقان مع قيمة مستهدفة في القائمة المحددة.
المتصفح ==

حدد المتصفح (المتصفحات) المراد استهدافه.

قبل استخدام هذه القاعدة، يجب عليك استخدام قاعدة معرف التطبيق لتحديد تطبيق ويب مرتبط بمشروع Firebase الخاص بك.

يتم تقييم هذه القاعدة على أنها true لمثيل تطبيق ويب معين إذا كان المتصفح وإصداره يتطابقان مع قيمة مستهدفة في القائمة المحددة.
فئة الجهاز إنه ليس متحرك تقوم هذه القاعدة بتقييم ما إذا كان الجهاز الذي يصل إلى تطبيق الويب الخاص بك هو جهاز محمول أو غير محمول (سطح المكتب أو وحدة التحكم). هذا النوع من القواعد متاح فقط لتطبيقات الويب.
اللغات في داخل اختر لغة واحدة أو أكثر. يتم تقييم هذه القاعدة على أنها true بالنسبة لمثيل تطبيق معين إذا تم تثبيت مثيل التطبيق هذا على جهاز يستخدم إحدى اللغات المدرجة.
البلد/المنطقة في داخل حدد منطقة أو بلدًا واحدًا أو أكثر. يتم تقييم هذه القاعدة على أنها true بالنسبة لمثيل تطبيق معين إذا كان المثيل موجودًا في أي من المناطق أو البلدان المدرجة. يتم تحديد رمز بلد الجهاز باستخدام عنوان IP للجهاز في الطلب أو رمز البلد الذي تحدده Firebase Analytics (إذا تمت مشاركة بيانات Analytics مع Firebase).
جمهور (جماهير) المستخدمين تتضمن واحدة على الأقل حدد واحدًا أو أكثر من قائمة شرائح جمهور Google Analytics التي قمت بإعدادها لمشروعك.

تتطلب هذه القاعدة قاعدة معرف التطبيق لتحديد تطبيق مرتبط بمشروع Firebase الخاص بك.

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

خاصية المستخدم لقيم السلسلة:
يتضمن،
لا يحتوي،
يتطابق تمامًا،
تعبير عادي

بالنسبة للقيم الرقمية:
=، ≠، >، ≥، <، ≥

ملاحظة: على العميل، يمكنك تعيين قيم السلسلة فقط لخصائص المستخدم. بالنسبة للشروط التي تستخدم عوامل تشغيل رقمية، يقوم Remote Config بتحويل قيمة خاصية المستخدم المقابلة إلى عدد صحيح/عائم.
اختر من قائمة خصائص مستخدمي Google Analytics المتاحة. لمعرفة كيفية استخدام خصائص المستخدم لتخصيص تطبيقك لشرائح محددة جدًا من قاعدة المستخدمين لديك، راجع التكوين عن بُعد وخصائص المستخدم .

لمعرفة المزيد حول خصائص المستخدم، راجع الأدلة التالية:

عند استخدام المطابقات التامة أو يحتوي على أو لا يحتوي أو معامل التعبير العادي ، يمكنك تحديد قيم متعددة.

عند استخدام عامل التعبير العادي ، يمكنك إنشاء تعبيرات عادية بتنسيق RE2 . يمكن أن يتطابق تعبيرك العادي مع كل أو جزء من سلسلة الإصدار الهدف. يمكنك أيضًا استخدام نقاط الربط ^ و $ لمطابقة بداية السلسلة المستهدفة أو نهايتها أو مجملها.

ملاحظة: خصائص المستخدم المجمعة تلقائيًا غير متاحة حاليًا عند إنشاء شروط التكوين عن بعد.
المستخدم في نسبة عشوائية شريط التمرير (في وحدة تحكم Firebase. تستخدم واجهة REST API عاملي التشغيل <= و > between ). 0-100

استخدم هذا الحقل لتطبيق تغيير على عينة عشوائية من مثيلات التطبيق (بأحجام عينة صغيرة تصل إلى .0001%)، باستخدام عنصر واجهة مستخدم شريط التمرير لتقسيم المستخدمين الذين تم تبديلهم عشوائيًا (مثيلات التطبيق) إلى مجموعات.

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

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

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

على سبيل المثال، لإنشاء شرطين مرتبطين ينطبق كل منهما على 5% غير متداخلة من مستخدمي التطبيق، يمكنك تكوين شرط واحد لمطابقة نسبة مئوية بين 0% و5% وتكوين شرط آخر لمطابقة نطاق بين 5% و 10%. للسماح لبعض المستخدمين بالظهور بشكل عشوائي في كلا المجموعتين، استخدم قيمًا أولية مختلفة للقواعد ضمن كل شرط.

شريحة مستوردة في داخل حدد شريحة مستوردة واحدة أو أكثر. تتطلب هذه القاعدة إعداد شرائح مخصصة مستوردة .
التاريخ/الوقت قبل بعد تاريخ ووقت محددان، إما بالمنطقة الزمنية للجهاز أو بمنطقة زمنية محددة مثل "(GMT+11) بتوقيت سيدني." يقارن الوقت الحالي بوقت جلب الجهاز.
أول مفتوح قبل بعد تاريخ ووقت محددان، في المنطقة الزمنية المحددة.

يطابق المستخدمين الذين فتحوا التطبيق المستهدف لأول مرة خلال النطاق الزمني المحدد.

يتطلب حزم SDK التالية:

  • Firebase SDK لـ Google Analytics
  • منصات Apple SDK v9.0.0+ أو Android SDK v21.1.1+ (Firebase BoM v30.3.0+)

معرف التثبيت في داخل حدد واحدًا أو أكثر من معرفات التثبيت (حتى 50) لاستهدافها. يتم تقييم هذه القاعدة على أنها true بالنسبة لعملية تثبيت محددة إذا كان معرف هذا التثبيت موجودًا في قائمة القيم المفصولة بفواصل.

لمعرفة كيفية الحصول على معرفات التثبيت، راجع استرداد معرفات العميل .
المستخدم موجود (لا يوجد مشغل) يستهدف جميع مستخدمي جميع التطبيقات ضمن المشروع الحالي.

استخدم قاعدة الشرط هذه لمطابقة جميع المستخدمين داخل المشروع، بغض النظر عن التطبيق أو النظام الأساسي.

البحث عن المعلمات والشروط

يمكنك البحث في مفاتيح معلمات مشروعك وقيم المعلمات والشروط من وحدة تحكم Firebase باستخدام مربع البحث الموجود أعلى علامة التبويب معلمات التكوين عن بعد.

حدود المعلمات والشروط

ضمن مشروع Firebase، يمكنك الحصول على ما يصل إلى 2000 معلمة وما يصل إلى 500 شرط. يمكن أن يصل طول مفاتيح المعلمات إلى 256 حرفًا، ويجب أن تبدأ بشرطة سفلية أو حرف إنجليزي (AZ، az)، وقد تتضمن أيضًا أرقامًا. لا يمكن أن يتجاوز إجمالي طول سلاسل قيم المعلمات داخل المشروع 1,000,000 حرف.

عرض التغييرات على المعلمات والشروط

يمكنك عرض أحدث التغييرات على قوالب التكوين عن بعد من وحدة تحكم Firebase . لكل معلمة وشرط على حدة، يمكنك:

  • عرض اسم المستخدم الذي قام بتعديل المعلمة أو الشرط آخر مرة.

  • إذا حدث التغيير خلال نفس اليوم، فاعرض عدد الدقائق أو الساعات التي انقضت منذ نشر التغيير إلى قالب التكوين عن بعد النشط.

  • إذا حدث التغيير قبل يوم واحد أو أكثر، فاعرض التاريخ الذي تم فيه نشر التغيير في قالب التكوين عن بعد النشط.

تحديثات المعلمات

في صفحة معلمات التكوين عن بعد، يعرض عمود آخر منشور آخر مستخدم قام بتعديل كل معلمة وآخر تاريخ نشر للتغيير:

  • لعرض بيانات تعريف التغيير للمعلمات المجمعة، قم بتوسيع مجموعة المعلمات.

  • للفرز بترتيب تصاعدي أو تنازلي حسب تاريخ النشر، انقر فوق تسمية عمود آخر منشور.

تحديثات الحالة

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

الخطوات التالية

للبدء في تكوين مشروع Firebase، راجع إعداد مشروع Firebase Remote Config .