شروع کار با «پیکربندی از دور» در 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:35.1.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:24.0.1")
       implementation("com.google.firebase:firebase-analytics:24.0.0")
   }

توجه: ازآنجایی‌که «کیت توسعه نرم‌افزار Android» به Remote Config REST API وابسته است، مطمئن شوید که آن API را غیرفعال نکنید، که به‌طور پیش‌فرض در یک پروژه معمولی فعال است.

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

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

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

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

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

مهم: داده‌های محرمانه را در کلیدها یا مقادیر پارامتر Remote Config ذخیره نکنید. 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) پیکربندی شده‌اند دریافت می‌کنید. برای دریافت این مقادیر، روش فهرست‌شده در کد زیر را که با نوع داده موردانتظار برنامه‌تان مطابقت دارد فراخوانی کنید و کلید پارامتر را به‌عنوان آرگومان ارائه دهید:

• getBoolean()
• getDouble()
• getLong()
• getString()

مرحله ۵: تنظیم مقادیر پارامتر در پسای 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();
               }
           });

چون این مقادیر پارامتر به‌روزشده بر رفتار و ظاهر برنامه‌تان تأثیر می‌گذارد، باید مقادیر واکشی‌شده را در زمانی فعال کنید که تجربه روانی را برای کاربرتان تضمین کند، مثلاً دفعه بعدی که کاربر برنامه‌تان را باز می‌کند. برای اطلاعات بیشتر و مثال‌ها، راهبردهای بار کردن «پیکربندی از راه دور» را ببینید.

توجه: اگر برنامه‌تان با Gradle ساخته نشده است، باید منبع رشته‌ای صحیح google_app_id را به‌صورت دستی به برنامه‌تان اضافه کنید تا Remote Config بتواند مقداردهی اولیه شود. افزایه Gradle‏ google-services معمولاً این را به‌طور خودکار اضافه می‌کند، اما می‌توانید مقدار مناسب را در فایل پیکربندی google-services.json که از کنسول Firebase بارگیری می‌کنید پیدا کنید. برای اطلاعات بیشتر درباره دریافت مقدار google_app_id از فایل پیکربندی google-services.json، نحوه پردازش فایل پیکربندی JSON را ببینید.

مرحله ۷: گوش دادن به به‌روزرسانی‌ها به‌طور هم‌زمان

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

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

مهم: Remote Config هم‌زمان به Firebase Remote Config Realtime API نیز نیاز دارد که باید ازقبل برای شما فعال شده باشد. برای درستی‌سنجی، کنسول Google Cloud را باز کنید، پروژه‌تان را انتخاب کنید، و صفحه میاناهای برنامه‌سازی کاربردی و سرویس‌ها را باز کنید. API باید به‌عنوان فعال نشان داده شود. اگر وجود ندارد یا فعال نیست، روی فعال کردن میاناهای برنامه‌سازی کاربردی و سرویس‌ها کلیک کنید، Firebase Remote Config Realtime API را جستجو کنید و آن را فعال کنید.

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 را برمی‌گرداند. قبل‌از نسخه ۱۷.۰.۰ کیت توسعه نرم‌افزار، حد مجاز ۵ درخواست واکشی در بازه زمانی ۶۰ دقیقه‌ای بود (نسخه‌های جدیدتر حد مجاز آسان‌گیرانه‌تری دارند).

نکته: با شروع از کیت توسعه نرم‌افزار Android نسخه ۲۱.۳.۰+ (Firebase BoM نسخه ۳۱.۳.۰+)، می‌توانید از Remote Config بی‌درنگ برای واکشی خودکار مقادیر پارامتر به‌روزشده از پسای Remote Config به‌محض انتشار آن‌ها استفاده کنید و هرگونه تنظیم حداقل فاصله واکشی را دور بزنید. برای اطلاعات بیشتر، به شنیدن به‌روزرسانی‌ها به‌طور هم‌زمان مراجعه کنید.

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

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

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

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

به‌خاطر داشته باشید که این تنظیم فقط باید برای توسعه استفاده شود، نه برای برنامه‌ای که درحال اجرا در محیط تولید است. اگر فقط درحال آزمایش برنامه‌تان با تیم توسعه کوچک ۱۰ نفره هستید، احتمالاً به محدودیت‌های سهمیه ساعتی سمت سرویس نخواهید رسید. اما اگر برنامه‌تان را با حداقل فاصله واکشی بسیار کم برای هزاران کاربر آزمایشی ارسال کنید، احتمالاً برنامه‌تان به این سهمیه می‌رسد.