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

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

    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")
}

    باستخدام 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.0.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

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

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

الخطوة 3: ضبط قيم المَعلمات التلقائية داخل التطبيق

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

  1. حدد مجموعة من أسماء المعلّمات وقيم المَعلمات التلقائية باستخدام أو إنشاء كائن على الخريطة ملف موارد XML المُخزَّنة في مجلد res/xml لتطبيقك. دليل "Remote Config" السريع نموذج تطبيق يستخدم ملف 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" التحديثات في الوقت الفعلي للإصدار Android من الإصدار 21.3.0 أو الإصدارات الأحدث (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() {
            @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 دقيقة (للإصدارات الأحدث حدودًا أكثر تساهلاً).

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

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

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

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

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

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