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

اختيار المنصة: iOS+ Android Web Flutter Unity C++


يمكنك استخدام 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 وAnalytics لنظام التشغيل Android. ننصحك باستخدام الـ Firebase Android BoM للتحكّم في تحديد إصدار المكتبة.

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.13.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 لإدارة إصدارات المكتبات، ما يضمن توافق جميع الإصدارات. 

    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:23.1.0")
        implementation("com.google.firebase:firebase-analytics:23.2.0")    
}

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

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

Kotlin 

val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)

Java 

FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);

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

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

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

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

  1. حدِّد مجموعة من أسماء المَعلمات والقيم التلقائية للمَعلمات باستخدام عنصر Map أو ملف موارد بتنسيق XML مخزَّن في مجلد res/xml في تطبيقك. يستخدم نموذج تطبيق Quickstart لميزة "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

    يمكنك إنشاء رمز مميّز للحامل عن طريق تشغيل الأمر التالي باستخدام Google Cloud CLI أو Cloud Shell:

    gcloud auth print-access-token

    هذا الرمز المميّز قصير الأجل، لذا قد تحتاج إلى إعادة إنشائه إذا ظهر لك خطأ في المصادقة.

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

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

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

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

تتوافق حزمة Firebase SDK لنظام التشغيل Android الإصدار 21.3.0 والإصدارات الأحدث ( Firebase BoM الإصدار 31.2.4 والإصدارات الأحدث) مع التعديلات في الوقت الفعلي.

  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).