مَعلمات وشروط "الإعداد عن بُعد" في نماذج العملاء

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

عند استخدام وحدة تحكّم Firebase أو واجهات برمجة التطبيقات الخلفية لميزة "Remote Config"، يمكنك تحديد مَعلمة واحدة أو أكثر (أزواج المفتاح-القيمة) وتقديم قيم تلقائية داخل التطبيق لهذه المَعلمات. يمكنك إلغاء القيم التلقائية داخل التطبيق من خلال تحديد قيم المَعلمات. مفاتيح المَعلمات وقيم المَعلمات هي سلاسل، ولكن يمكن تحويل قيم المَعلمات إلى أنواع بيانات أخرى عند استخدام هذه القيم في تطبيقك.

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

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

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

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

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

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

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

إضافة الشروط أو تعديلها أو إعادة ترتيبها أو حذفها باستخدام وحدة تحكّم Firebase

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

1. في وحدة تحكّم Firebase، انتقِل إلى DevOps & Engagement > الإعداد عن بُعد > صفحة الشروط (أو اختَر إدارة الشروط من صفحة المَعلمات).
2. إضافة شرط: انقر على إضافة شرط (أو إنشاء الشرط الأول)، وأدخِل اسمًا يحدّد هدف الاستهداف، واختَر قاعدة استهداف واحدة أو أكثر.
3. تعديل شرط: انقر على اسم الشرط أو رمز التعديل، وعدِّل القواعد حسب الحاجة، ثم انقر على حفظ.
4. تغيير أولوية الشرط: في صفحة الشروط، اسحب الشروط باستخدام مقبض الإمساك لإعادة ترتيبها. وتحظى الشروط الأعلى في القائمة بالأولوية على الشروط الأدنى في القائمة.
5. حذف شرط: انقر على رمز الحذف بجانب الشرط الذي تريد إزالته. إذا تمت الإشارة إلى الشرط من خلال أي مَعلمة، ستؤدي إزالته أيضًا إلى إزالة القيم الشرطية المرتبطة به.

بعد حفظ التغييرات في الشرط، انشر النموذج باستخدام نشر التغييرات.

قيود الإصدار السادس من بروتوكول الإنترنت (IPv6) مع التحكّم في الوصول المستند إلى عنوان IP

يوفّر "Remote Config" دعمًا محدودًا لبروتوكول IPv6 عند استخدامه مع سياسات الوصول المستندة إلى عنوان IP. إذا كانت مؤسستك تفرض قيودًا على الوصول إلى نطاقات عناوين IP عامة معيّنة، يمكن أن يؤدي الاتصال من خلال شبكة IPv6 إلى حدوث المشاكل التالية:

• الوصول إلى وحدة التحكّم: قد لا تتمكّن من استخدام ميزات معيّنة في "Remote Config" في وحدة تحكّم "Firebase"، مثل تحميل البيانات أو إعداد الاستهداف.
• وصول العميل: قد تظهر أخطاء PERMISSION_DENIED في تطبيقات العملاء.

لتجنُّب هذه المشاكل، يمكنك ضبط شبكتك لاستخدام IPv4 أو إضافة نطاقات عناوين IP المطلوبة في Firebase إلى القائمة المسموح بها في مؤسستك.

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

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

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

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

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

1. إذا تم جلب قيمة من الخلفية ثم تفعيلها، يستخدم التطبيق القيمة التي تم جلبها. تكون قيم المَعلمات المفعَّلة ثابتة.

2. إذا لم يتم جلب أي قيمة من الخلفية، أو إذا لم يتم تفعيل القيم التي تم جلبها من الخلفية في Remote Config، سيستخدم التطبيق القيمة التلقائية داخل التطبيق.

   لمزيد من المعلومات حول الحصول على القيم التلقائية وضبطها، يُرجى الاطّلاع على مقالة تنزيل القيم التلقائية لنموذج Remote Config.

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

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

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

تتيح لك ميزة "Remote Config" اختيار نوع بيانات لكل مَعلمة، والتحقّق من صحة جميع قيم "Remote Config" وفقًا لهذا النوع قبل تعديل النموذج. يتم تخزين نوع البيانات وعرضه في طلب getRemoteConfig.

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

• String
• Boolean
• Number
• JSON

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

مجموعات المَعلمات

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

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

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

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

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

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

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.
2. انقر على إدارة المجموعات.
3. ضَع علامة في مربّعات الاختيار بجانب المَعلمات التي تريد إضافتها، ثم انقر على نقل إلى المجموعة.
4. اختَر مجموعة حالية أو أنشِئ مجموعة جديدة من خلال إدخال اسم ووصف، ثم انقر على إنشاء مجموعة جديدة. بعد حفظ مجموعة، تصبح متاحة للنشر باستخدام الزر نشر التغييرات.

إنشاء المجموعات آليًا

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

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 pumpkin spice season."
        }
      }
    }
  }
}

شروط الإشارات المخصّصة

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

تتوفّر شروط الإشارات المخصّصة لبيئات العملاء التالية:

• ‫iOS: الإصدار 11.8.0 أو إصدار أحدث
• ‫Android: الإصدار 22.1.0 أو إصدار أحدث (Firebase BoM الإصدار 33.8.0 أو إصدار أحدث)
• الويب: الإصدار 11.2.0 أو إصدار أحدث
• ‫Flutter: الإصدار 3.6.0 من Flutter BoM أو إصدار أحدث

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

1. أضِف banner_image_url وbanner_link إلى نموذج عميل Remote Config. تمثّل هذه العناصر صورة البانر وصفحة الحدث المرتبطة بهذه الصورة.
2. اضبط إشارات مخصّصة من تطبيقك باستخدام القيمتَين city وpreferred_event_category.
3. أضِف قيمًا تلقائية إلى نموذج Remote Config الخاص بالعميل وأنشئ قيمًا شرطية استنادًا إلى الإشارات المخصّصة التي حدّدتها في الخطوة السابقة.
4. أضِف قيمًا تلقائية إلى نموذج Remote Config الخاص بالعميل و قيمًا شرطية لكل شرط حدّدته.
5. عدِّل الرمز البرمجي للتطبيق لضبط شروط الإشارات المخصّصة واستخدامها.

يمكن لتطبيقك الآن تنزيل banner_image_url وbanner_link المناسبَين عند جلب هذه المَعلمات من خادم Remote Config.

الحدود

عند إنشاء شروط إشارة مخصّصة، يجب الالتزام بالحدود التالية:

• عدد الإشارات المخصّصة: يمكنك إنشاء ما يصل إلى 100 إشارة مخصّصة لكلّ مثيل تطبيق. يمكنك إلغاء ضبط إشارة مخصّصة من خلال ضبط قيمتها على "فارغة".
• اسم الإشارة المخصّصة: يمكن أن يتألف كل اسم إشارة مخصّصة من 250 حرفًا كحدّ أقصى.
• قيمة الإشارة المخصّصة: يمكن أن تتضمّن كل قيمة إشارة مخصّصة ما يصل إلى 500 حرف. عند استخدام التعبيرات العادية، يكون الحدّ الأقصى هو 250 حرفًا.

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

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

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

يمكنك البحث في مفاتيح المَعلمات وقيم المَعلمات والشروط الخاصة بمشروعك من وحدة تحكّم Firebase باستخدام مربّع البحث في أعلى صفحة DevOps والتفاعل > الإعداد عن بُعد > المَعلمات.

الحدود القصوى للمَعلمات والشروط

ضمن مشروع Firebase، يمكنك استخدام ما يصل إلى 3,000 مَعلمة و2,000 شرط. يمكن أن يصل طول مفاتيح المَعلمات إلى 256 حرفًا، ويجب أن تبدأ بشرطة سفلية أو حرف باللغة الإنجليزية (A-Z أو a-z)، ويمكن أن تتضمّن أيضًا أرقامًا. لا يمكن أن يتجاوز إجمالي طول سلاسل قيم المَعلمات ضمن المشروع الواحد 1,000,000 حرف. بالإضافة إلى ذلك، يمكن أن تتضمّن قواعد الشروط المستندة إلى خصائص المستخدمين ما يصل إلى 100 قيمة لخصائص المستخدمين. للاطّلاع على قائمة كاملة بالحدود القصوى، يُرجى مراجعة الحصص والحدود القصوى.

الاطّلاع على التغييرات في المَعلمات والشروط

يمكنك الاطّلاع على آخر التغييرات التي تم إجراؤها على نماذج "Remote Config" من خلال وحدة تحكّم "Firebase". لكل مَعلمة وشرط فردي، يمكنك إجراء ما يلي:

• يمكنك الاطّلاع على اسم المستخدم الذي أجرى آخر تعديل على المَعلمة أو الشرط.

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

• إذا حدث التغيير قبل يوم واحد أو أكثر، يمكنك الاطّلاع على تاريخ نشر التغيير في نموذج "Remote Config" النشط.

سجلّ التغييرات للمَعلمات

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

• لعرض البيانات الوصفية للتغييرات في المَعلمات المجمّعة، وسِّع مجموعة المَعلمات.

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

سجلّ التغييرات للشروط

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

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

لضبط مشروعك وتطبيقك على Firebase لاستخدام Remote Config، يُرجى الاطّلاع على بدء استخدام Firebase Remote Config.