Начало работы с Firebase Remote Config

iOS+ Android Web Flutter Unity C++

Важно: В этом разделе описаны шаги по настройке Remote Config с помощью мобильных и веб-клиентов. Для серверных сред см. раздел Использование Remote Config в серверных средах .

Вы можете использовать Firebase Remote Config для определения параметров в вашем приложении и обновления их значений в облаке, что позволяет изменять внешний вид и поведение приложения без необходимости распространения обновления. Это руководство подробно описывает шаги для начала работы и предоставляет примеры кода, которые можно клонировать или скачать из репозитория firebase/quickstart-android на GitHub.

Шаг 1: Добавьте 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 для Android. Для управления версиями библиотеки мы рекомендуем использовать Firebase Android BoM .

   Кроме того, в рамках настройки Analytics вам необходимо добавить Firebase SDK для Google Analytics в ваше приложение.

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

   Ищете модуль библиотеки, специфичный для Kotlin? С октября 2023 года ( Firebase BoM 32.5.0) разработчики как Kotlin, так и Java смогут использовать основной модуль библиотеки (подробности см. в разделе часто задаваемых вопросов об этой инициативе ).

Примечание: Поскольку Android SDK зависит от REST API Remote Config , убедитесь, что вы не отключаете этот API, который в типичном проекте включен по умолчанию.

Шаг 2: Получите объект-синглтон 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 используется для хранения значений параметров приложения по умолчанию, извлечения обновленных значений параметров из бэкэнда и управления тем, когда извлеченные значения становятся доступны вашему приложению.

Во время разработки рекомендуется установить относительно небольшой минимальный интервал выборки. Подробнее см. в разделе «Регулирование» .

Шаг 3: Установите значения параметров приложения по умолчанию

Вы можете задать значения параметров приложения по умолчанию в объекте Remote Config , чтобы приложение вело себя так, как задумано, до того, как оно подключится к бэкэнду Remote Config , и чтобы значения по умолчанию были доступны, если в бэкэнде ничего не задано.

Важно: Не храните конфиденциальные данные в ключах или значениях параметров Remote Config . Данные Remote Config шифруются при передаче, но конечные пользователи могут получить доступ к любому параметру Remote Config по умолчанию или извлеченному параметру, доступному их клиентскому приложению.

1. Определите набор имён параметров и значений параметров по умолчанию, используя объект Map или XML-файл ресурсов, хранящийся в папке res/xml вашего приложения. В примере приложения Remote Config для быстрого запуска имена и значения параметров по умолчанию определяются с помощью XML-файла .

   Если вы уже настроили значения параметров бэкэнда 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
   

   Консоль 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) . Чтобы получить эти значения, вызовите указанный ниже метод, который соответствует типу данных, ожидаемому вашим приложением, передав ключ параметра в качестве аргумента:

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

Шаг 5: Задайте значения параметров в бэкэнде Remote Config

Используя консоль Firebase или API-интерфейсы 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();
               }
           });

Поскольку эти обновлённые значения параметров влияют на поведение и внешний вид вашего приложения, вам следует активировать полученные значения в момент, обеспечивающий бесперебойную работу пользователя, например, при следующем открытии приложения. Дополнительную информацию и примеры см. в разделе «Стратегии загрузки Remote Config».

Примечание: Если ваше приложение не собирается с помощью Gradle, необходимо вручную добавить в него правильный строковый ресурс google_app_id , чтобы Remote Config мог инициализироваться. Плагин Gradle google-services обычно добавляет его автоматически, но нужное значение можно найти в файле google-services.json , который вы загружаете из консоли Firebase . Подробнее о получении значения google_app_id из файла google-services.json см. в разделе Обработка JSON-файла .

Шаг 7: Следите за обновлениями в режиме реального времени

После получения значений параметров вы можете использовать Remote Config в режиме реального времени для прослушивания обновлений из бэкенда Remote Config . Remote Config в режиме реального времени уведомляет подключенные устройства о наличии обновлений и автоматически извлекает изменения после публикации новой версии Remote Config .

Обновления в реальном времени поддерживаются Firebase SDK для Android v21.3.0+ ( Firebase BoM v31.2.4+).

Важно: Remote Config в реальном времени также требуется Firebase Remote Config Realtime API, который должен быть у вас уже включён. Для проверки откройте консоль Google Cloud , выберите свой проект и откройте страницу API и сервисы . API должен отображаться как включённый. Если он отсутствует или не включён, нажмите «Включить API и сервисы» , найдите Firebase Remote Config Realtime API и включите его.

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 . До версии SDK 17.0.0 ограничение составляло 5 запросов на выборку за 60 минут (в более новых версиях ограничения шире).

Совет: Начиная с Android SDK версии 21.3.0 и выше ( Firebase BoM версии 31.3.0 и выше), вы можете использовать Remote Config в реальном времени для автоматического получения обновлённых значений параметров из бэкенда Remote Config сразу после их публикации, минуя любые настройки минимального интервала выборки. Подробнее см. в разделе Прослушивание обновлений в реальном времени .

Во время разработки приложения может потребоваться очень частое получение и активация конфигураций (несколько раз в час), чтобы обеспечить быструю итерацию по мере разработки и тестирования приложения. Обновления Remote Config в режиме реального времени автоматически обходят кэш при обновлении конфигурации на сервере. Чтобы обеспечить быструю итерацию в проекте с числом разработчиков до 10, вы можете временно задать объект FirebaseRemoteConfigSettings с низким минимальным интервалом выборки ( setMinimumFetchIntervalInSeconds ) в своём приложении.

Минимальный интервал выборки по умолчанию для Remote Config составляет 12 часов. Это означает, что конфигурации не будут извлекаться из бэкенда чаще одного раза в течение 12-часового окна, независимо от фактического количества вызовов выборки. В частности, минимальный интервал выборки определяется в следующем порядке:

1. Параметр в fetch(long)
2. Параметр в FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
3. Значение по умолчанию 12 часов

Чтобы задать минимальное значение интервала выборки, используйте FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long) .

Имейте в виду, что этот параметр следует использовать только для разработки, а не для приложения, работающего в продакшене. Если вы просто тестируете приложение с небольшой командой из 10 человек, вы вряд ли достигнете почасовой квоты на стороне сервиса. Но если вы распространяете приложение среди тысяч тестовых пользователей с очень низким минимальным интервалом загрузки, ваше приложение, вероятно, достигнет этой квоты.

Следующие шаги

Если вы еще этого не сделали, изучите варианты использования Remote Config и посмотрите на некоторые из ключевых концепций и документации «Расширенные стратегии», в том числе:

• Управлять версиями шаблона Remote Config
• Стратегии загрузки конфигурации