بدء استخدام ميزة "الإعداد عن بُعد في Firebase"

iOS+ Android الويب Flutter Unity C++

ملاحظة مُهمّة: يوضّح هذا القسم خطوات إعداد ميزة "الإعداد عن بُعد" في برامج الويب والأجهزة الجوّالة. بالنسبة إلى بيئات الخوادم، يُرجى الاطّلاع على استخدام ميزة "الإعداد عن بُعد" في بيئات الخادم.

يمكنك استخدام ميزة "الإعداد عن بُعد في Firebase" لتحديد مَعلمات في تطبيقك وتعديل قيمها في السحابة الإلكترونية، ما يتيح لك تعديل مظهر تطبيقك وسلوكه بدون توزيع تحديث للتطبيق. يرشدك هذا الدليل إلى الخطوات اللازمة للبدء ويوفر لك نموذج رمز برمجي، ويمكنك استنساخ جميع هذه الرموز أو تنزيلها من مستودع GitHub في firebase/quickstart-android.

الخطوة 1: إضافة Firebase وحزمة تطوير البرامج (SDK) لميزة "الإعداد عن بُعد" إلى تطبيقك

1. أضِف Firebase إلى مشروع Android الخاص بك، إذا لم يسبق لك إجراء ذلك.

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

3. في ملف 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")
   }
   

   هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 ( Firebase BoM 32.5.0)، أصبح بإمكان مطوّري لغتَي Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (لمعرفة التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة).

ملاحظة: بما أنّ حزمة تطوير البرامج (SDK) لنظام التشغيل Android تعتمد على واجهة برمجة التطبيقات Remote Config REST، احرِص على عدم إيقاف واجهة برمجة التطبيقات هذه التي يتم تفعيلها تلقائيًا في مشروع عادي.

الخطوة 2: استرجاع عنصر ميزة "الإعداد عن بُعد" في نمط "سينغلتون"

احصل على مثيل لكائن "الإعداد عن بُعد" واضبط الحدّ الأدنى للفاصل الزمني للاسترجاع للسماح بإعادة التحميل بشكل متكرّر:

Kotlin+KTX

val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)
MainActivity.kt

Java

FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);
MainActivity.java

يُستخدم كائن سينغلتون لتخزين قيم المعلمات التلقائية داخل التطبيق واسترجاع قيم المعلّمات المعدّلة من الخلفية والتحكّم في وقت توفير القيم التي تم استرجاعها لتطبيقك.

أثناء التطوير، يُوصى بضبط حد أدنى منخفض نسبيًا لفاصل استرجاع البيانات. راجِع التقييد للحصول على مزيد من المعلومات.

الخطوة 3: ضبط قيم المَعلمات التلقائية داخل التطبيق

يمكنك ضبط قيم للمعلَمات التلقائية داخل التطبيق في كائن "الإعداد عن بُعد"، حتى يتصرف تطبيقك على النحو المطلوب قبل اتصاله بالخلفية الخلفية للإعداد عن بُعد، ولكي تتوفّر قيم تلقائية في حال لم يتم ضبط أي منها في الخلفية.

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

1. حدِّد مجموعة من أسماء المَعلمات وقيم المَعلمات التلقائية باستخدام كائن ربط أو ملف موارد 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

   1. في علامة التبويب المَعلمات، افتح القائمة، واختَر تنزيل القيم التلقائية.

   2. فعِّل .xml في نظام التشغيل Android ثم انقر على تنزيل الملف عندما يُطلب منك ذلك.

2. أضِف هذه القيم إلى كائن "الإعداد عن بُعد" باستخدام setDefaultsAsync(int)، على النحو الموضّح:

   Kotlin+KTX

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

الخطوة 4: الحصول على قيم المَعلمات لاستخدامها في تطبيقك

يمكنك الآن الحصول على قيم المَعلمات من كائن "الإعداد عن بُعد". إذا ضبطت قيمًا في الخلفية وجلبتها ثم فعّلتها، تصبح هذه القيم متاحة لتطبيقك. وإلا، سيتم ضبط قيم المعلمات داخل التطبيق باستخدام setDefaultsAsync(int). للحصول على هذه القيم، استدعِ الطريقة المدرجة أدناه والتي ترتبط بنوع البيانات المتوقع من تطبيقك، مع تقديم مفتاح المعلمة كوسيطة:

• getBoolean()
• getDouble()
• getLong()
• getString()

الخطوة 5: ضبط قيم المَعلمات في الواجهة الخلفية لميزة "الإعداد عن بُعد"

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

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

الخطوة 6: استرجاع القيم وتفعيلها

1. لاسترجاع قيم المَعلمات من الواجهة الخلفية لميزة "الإعداد عن بُعد"، عليك طلب الإجراء fetch(). ويتم استرجاع أي قيم تضبطها في الخلفية وتخزينها في كائن "الإعداد عن بُعد".

2. لإتاحة قيم المَعلمات التي تم استرجاعها لتطبيقك، عليك طلب الإجراء 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();
               }
           });

ولأنّ قيم المَعلمات المعدّلة هذه تؤثر في سلوك تطبيقك ومظهره، يجب تفعيل القيم التي تم استرجاعها في وقت يضمن تجربة سلسة للمستخدم، مثل المرة التالية التي يفتح فيها المستخدِم تطبيقك. راجِع استراتيجيات تحميل الإعداد عن بُعد للاطّلاع على مزيد من المعلومات والأمثلة.

ملاحظة: إذا لم يتم إنشاء تطبيقك باستخدام Gradle، عليك إضافة مورد سلسلة google_app_id الصحيح إلى تطبيقك يدويًا كي يتم إعداد ميزة "الإعداد عن بُعد". يضيف عادةً مكوّن Gradle الإضافي google-services هذا تلقائيًا، ولكن يمكنك العثور على القيمة المناسبة في ملف google-services.json الذي يتم تنزيله من "وحدة تحكُّم Firebase". لمزيد من المعلومات حول الحصول على القيمة google_app_id من ملف google-services.json، يمكنك الاطّلاع على معالجة ملف JSON.

الخطوة 7: الاستماع إلى آخر الأخبار في الوقت الفعلي

بعد استرجاع قيم المَعلمات، يمكنك استخدام ميزة "الإعداد عن بُعد" في الوقت الفعلي للاستماع إلى آخر الأخبار من الواجهة الخلفية لميزة "الإعداد عن بُعد". في الوقت الفعلي تُرسِل ميزة "الإعداد عن بُعد" إشارات إلى الأجهزة المتصلة عند توفّر التحديثات، وتجلب التغييرات تلقائيًا بعد نشر إصدار جديد من ميزة "الإعداد عن بُعد".

تتوفّر التحديثات في الوقت الفعلي من خلال حزمة تطوير البرامج (SDK) لمنصة Firebase لنظام التشغيل Android الإصدار 21.3.0 والإصدارات الأحدث (الإصدار 31.2.4 والإصدارات الأحدث من Firebase BoM).

ملاحظة مهمة: تتطلّب ميزة "الإعداد عن بُعد في الوقت الفعلي" أيضًا توفّر واجهة برمجة التطبيقات Firebase Remote Config (الإعداد عن بُعد في Firebase) والتي سبق أن تم تفعيلها. لإثبات الملكية، افتح وحدة تحكّم Google Cloud واختَر مشروعك، ثم افتح صفحة واجهات برمجة التطبيقات والخدمات. من المفترض أن تظهر واجهة برمجة التطبيقات على أنّها مفعّلة. إذا لم تكن هذه الواجهة غير متوفّرة أو لم يتم تفعيلها، انقر على تفعيل واجهات برمجة التطبيقات والخدمات، وابحث عن واجهة برمجة التطبيقات Firebase Remote Config TIME API وفعِّلها.

1. في تطبيقك، استخدم 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);
       }
   });
   

2. في المرة القادمة التي تنشر فيها إصدارًا جديدًا من ميزة "الإعداد عن بُعد"، ستحمل الأجهزة التي تشغِّل تطبيقك وتستمع إلى التغييرات الاسم ConfigUpdateListener.

تقييد

إذا كان التطبيق يجلب عددًا كبيرًا جدًا من المرات خلال فترة زمنية قصيرة، يتم فرض قيود على طلبات الاسترجاع وتعرض حزمة تطوير البرامج (SDK) FirebaseRemoteConfigFetchThrottledException. قبل الإصدار 17.0.0 من حزمة تطوير البرامج (SDK)، كان الحدّ الأقصى المسموح به هو 5 طلبات جلب خلال فترة 60 دقيقة (تتسم الإصدارات الأحدث بحدود أكثر تساهلاً).

ملاحظة: بدءًا من الإصدار 21.3.0 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android (الإصدار 31.3.0 من Firebase BoM والإصدارات الأحدث)، يمكنك استخدام ميزة "الإعداد عن بُعد" في الوقت الفعلي لجلب قيم المَعلمات المعدَّلة تلقائيًا من الخلفية لميزة "الإعداد عن بُعد" فور نشرها، مع تجاوز أي إعدادات للحدّ الأدنى للفاصل الزمني للاسترجاع. لمزيد من المعلومات، يُرجى مراجعة الاستماع إلى التحديثات في الوقت الفعلي.

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

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

1. المَعلمة في fetch(long)
2. المَعلمة في FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
3. القيمة التلقائية التي تبلغ 12 ساعة

لضبط الحد الأدنى للفاصل الزمني للاسترجاع على قيمة مخصّصة، استخدِم FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long).

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

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

استكشِف حالات الاستخدام لميزة "الإعداد عن بُعد" إذا لم يسبق لك ذلك، وألقِ نظرة على بعض المفاهيم الرئيسية ومستندات الاستراتيجيات المتقدّمة، بما في ذلك:

• إدارة إصدارات نماذج "الإعداد عن بُعد"
• استراتيجيات تحميل الإعدادات