مَعلمات وشروط الإعداد عن بُعد


يمكنك عرض مَعلمات وقيم Remote Config من النماذج لكلّ من حالات استخدام العميل والخادم.

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

  • يمكن عرض نماذج خاصة بالخادم على عمليات تنفيذ Remote Config (بما في ذلك Cloud Run وCloud Functions) التي تستخدم بيئات الخادم التالية:

    • الإصدار 12.1.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لمنصة Firebase Admin Node.js
    • الإصدار 6.7.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لخدمة "مدير Firebase" في Python
    • الإصدار 4.17.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لخدمة "مشرف Firebase" في Go
    • الإصدار 9.7.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لمدير Firebase في Java

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

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

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

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

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

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

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

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

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

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

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

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

Remote Config لا تتوافق بشكل كامل مع الإصدار 6 من بروتوكول الإنترنت (IPv6) عند استخدامها مع سياسات الوصول المستندة إلى عناوين IP. إذا كانت مؤسستك تحظر الوصول إلى نطاقات محددة من عناوين IP العامة، قد يؤدي الاتصال من خلال شبكة IPv6 إلى حدوث المشاكل التالية:

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

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

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

عند استخدام Remote Config في تطبيقات الخادم باستخدام Firebase Admin SDK، يمكنك جلب النموذج الكامل وتحميله من أجل استخراج قيم المَعلمات المناسبة عند الطلب لكل طلب من العميل. قد تتضمّن المَعلمة عدة قيم شرطية مرتبطة بها.

تحدّد القواعد التالية القيمة التي يتم تعيينها أثناء تقييم النموذج في وقت معيّن:

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

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

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

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

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

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

  • String
  • Boolean
  • Number
  • JSON

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  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 حرفًا.

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

تتيح نماذج Remote Config لتطبيقات الخادم أنواع الشروط التالية:

المستخدمون بنسبة عشوائية

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

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

ستستخدِم القاعدة المفتاح التلقائي (المعروض على أنّه تعديل القيمة الأولية في وحدة تحكّم Firebase) ما لم تعدِّل قيمة القيمة الأولية. يمكنك إعادة القاعدة إلى استخدام المفتاح التلقائي من خلال محو الحقل المفتاح الأساسي.

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

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

للتعرّف على كيفية إضافة شروط النسبة المئوية العشوائية إلى تطبيقك، اطّلِع على ضبط تطبيق الخادم.

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

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

  • الإصدار 12.1.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لمنصة Firebase Admin Node.js
  • الإصدار 6.7.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لخدمة "مدير Firebase" في Python
  • الإصدار 4.17.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لخدمة "مشرف Firebase" في Go
  • الإصدار 9.7.0 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لمدير Firebase في Java

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

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

يمكن لتطبيقك الآن استخراج الطلب والنموذج المناسبَين أثناء تقييم النموذج، واستخدامهما لعرض ردود مخصّصة لكل عميل.

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

فئة المشغّل المشغِّلون القيمة ملاحظة
نص تطابق تام، تحتوي على، لا تحتوي على، تحتوي على تعبير عادي

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

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

أرقام <،‏ <=،‏ =،‏ !=،‏ >،‏ >= عدد لا يزيد عن عشرة أرقام على كل جانب من العلامة العشرية
الإصدارات <،‏ <=،‏ =،‏ !=،‏ >،‏ >= رقم يمثّل أرقام الإصدارات التي يجب أن تتطابق (على سبيل المثال، 2.1.0).

للتعرّف على كيفية إضافة إشارات مخصّصة إلى تطبيقك، اطّلِع على ضبط إعدادات تطبيق الخادم.

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

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

الحدود المفروضة على المَعلمات والشروط

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

عرض التغييرات التي تم إجراؤها على المَعلمات والشروط

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

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

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

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

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

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

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

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

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

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

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

لضبط مشروع Firebase وتطبيق الخادم لاستخدام Remote Config، راجِع مقالة استخدام Remote Config في بيئات الخادم.