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

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

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

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

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

3. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف تبعيات لمكتبتَي Remote Config وAnalytics لنظام التشغيل Android. ننصح باستخدام Firebase Android BoM للتحكّم في إصدارات المكتبة.

   كجزء من عملية إعداد "Analytics"، عليك أيضًا إضافة حزمة Firebase SDK لخدمة "Google Analytics" إلى تطبيقك.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:35.0.2"))
   
       // 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")
   }

   باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase لنظام التشغيل Android.

   (بديل)  إضافة تبعيات مكتبة Firebase بدون استخدام BoM

   إذا اخترت عدم استخدام Firebase BoM، عليك تحديد كل إصدار من مكتبة 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:24.0.0")
       implementation("com.google.firebase:firebase-analytics:24.0.0")
   }

الخطوة 2: الحصول على عنصر Remote Config في نمط "سينغلتون"

احصل على النسخة الافتراضية لعنصر Remote Config وحدِّد أقل فترة زمنية للاسترجاع من أجل السماح بإعادة التحميل بشكل متكرّر:

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

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

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

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

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

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

1. حدِّد مجموعة من أسماء المَعلمات وقيم المَعلمات التلقائية باستخدام عنصر Map أو ملف موارد XML مخزَّن في مجلد res/xml لتطبيقك. يستخدم نموذج تطبيق البدء السريع Remote Config ملفّ XML لتحديد أسماء المَعلمات وقيمها التلقائية.

   إذا سبق لك ضبط قيم مَعلمات الخلفية في Remote Config، يمكنك تنزيل ملف 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
   

   يمكنك إنشاء رمز حامل مميز من خلال تشغيل الأمر التالي باستخدام Google Cloud CLI أو Cloud Shell:

   gcloud auth print-access-token
   

   هذا الرمز المميز قصير الأجل، لذا قد تحتاج إلى إعادة إنشائه إذا تلقيت خطأ في المصادقة.

   وحدة تحكّم Firebase

   1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

   2. افتح more_vert القائمة ، واختَر تنزيل القيم التلقائية.

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

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

   Kotlin

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

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

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

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

الخطوة 5: ضبط قيم المَعلمات في الخلفية في Remote Config

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

1. في وحدة تحكّم Firebase، انتقِل إلى صفحة DevOps & Engagement > الإعداد عن بُعد > المَعلمات.

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

3. في حال استخدام شروط الإشارات المخصّصة، حدِّد السمات وقيمها. توضّح الأمثلة التالية كيفية تحديد شرط إشارة مخصّص.

   Kotlin

           val customSignals = customSignals {
               put("city", "Tokyo")
               put("preferred_event_category", "sports")
           }
   
           remoteConfig.setCustomSignals(customSignals)
       

   Java

           CustomSignals customSignals = new CustomSignals.Builder()
               .put("city", "Tokyo")
               .put("preferred_event_category", "sports")
               .build();
   
           mFirebaseRemoteConfig.setCustomSignals(customSignals);
   
       

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

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

2. لإتاحة قيم المَعلمات التي تم جلبها لتطبيقك، استخدِم طريقة activate().

   في الحالات التي تريد فيها جلب القيم وتفعيلها في طلب واحد، يمكنك استخدام طلب fetchAndActivate() لجلب القيم من الواجهة الخلفية لخدمة Remote Config وإتاحتها للتطبيق:

   Kotlin

   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: الاستماع إلى التعديلات في الوقت الفعلي

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

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

1. في تطبيقك، استخدِم addOnConfigUpdateListener() لبدء الاستماع إلى التحديثات واسترجاع أي قيم مَعلمات جديدة تلقائيًا. نفِّذ دالة ردّ الاتصال onUpdate() لتفعيل الإعدادات المعدَّلة.

   Kotlin

   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<Boolean>() {
                   @Override
                   public void onComplete(@NonNull Task<Boolean> task) {
                       displayWelcomeMessage();
                   }
               });
           }
           @Override
           public void onError(FirebaseRemoteConfigException error) {
               Log.w(TAG, "Config update error with code: " + error.getCode(), error);
           }
       });
       

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

التقييد

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

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

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

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

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