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


يمكنك استخدام ميزة "الإعداد عن بُعد في 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. ننصح باستخدام بنود سياسة Android في Firebase للتحكّم في نُسَخ المكتبة.

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

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

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

الخطوة 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

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

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

الخطوة 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). للحصول على هذه القيم، استدعِ الطريقة المُدرجة أدناه التي ترتبط بنوع البيانات المتوقّع من تطبيقك، مع تقديم مفتاح المَعلمة كوسيطة:

الخطوة 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();
            }
        });

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

الخطوة 7: الاستماع إلى أحدث المعلومات في الوقت الفعلي

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

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

  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 دقيقة (تضع الإصدارات الأحدث حدودًا أكثر تساهلاً).

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

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

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

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

الخطوات اللاحقة

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