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


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

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

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.1.2"))

    // 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 BoM) من 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.2")
}
    هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ ستبدأ بعد تشرين الأول (أكتوبر) 2023 (الإصدار 32.5.0 من Firebase BoM)، بإمكان مطوّري برامج 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 أو الإصدارات الأحدث من نظام التشغيل Firebase. الإصدار 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() {
            @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).

الخطوات التالية

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