بدء استخدام ميزة "الإعداد عن بُعد في 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.7.0"))

    // 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: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)
MainActivity.kt

Java 

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

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

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

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

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

  1. حدِّد مجموعة من أسماء المَعلمات وقيمها التلقائية باستخدام عنصر Map أو ملف موارد XML المخزّن في مجلد res/xml في تطبيقك. يستخدم Remote Config quickstart نموذج التطبيق ملف 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 حالات الاستخدام، والاطّلاع على بعض مستندات المفاهيم الرئيسية والاستراتيجيات المتقدّمة، بما في ذلك: