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


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

الخطوة 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 للتحكّم في إصدارات المكتبة.

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.4.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.0")
    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. حدد مجموعة من أسماء المعلّمات وقيم المَعلمات التلقائية باستخدام أو إنشاء كائن على الخريطة ملف موارد 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، إذا لم يسبق لك إجراء ذلك. حالات الاستخدام، وإلقاء نظرة على بعض وثائق المفاهيم الرئيسية والاستراتيجيات المتقدمة، بما في ذلك: