يمكنك استخدام ميزة "الإعداد عن بُعد في Firebase" لتحديد مَعلمات في تطبيقك وتعديل قيمها في السحابة الإلكترونية، ما يتيح لك تعديل مظهر تطبيقك وسلوكه بدون توزيع تحديث للتطبيق. يرشدك هذا الدليل إلى الخطوات اللازمة للبدء ويوفر لك نموذج رمز برمجي، ويمكنك استنساخ جميع هذه الرموز أو تنزيلها من مستودع GitHub في firebase/quickstart-android.
الخطوة 1: إضافة Firebase وحزمة تطوير البرامج (SDK) لميزة "الإعداد عن بُعد" إلى تطبيقك
أضِف Firebase إلى مشروع Android الخاص بك، إذا لم يسبق لك إجراء ذلك.
بالنسبة إلى ميزة "الإعداد عن بُعد"، يجب استخدام "إحصاءات Google" من أجل الاستهداف المشروط لمثيلات التطبيقات لخصائص المستخدمين وشرائح الجمهور. احرص على تفعيل "إحصاءات Google" في مشروعك.
في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً
<project>/<app-module>/build.gradle.kts
أو<project>/<app-module>/build.gradle
)، أضِف الملحقية لمكتبة "الإعداد عن بُعد" لنظام التشغيل Android. ننصحك باستخدام برنامج Firebase Android BoM للتحكّم في إصدارات المكتبة.وأيضًا، كجزء من إعداد "إحصاءات Google"، عليك إضافة حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصة بخدمة "إحصاءات Google" إلى تطبيقك.
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:32.8.1")) // Add the dependencies for the Remote Config and Analytics libraries // When using the BoM, you don't specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-config") implementation("com.google.firebase:firebase-analytics") }
باستخدام إطار عمل Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Android في Firebase.
(بديل) أضِف تبعيات مكتبة Firebase بدون استخدام قائمة BoM.
إذا اختَرت عدم استخدام قائمة مشروعات Firebase، يجب تحديد كل إصدار من إصدارات مكتبة Firebase في سطر التبعية الخاص به.
يُرجى العلم أنّه في حال استخدام مكتبات Firebase متعددة في تطبيقك، ننصحك بشدة باستخدام أداة BoM لإدارة إصدارات المكتبة، ما يضمن توافق جميع الإصدارات.
dependencies { // Add the dependencies for the Remote Config and Analytics libraries // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-config:21.6.3") implementation("com.google.firebase:firebase-analytics:21.6.2") }
الخطوة 2: استرجاع عنصر ميزة "الإعداد عن بُعد" في نمط "سينغلتون"
احصل على مثيل لكائن "الإعداد عن بُعد" واضبط الحدّ الأدنى للفاصل الزمني للاسترجاع للسماح بإعادة التحميل بشكل متكرّر:
Kotlin+KTX
val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig val configSettings = remoteConfigSettings { minimumFetchIntervalInSeconds = 3600 } remoteConfig.setConfigSettingsAsync(configSettings)
Java
FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance(); FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder() .setMinimumFetchIntervalInSeconds(3600) .build(); mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);
يُستخدم كائن سينغلتون لتخزين قيم المعلمات التلقائية داخل التطبيق واسترجاع قيم المعلّمات المعدّلة من الخلفية والتحكّم في وقت توفير القيم التي تم استرجاعها لتطبيقك.
أثناء التطوير، يُوصى بضبط حد أدنى منخفض نسبيًا لفاصل استرجاع البيانات. راجِع التقييد للحصول على مزيد من المعلومات.
الخطوة 3: ضبط قيم المَعلمات التلقائية داخل التطبيق
يمكنك ضبط قيم للمعلَمات التلقائية داخل التطبيق في كائن "الإعداد عن بُعد"، حتى يتصرف تطبيقك على النحو المطلوب قبل اتصاله بالخلفية الخلفية للإعداد عن بُعد، ولكي تتوفّر قيم تلقائية في حال لم يتم ضبط أي منها في الخلفية.
حدِّد مجموعة من أسماء المَعلمات وقيم المَعلمات التلقائية باستخدام كائن ربط أو ملف موارد XML مخزَّن في مجلد
res/xml
الخاص بتطبيقك. يستخدم نموذج البدء السريع لميزة "الإعداد عن بُعد" ملف XML لتحديد أسماء وقيم المعلّمات التلقائية.إذا سبق لك ضبط قيم مَعلمات الخلفية لميزة "الإعداد عن بُعد"، يمكنك تنزيل ملف XML تم إنشاؤه يتضمّن جميع القيم التلقائية وحفظه في دليل
res/xml
لتطبيقك:REST
curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=XML -o remote_config_defaults.xml
وحدة تحكُّم Firebase
في علامة التبويب المَعلمات، افتح القائمة، واختَر تنزيل القيم التلقائية.
فعِّل .xml في نظام التشغيل Android ثم انقر على تنزيل الملف عندما يُطلب منك ذلك.
أضِف هذه القيم إلى كائن "الإعداد عن بُعد" باستخدام
setDefaultsAsync(int)
، على النحو الموضّح:Kotlin+KTX
remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)
Java
mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);
الخطوة 4: الحصول على قيم المَعلمات لاستخدامها في تطبيقك
يمكنك الآن الحصول على قيم المَعلمات من كائن "الإعداد عن بُعد". إذا ضبطت قيمًا في الخلفية وجلبتها ثم فعّلتها، تصبح هذه القيم متاحة لتطبيقك. وإلا، سيتم ضبط قيم المعلمات داخل التطبيق باستخدام setDefaultsAsync(int)
.
للحصول على هذه القيم، استدعِ الطريقة المدرجة أدناه والتي ترتبط بنوع البيانات
المتوقع من تطبيقك، مع تقديم مفتاح المعلمة كوسيطة:
الخطوة 5: ضبط قيم المَعلمات في الواجهة الخلفية لميزة "الإعداد عن بُعد"
باستخدام وحدة تحكُّم Firebase أو واجهات برمجة تطبيقات الواجهة الخلفية لميزة "الإعداد عن بُعد"، يمكنك إنشاء قيم تلقائية جديدة من جهة الخادم تلغي القيم داخل التطبيق وفقًا للمنطق الشرطي أو استهداف المستخدمين المطلوب. يصف هذا القسم خطوات وحدة تحكم Firebase لإنشاء هذه القيم.
- افتح مشروعك في وحدة تحكُّم Firebase.
- اختَر الإعداد عن بُعد من القائمة لعرض لوحة بيانات "الإعداد عن بُعد".
- حدِّد المَعلمات بنفس أسماء المَعلمات التي حدّدتها في تطبيقك. ولكل مَعلمة، يمكنك ضبط قيمة تلقائية (ستؤدي في النهاية إلى إلغاء القيمة التلقائية المقابلة في التطبيق)، ويمكنك أيضًا ضبط قيم شرطية. لمزيد من المعلومات، اطّلِع على مَعلمات "الإعداد عن بُعد" وشروطه.
الخطوة 6: استرجاع القيم وتفعيلها
- لاسترجاع قيم المَعلمات من الواجهة الخلفية لميزة "الإعداد عن بُعد"، عليك طلب الإجراء
fetch()
. ويتم استرجاع أي قيم تضبطها في الخلفية وتخزينها في كائن "الإعداد عن بُعد". لإتاحة قيم المَعلمات التي تم استرجاعها لتطبيقك، عليك طلب الإجراء
activate()
.بالنسبة إلى الحالات التي تريد فيها استرجاع القيم وتفعيلها في مكالمة واحدة، يمكنك استخدام طلب
fetchAndActivate()
لجلب القيم من الواجهة الخلفية لميزة "الإعداد عن بُعد" وإتاحتها للتطبيق:Kotlin+KTX
remoteConfig.fetchAndActivate() .addOnCompleteListener(this) { task -> if (task.isSuccessful) { val updated = task.result Log.d(TAG, "Config params updated: $updated") Toast.makeText( this, "Fetch and activate succeeded", Toast.LENGTH_SHORT, ).show() } else { Toast.makeText( this, "Fetch failed", Toast.LENGTH_SHORT, ).show() } displayWelcomeMessage() }
Java
mFirebaseRemoteConfig.fetchAndActivate() .addOnCompleteListener(this, new OnCompleteListener<Boolean>() { @Override public void onComplete(@NonNull Task<Boolean> task) { if (task.isSuccessful()) { boolean updated = task.getResult(); Log.d(TAG, "Config params updated: " + updated); Toast.makeText(MainActivity.this, "Fetch and activate succeeded", Toast.LENGTH_SHORT).show(); } else { Toast.makeText(MainActivity.this, "Fetch failed", Toast.LENGTH_SHORT).show(); } displayWelcomeMessage(); } });
ولأنّ قيم المَعلمات المعدّلة هذه تؤثر في سلوك تطبيقك ومظهره، يجب تفعيل القيم التي تم استرجاعها في وقت يضمن تجربة سلسة للمستخدم، مثل المرة التالية التي يفتح فيها المستخدِم تطبيقك. راجِع استراتيجيات تحميل الإعداد عن بُعد للاطّلاع على مزيد من المعلومات والأمثلة.
الخطوة 7: الاستماع إلى آخر الأخبار في الوقت الفعلي
بعد استرجاع قيم المَعلمات، يمكنك استخدام ميزة "الإعداد عن بُعد" في الوقت الفعلي للاستماع إلى آخر الأخبار من الواجهة الخلفية لميزة "الإعداد عن بُعد". في الوقت الفعلي تُرسِل ميزة "الإعداد عن بُعد" إشارات إلى الأجهزة المتصلة عند توفّر التحديثات، وتجلب التغييرات تلقائيًا بعد نشر إصدار جديد من ميزة "الإعداد عن بُعد".
تتوفّر التحديثات في الوقت الفعلي من خلال حزمة تطوير البرامج (SDK) لمنصة Firebase لنظام التشغيل Android الإصدار 21.3.0 والإصدارات الأحدث (الإصدار 31.2.4 والإصدارات الأحدث من Firebase BoM).
في تطبيقك، استخدم
addOnConfigUpdateListener()
لبدء الاستماع إلى التحديثات وجلب أي قيم معلمات جديدة تلقائيًا. يمكنك تنفيذ معاودة الاتصال بـ "onUpdate()
" لتفعيل الإعدادات المعدَّلة.Kotlin+KTX
remoteConfig.addOnConfigUpdateListener(object : ConfigUpdateListener { override fun onUpdate(configUpdate : ConfigUpdate) { Log.d(TAG, "Updated keys: " + configUpdate.updatedKeys); if (configUpdate.updatedKeys.contains("welcome_message")) { remoteConfig.activate().addOnCompleteListener { displayWelcomeMessage() } } } override fun onError(error : FirebaseRemoteConfigException) { Log.w(TAG, "Config update error with code: " + error.code, error) } })
Java
mFirebaseRemoteConfig.addOnConfigUpdateListener(new ConfigUpdateListener() { @Override public void onUpdate(ConfigUpdate configUpdate) { Log.d(TAG, "Updated keys: " + configUpdate.getUpdatedKeys()); mFirebaseRemoteConfig.activate().addOnCompleteListener(new OnCompleteListener
() { @Override public void onComplete(@NonNull Task task) { displayWelcomeMessage(); } }); } @Override public void onError(FirebaseRemoteConfigException error) { Log.w(TAG, "Config update error with code: " + error.getCode(), error); } }); في المرة القادمة التي تنشر فيها إصدارًا جديدًا من ميزة "الإعداد عن بُعد"، ستحمل الأجهزة التي تشغِّل تطبيقك وتستمع إلى التغييرات الاسم
ConfigUpdateListener
.
تقييد
إذا كان التطبيق يجلب عددًا كبيرًا جدًا من المرات خلال فترة زمنية قصيرة، يتم فرض قيود على طلبات الاسترجاع
وتعرض حزمة تطوير البرامج (SDK)
FirebaseRemoteConfigFetchThrottledException
. قبل الإصدار 17.0.0 من حزمة تطوير البرامج (SDK)، كان الحدّ الأقصى المسموح به هو 5 طلبات جلب خلال فترة 60 دقيقة (تتسم الإصدارات الأحدث بحدود أكثر تساهلاً).
أثناء تطوير التطبيق، قد تحتاج إلى استرجاع الإعدادات وتفعيلها بشكل متكرر (عدد كبير في الساعة) للسماح لك بتكرارها سريعًا أثناء تطوير تطبيقك واختباره. إنّ تحديثات "الإعداد عن بُعد في الوقت الفعلي" تتجاوز ذاكرة التخزين المؤقت تلقائيًا عند تعديل الإعدادات على الخادم. ولاستيعاب التكرار السريع في مشروع مع ما يصل إلى 10 مطوّرين، يمكنك ضبط عنصر
FirebaseRemoteConfigSettings
مؤقتًا بحدّ أدنى منخفض للفاصل الزمني للاسترجاع
(setMinimumFetchIntervalInSeconds
) في تطبيقك.
إنّ الحد الأدنى التلقائي للفاصل الزمني للاسترجاع في ميزة "الإعداد عن بُعد" هو 12 ساعة، ما يعني أنّه لن يتم جلب الإعدادات من الخلفية أكثر من مرة خلال فترة 12 ساعة، بغض النظر عن عدد طلبات الاسترجاع التي يتم إجراؤها. وعلى وجه التحديد، يتم تحديد الحد الأدنى للفاصل الزمني للاسترجاع بهذا الترتيب التالي:
- المَعلمة في
fetch(long)
- المَعلمة في
FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
- القيمة التلقائية التي تبلغ 12 ساعة
لضبط الحد الأدنى للفاصل الزمني للاسترجاع على قيمة مخصّصة، استخدِم FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long)
.
الخطوات التالية
استكشِف حالات الاستخدام لميزة "الإعداد عن بُعد" إذا لم يسبق لك ذلك، وألقِ نظرة على بعض المفاهيم الرئيسية ومستندات الاستراتيجيات المتقدّمة، بما في ذلك: