با Firebase Remote Config شروع کنید


شما می‌توانید از Firebase Remote Config برای تعریف پارامترها در برنامه خود و به‌روزرسانی مقادیر آنها در فضای ابری استفاده کنید، که به شما امکان می‌دهد ظاهر و رفتار برنامه خود را بدون توزیع به‌روزرسانی برنامه تغییر دهید. این راهنما مراحل شروع کار را برای شما شرح می‌دهد و تعدادی کد نمونه ارائه می‌دهد که همه آنها برای کلون کردن یا دانلود از مخزن گیت‌هاب firebase/quickstart-android در دسترس هستند.

مرحله 1: Firebase و Remote Config SDK را به برنامه خود اضافه کنید

  1. اگر هنوز Firebase را به پروژه اندروید خود اضافه نکرده‌اید، آن را اضافه کنید.

  2. برای Remote Config ، Google Analytics برای هدف‌گیری مشروط نمونه‌های برنامه به ویژگی‌های کاربر و مخاطبان مورد نیاز است. مطمئن شوید که Google Analytics در پروژه خود فعال کرده‌اید .

  3. در فایل Gradle ماژول (سطح برنامه) خود (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle )، وابستگی مربوط به کتابخانه Remote Config برای اندروید را اضافه کنید. توصیه می‌کنیم برای کنترل نسخه‌بندی کتابخانه Firebase Android BoM استفاده کنید.

    همچنین، به عنوان بخشی از راه‌اندازی Analytics ، باید Firebase SDK را برای Google Analytics به برنامه خود اضافه کنید. 

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.4.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 استفاده خواهد کرد.

    (جایگزین) اضافه کردن وابستگی‌های کتابخانه 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.0.1")
    implementation("com.google.firebase:firebase-analytics:23.0.0")
}

مرحله ۲: دریافت شیء singleton مربوط 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 برای ذخیره مقادیر پیش‌فرض پارامترها در برنامه، دریافت مقادیر به‌روزرسانی‌شده پارامترها از backend و کنترل زمان در دسترس قرار گرفتن مقادیر دریافتی در برنامه شما استفاده می‌شود.

در طول توسعه، توصیه می‌شود حداقل فاصله زمانی واکشی نسبتاً کمی تنظیم شود. برای اطلاعات بیشتر به بخش تنظیم فشار (Throttling) مراجعه کنید.

مرحله ۳: تنظیم مقادیر پیش‌فرض پارامترها در برنامه

شما می‌توانید مقادیر پیش‌فرض پارامترهای درون‌برنامه‌ای را در شیء Remote Config تنظیم کنید، به طوری که برنامه شما قبل از اتصال به Remote Config backend طبق انتظار رفتار کند، و اگر هیچ مقداری در backend تنظیم نشده باشد، مقادیر پیش‌فرض در دسترس باشند.

  1. مجموعه‌ای از نام پارامترها و مقادیر پیش‌فرض پارامترها را با استفاده از یک شیء Map یا یک فایل منبع XML که در پوشه res/xml برنامه شما ذخیره شده است، تعریف کنید. برنامه نمونه Remote Config quickstart از یک فایل XML برای تعریف نام‌ها و مقادیر پیش‌فرض پارامترها استفاده می‌کند.

    اگر قبلاً مقادیر پارامترهای backend مربوط به 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

    شما می‌توانید با اجرای دستور زیر با استفاده از رابط خط فرمان گوگل کلود یا کلود شل، یک توکن حامل ایجاد کنید: 

    gcloud auth print-access-token

    این توکن کوتاه‌مدت است، بنابراین اگر با خطای احراز هویت مواجه شدید، ممکن است نیاز به تولید مجدد آن داشته باشید.

    کنسول Firebase

    1. در برگه پارامترها ، منوی را باز کنید و گزینه دانلود مقادیر پیش‌فرض را انتخاب کنید.

    2. وقتی از شما خواسته شد، فایل ‎.xml را برای اندروید فعال کنید، سپس روی دانلود فایل کلیک کنید.

  2. این مقادیر را با استفاده از setDefaultsAsync(int) به شیء Remote Config اضافه کنید، همانطور که نشان داده شده است:

    Kotlin 

    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

    Java 

    mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

مرحله ۴: دریافت مقادیر پارامترها برای استفاده در برنامه

اکنون می‌توانید مقادیر پارامترها را از شیء Remote Config دریافت کنید. اگر مقادیر را در backend تنظیم کنید، آنها را دریافت کنید و سپس فعال کنید، آن مقادیر برای برنامه شما در دسترس هستند. در غیر این صورت، مقادیر پارامترهای درون برنامه‌ای را که با استفاده از setDefaultsAsync(int) پیکربندی شده‌اند، دریافت می‌کنید. برای دریافت این مقادیر، متد ذکر شده در زیر را که به نوع داده مورد انتظار برنامه شما نگاشت می‌شود، فراخوانی کنید و کلید پارامتر را به عنوان آرگومان ارائه دهید:

مرحله ۵: تنظیم مقادیر پارامترها در بخش Remote Config

با استفاده از کنسول Firebase یا APIهای backend مربوط به 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);

مرحله ۶: دریافت و فعال‌سازی مقادیر

  1. برای دریافت مقادیر پارامترها از Remote Config backend، متد fetch() را فراخوانی کنید. هر مقداری که در backend تنظیم کنید، دریافت شده و در شیء 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 مراجعه کنید.

مرحله ۷: به روزرسانی‌ها را به صورت آنی دریافت کنید

پس از دریافت مقادیر پارامترها، می‌توانید Remote Config به صورت بلادرنگ برای دریافت به‌روزرسانی‌ها از بک‌اند Remote Config استفاده کنید. Remote Config به صورت بلادرنگ، هنگامی که به‌روزرسانی‌ها در دسترس باشند، به دستگاه‌های متصل سیگنال می‌دهد و پس از انتشار نسخه جدید Remote Config تغییرات را به طور خودکار دریافت می‌کند.

به‌روزرسانی‌های بلادرنگ توسط Firebase SDK برای Android نسخه ۲۱.۳.۰+ ( Firebase BoM نسخه ۳۱.۲.۴+) پشتیبانی می‌شوند.

  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 فراخوانی خواهند کرد.

تنظیم سرعت

اگر یک برنامه در یک بازه زمانی کوتاه، تعداد زیادی درخواست واکشی (fetch) داشته باشد، فراخوانی‌های واکشی محدود می‌شوند و SDK خطای FirebaseRemoteConfigFetchThrottledException برمی‌گرداند. قبل از نسخه 17.0.0 SDK، محدودیت 5 درخواست واکشی در یک پنجره 60 دقیقه‌ای بود (نسخه‌های جدیدتر محدودیت‌های مجازتری دارند).

در طول توسعه برنامه، ممکن است بخواهید پیکربندی‌ها را خیلی مکرر (چندین بار در ساعت) دریافت و فعال کنید تا بتوانید هنگام توسعه و آزمایش برنامه خود به سرعت آنها را تکرار کنید. به‌روزرسانی‌های Remote Config در زمان واقعی، هنگام به‌روزرسانی پیکربندی روی سرور، به طور خودکار از حافظه پنهان (cache) عبور می‌کنند. برای تطبیق با تکرار سریع در پروژه‌ای با حداکثر 10 توسعه‌دهنده، می‌توانید به طور موقت یک شیء FirebaseRemoteConfigSettings با حداقل فاصله زمانی دریافت ( setMinimumFetchIntervalInSeconds ) در برنامه خود تنظیم کنید.

حداقل فاصله زمانی پیش‌فرض برای واکشی Remote Config ۱۲ ساعت است، به این معنی که پیکربندی‌ها بیش از یک بار در یک بازه زمانی ۱۲ ساعته از بک‌اند واکشی نمی‌شوند، صرف نظر از اینکه در واقع چند فراخوانی واکشی انجام شده است. به طور خاص، حداقل فاصله زمانی واکشی به ترتیب زیر تعیین می‌شود:

  1. پارامتر در fetch(long)
  2. پارامتر موجود در FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
  3. مقدار پیش‌فرض ۱۲ ساعت

برای تنظیم حداقل فاصله زمانی دریافت (fetch interval) روی یک مقدار سفارشی، از FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long) استفاده کنید.

مراحل بعدی

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: