بدء استخدام ميزة "الإعداد عن بُعد في 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.6.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، سيستخدم تطبيقك دائمًا الإصدارات المتوافقة من مكتبات 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)
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" للإصدار Android من الإصدار 21.3.0 والإصدارات الأحدث (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 حالات الاستخدام، والاطّلاع على بعض مستندات المفاهيم الرئيسية والاستراتيجيات المتقدّمة، بما في ذلك: