ابدأ باستخدام Firebase Remote Config


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

الخطوة 1: أضف Firebase وRemote Config SDK إلى تطبيقك

  1. إذا لم تكن قد قمت بذلك بالفعل، فأضف Firebase إلى مشروع Android الخاص بك .

  2. بالنسبة إلى Remote Config، يلزم توفر Google Analytics للاستهداف المشروط لمثيلات التطبيق لخصائص المستخدم والجماهير. تأكد من تمكين Google Analytics في مشروعك.

  3. في ملف Gradle الخاص بالوحدة النمطية (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle )، أضف التبعية للتكوين عن بعد مكتبة أندرويد. نوصي باستخدام Firebase Android BoM للتحكم في إصدار المكتبة.

    وأيضًا، كجزء من إعداد Analytics، تحتاج إلى إضافة Firebase SDK لـ Google Analytics إلى تطبيقك.

    Kotlin+KTX

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

    باستخدام 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-ktx:21.4.1")
    implementation("com.google.firebase:firebase-analytics-ktx:21.3.0")
}

    Java

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:32.3.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 ، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات 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:21.4.1")
    implementation("com.google.firebase:firebase-analytics:21.3.0")
}

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

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

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

الخطوة 3: قم بتعيين قيم المعلمات الافتراضية داخل التطبيق

يمكنك تعيين قيم المعلمات الافتراضية داخل التطبيق في كائن Remote Config، بحيث يتصرف تطبيقك على النحو المنشود قبل أن يتصل بالواجهة الخلفية للتكوين عن بعد، وحتى تكون القيم الافتراضية متاحة إذا لم يتم تعيين أي منها في الواجهة الخلفية.

  1. حدد مجموعة من أسماء المعلمات وقيم المعلمات الافتراضية باستخدام كائن Map أو ملف مورد XML مخزن في مجلد res/xml الخاص بالتطبيق. يستخدم نموذج تطبيق التشغيل السريع للتكوين عن بعد ملف XML لتحديد أسماء المعلمات الافتراضية وقيمها.

    إذا قمت بالفعل بتكوين قيم معلمات الواجهة الخلفية لـ Remote Config، فيمكنك تنزيل ملف XML تم إنشاؤه والذي يتضمن جميع القيم الافتراضية وحفظه في دليل res/xml الخاص بتطبيقك:

    استراحة

    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. حدد Remote Config من القائمة لعرض لوحة معلومات التكوين عن بعد.
  3. حدد المعلمات بنفس أسماء المعلمات التي حددتها في تطبيقك. بالنسبة لكل معلمة، يمكنك تعيين قيمة افتراضية (والتي ستتجاوز في النهاية القيمة الافتراضية المقابلة داخل التطبيق)، ويمكنك أيضًا تعيين القيم الشرطية. لمعرفة المزيد، راجع معلمات وشروط التكوين عن بعد .

الخطوة 6: جلب القيم وتنشيطها

  1. لجلب قيم المعلمات من الواجهة الخلفية للتكوين عن بعد، قم باستدعاء الأسلوب fetch() . يتم جلب أي قيم تقوم بتعيينها في الواجهة الخلفية وتخزينها في كائن Remote Config.

  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: الاستماع إلى التحديثات في الوقت الحقيقي

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

يتم دعم التحديثات في الوقت الفعلي بواسطة Firebase SDK لنظام التشغيل Android v21.3.0+ (Firebase BoM v31.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() {
            @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. في المرة التالية التي تقوم فيها بنشر إصدار جديد من Remote Config، ستستدعي الأجهزة التي تقوم بتشغيل تطبيقك وتستمع إلى التغييرات 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) .

Next steps

If you haven't already, explore the Remote Config use cases , and take a look at some of the key concepts and advanced strategies documentation, including: