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


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

الخطوة 1: إضافة Firebase وحزمة تطوير البرامج (SDK) لميزة "الإعداد عن بُعد" إلى تطبيقك

  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.16.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، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase Android.

    (بديل)  أضِف تبعيات مكتبة Firebase بدون استخدام BoM

    إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية الخاص بها.

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

الخطوة 2: الحصول على عنصر Remote Config في نمط "سينغلتون"

احصل على نسخة افتراضية من العنصر Remote Config وحدِّد أقل فترة زمنية للاسترجاع من أجل السماح بإعادة التحميل بشكل متكرّر:

Kotlin 

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

يتم استخدام عنصر singleton لتخزين قيم المَعلمات التلقائية داخل التطبيق، واسترداد قيم المَعلمات المعدَّلة من الخلفية، والتحكّم في وقت إتاحة القيم المستردة لتطبيقك.

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

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

    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.

  4. في حال استخدام شروط الإشارات المخصّصة، حدِّد السمات وقيمها. توضّح الأمثلة التالية كيفية تحديد شرط إشارة مخصّصة.

    Kotlin 

        val customSignals = customSignals {
        put("city", "Tokyo")
        put("preferred_event_category", "sports")
    }

    remoteConfig.setCustomSignals(customSignals)

    Java 

        CustomSignals customSignals = new CustomSignals.Builder()
        .put("city", "Tokyo")
        .put("preferred_event_category", "sports")
        .build();

    mFirebaseRemoteConfig.setCustomSignals(customSignals);

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

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

  2. لإتاحة قيم المَعلمات التي تم جلبها لتطبيقك، استدعِ طريقة activate().

    في الحالات التي تريد فيها استرجاع القيم وتنشيطها في طلب واحد، يمكنك استخدام طلب fetchAndActivate() لاسترجاع القيم من الخلفية Remote Config وإتاحتها للتطبيق:

    Kotlin 

    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();
            }
        });

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

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

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

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

  1. في تطبيقك، استخدِم addOnConfigUpdateListener() لبدء الاستماع إلى التعديلات واسترجاع أي قيم جديدة للمَعلمات تلقائيًا. نفِّذ وظيفة onUpdate() رد الاتصال لتفعيل الإعدادات المعدَّلة.

    Kotlin 

    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 حالات الاستخدام، وإلقاء نظرة على بعض المستندات الخاصة بالمفاهيم الأساسية والاستراتيجيات المتقدّمة، بما في ذلك: