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

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


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

مرحله ۱: افزودن Firebase و Remote Config 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 برای Google Analytics را به برنامه‌تان اضافه کنید.

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:35.0.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، برنامه شما همیشه از نسخه‌های سازگار کتابخانه‌های 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:24.0.0")
        implementation("com.google.firebase:firebase-analytics:24.0.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 تنظیم کنید تا برنامه‌تان قبل‌از اتصال به باطن 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 استفاده کنید. وقتی به‌روزرسانی‌ها دردسترس باشند، Real-time Remote Config به دستگاه‌های متصل سیگنال می‌دهد و پس‌از انتشار نسخه جدید Remote Config، تغییرات را به‌طور خودکار واکشی می‌کند.

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

  1. در برنامه‌تان، از addOnConfigUpdateListener() برای شروع گوش دادن به به‌روزرسانی‌ها و واکشی خودکار مقادیر پارامتر جدید استفاده کنید. برای فعال کردن پیکربندی به‌روزشده، onUpdate() callback را پیاده‌سازی کنید.

    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) استفاده کنید.