شروع کار با «پیکربندی از دور» در Android

انتخاب پلاتفرم: iOS+ Android Web Flutter Unity C++‎


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

مرحله ۱: افزودن Firebase و «کیت توسعه نرم‌افزار پیکربندی از دور» به برنامه

  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» برای Google Analytics را به برنامه‌تان اضافه کنید.

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.19.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")    
}

مرحله ۲: دریافت شیء تک‌نمونه 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);

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

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

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

می‌توانید مقادیر پارامتر پیش‌فرض درون‌برنامه‌ای را در Remote Config object تنظیم کنید تا برنامه‌تان قبل‌از اتصال به زیرینه Remote Config طبق انتظار عمل کند و مقادیر پیش‌فرض درصورت عدم تنظیم در زیرینه دردسترس باشد.

  1. مجموعه‌ای از نام‌های پارامتر و مقادیر پیش‌فرض پارامتر را بااستفاده از شیء Map یا فایل منبع 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

    با اجرای فرمان زیر بااستفاده از Google Cloud CLI یا Cloud Shell می‌توانید یک کدحامل تولید کنید:

    gcloud auth print-access-token

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

    کنسول Firebase

    1. در کنسول Firebase، به DevOps و تعامل > پیکربندی از دور > صفحه پارامترها بروید.

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

    3. وقتی درخواست شد، .xml برای Android را فعال کنید، سپس روی بارگیری فایل کلیک کنید.

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

    Kotlin 

    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

    Java 

    mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

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

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

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

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

  1. در کنسول Firebase، به DevOps و تعامل > پیکربندی از دور > صفحه پارامترها بروید.

  2. پارامترهایی با همان نام پارامترهایی که در برنامه‌تان تعریف کرده‌اید تعریف کنید. برای هر پارامتر، می‌توانید مقدار پیش‌فرضی تنظیم کنید (که درنهایت مقدار پیش‌فرض درون‌برنامه‌ای مربوطه را ملغی می‌کند)، و همچنین می‌توانید مقادیر شرطی تنظیم کنید. برای کسب اطلاعات بیشتر، Remote Config پارامترها و شرایط را ببینید.

  3. اگر از شرایط سیگنال سفارشی استفاده می‌کنید، مشخصه‌های آن و مقادیرشان را تعریف کنید. مثال‌های زیر نشان می‌دهد که چگونه شرایط سیگنال سفارشی را تعریف کنید.

    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، 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 هم‌زمان برای شنیدن به‌روزرسانی‌های Remote Config زیرینه استفاده کنید. وقتی به‌روزرسانی دردسترس باشد، Remote Config سیگنال‌های هم‌زمان به دستگاه‌های متصل ارسال می‌شود و پس‌از انتشار نسخه جدید Remote Config، تغییرات به‌طور خودکار واکشی می‌شود.

به‌روزرسانی‌های هم‌زمان توسط «کیت توسعه نرم‌افزار Firebase برای 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 را فرا می‌خوانند.

محدودسازی

اگر برنامه‌ای در مدت زمان کوتاهی دفعات زیادی واکشی کند، تماس‌های واکشی محدود می‌شود و «کیت توسعه نرم‌افزار» FirebaseRemoteConfigFetchThrottledException را برمی‌گرداند. قبل‌از نسخه ۱۷.۰.۰ کیت توسعه نرم‌افزار، محدودیت ۵ درخواست واکشی در بازه زمانی ۶۰ دقیقه‌ای بود (نسخه‌های جدیدتر محدودیت‌های آسان‌گیرانه‌تری دارند).

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

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

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

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