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


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

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

  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 لنظام التشغيل Android. ننصحك باستخدام الرمز Firebase Android BoM للتحكّم في إصدارات المكتبة.

    بالإضافة إلى ذلك، كجزء من إعداد Analytics، عليك إضافة حزمة تطوير البرامج (SDK) لبرنامج Firebase لنظام التشغيل Google Analytics إلى تطبيقك.

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

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

    (بديل)  إضافة تبعيات مكتبة 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:22.0.1")
        implementation("com.google.firebase:firebase-analytics:22.1.2")
    }
    هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من تشرين الأول (أكتوبر) 2023 (Firebase BoM 32.5.0)، يمكن لمطوّري Kotlin وJava الاعتماد على وحدة المكتبة الرئيسية (للاطّلاع على التفاصيل، راجِع الأسئلة الشائعة حول هذه المبادرة).

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

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

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: ضبط قيم المَعلمات التلقائية داخل التطبيق

يمكنك ضبط قيم المَعلمات التلقائية داخل التطبيق في 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
    

    وحدة تحكّم Firebase

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

    2. فعِّل ملف ‎.xml لأجهزة Android عندما يُطلب منك ذلك، ثم انقر على تنزيل الملف.

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

    Kotlin+KTX

    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

    Java

    mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

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

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

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

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

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

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

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

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

    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: الاستماع إلى آخر الأخبار في الوقت الفعلي

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

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

  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<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).

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

يمكنك استكشاف Remote Config حالات الاستخدام، والاطّلاع على بعض مستندات المفاهيم الرئيسية والاستراتيجيات المتقدّمة، بما في ذلك: