Вы можете использовать Firebase Remote Config для определения параметров в вашем приложении и обновления их значений в облаке, что позволяет вам изменять внешний вид и поведение вашего приложения без распространения обновления приложения. Это руководство проведет вас через шаги для начала работы и предоставит несколько примеров кода, все из которых доступны для клонирования или загрузки из репозитория firebase/quickstart-android GitHub.
Шаг 1: Добавьте Firebase и Remote Config SDK в свое приложение
Если вы еще этого не сделали, добавьте Firebase в свой проект Android .
Для Remote Config требуется Google Analytics для условного таргетинга экземпляров приложения на свойства и аудитории пользователя. Убедитесь, что вы включили Google Analytics в своем проекте.
В файле 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.14.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.
Ищете модуль библиотеки, специфичный для Kotlin? Начиная с октября 2023 года ( Firebase BoM 32.5.0) разработчики Kotlin и Java смогут полагаться на основной модуль библиотеки (подробности см. в разделе часто задаваемых вопросов об этой инициативе ).(Альтернатива) Добавьте зависимости библиотеки 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.4.0") }
Шаг 2: Получите объект-синглтон 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);
Объект Singleton используется для хранения значений параметров приложения по умолчанию, извлечения обновленных значений параметров из бэкэнда и управления тем, когда извлеченные значения становятся доступными для вашего приложения.
Во время разработки рекомендуется установить относительно низкий минимальный интервал выборки. Подробнее см. в разделе Throttling .
Шаг 3: Установите значения параметров приложения по умолчанию
Вы можете задать значения параметров приложения по умолчанию в объекте Remote Config , чтобы ваше приложение вело себя так, как задумано, до того, как оно подключится к бэкэнду Remote Config , и чтобы были доступны значения по умолчанию, если в бэкэнде ничего не задано.
Определите набор имен параметров и значений параметров по умолчанию с помощью объекта Map или файла ресурсов XML , хранящегося в папке
res/xml
вашего приложения. Пример приложения Remote Config quickstart использует файл 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
На вкладке «Параметры» откройте меню и выберите «Загрузить значения по умолчанию» .
При появлении запроса включите .xml для Android , затем нажмите Загрузить файл .
Добавьте эти значения в объект 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)
. Чтобы получить эти значения, вызовите метод, указанный ниже, который сопоставляется с типом данных, ожидаемым вашим приложением, предоставляя ключ параметра в качестве аргумента:
Шаг 5: Задайте значения параметров в бэкэнде Remote Config
Используя консоль Firebase или API-интерфейсы Remote Config backend , вы можете создавать новые значения по умолчанию на стороне сервера, которые переопределяют значения в приложении в соответствии с желаемой условной логикой или таргетингом пользователя. В этом разделе описываются шаги консоли Firebase для создания этих значений.
- В консоли Firebase откройте свой проект.
- Выберите Remote Config в меню, чтобы просмотреть панель управления Remote Config .
- Определите параметры с теми же именами, что и параметры, которые вы определили в своем приложении. Для каждого параметра вы можете задать значение по умолчанию (которое в конечном итоге переопределит соответствующее значение по умолчанию в приложении), а также можете задать условные значения. Чтобы узнать больше, см. Параметры и условия Remote Config .
Если используются пользовательские условия сигнала , определите атрибуты и их значения. В следующих примерах показано, как определить пользовательское условие сигнала.
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: Извлечение и активация значений
- Чтобы получить значения параметров из бэкэнда Remote Config , вызовите метод
fetch()
. Любые значения, которые вы устанавливаете в бэкэнде, извлекаются и сохраняются в объекте Remote Config . Чтобы сделать извлеченные значения параметров доступными для вашего приложения, вызовите метод
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 для получения дополнительной информации и примеров.
Шаг 7: Следите за обновлениями в режиме реального времени
После получения значений параметров вы можете использовать Remote Config в реальном времени для прослушивания обновлений из бэкэнда Remote Config . Remote Config в реальном времени посылает подключенным устройствам сигналы о наличии обновлений и автоматически извлекает изменения после публикации новой версии Remote Config .
Обновления в реальном времени поддерживаются Firebase SDK для Android v21.3.0+ ( Firebase BoM v31.2.4+).
В вашем приложении используйте
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); } });
В следующий раз, когда вы опубликуете новую версию Remote Config , устройства, на которых запущено ваше приложение и которые ожидают изменений, вызовут
ConfigUpdateListener
.
Дросселирование
Если приложение выполняет выборку слишком много раз за короткий промежуток времени, вызовы выборки ограничиваются, и SDK возвращает FirebaseRemoteConfigFetchThrottledException
. До версии SDK 17.0.0 ограничение составляло 5 запросов выборки в 60-минутном окне (более новые версии имеют более разрешительные ограничения).
Во время разработки приложения вам может потребоваться получать и активировать конфигурации очень часто (много раз в час), чтобы иметь возможность быстро выполнять итерации по мере разработки и тестирования приложения. Обновления Remote Config в реальном времени автоматически обходят кэш, когда конфигурация обновляется на сервере. Чтобы обеспечить быструю итерацию в проекте с числом разработчиков до 10, вы можете временно задать объект FirebaseRemoteConfigSettings
с низким минимальным интервалом выборки ( setMinimumFetchIntervalInSeconds
) в своем приложении.
Минимальный интервал выборки по умолчанию для Remote Config составляет 12 часов, что означает, что конфигурации не будут извлекаться из бэкэнда чаще одного раза в 12-часовом окне, независимо от того, сколько вызовов выборки фактически сделано. В частности, минимальный интервал выборки определяется в следующем порядке:
- Параметр в
fetch(long)
- Параметр в
FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
- Значение по умолчанию 12 часов.
Чтобы задать минимальное значение интервала выборки, используйте FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long)
.
Следующие шаги
Если вы еще этого не сделали, изучите варианты использования Remote Config и посмотрите на некоторые из ключевых концепций и документации «Расширенные стратегии», в том числе:
,Вы можете использовать Firebase Remote Config для определения параметров в вашем приложении и обновить их значения в облаке, что позволяет вам изменять внешний вид и поведение вашего приложения без распространения обновления приложения. Это руководство проходит через шаги, чтобы начать работу и предоставляет некоторый пример кода, который доступен для клонирования или загрузки с репозитория Github Firebase/QuickStart-Android .
Шаг 1: Добавьте Firebase и удаленную конфигурацию SDK в ваше приложение
Если вы еще этого не сделали, добавьте Firebase в свой проект Android .
Для Remote Config Google Analytics требуется для условного нацеливания экземпляров приложений на свойства пользователя и аудиторию. Убедитесь, что вы включите Google Analytics в свой проект.
В вашем модуле (App-Level) файл Gradle (обычно
<project>/<app-module>/build.gradle.kts
или<project>/<app-module>/build.gradle
) добавьте зависимость для Remote Config для Android. Мы рекомендуем использовать Firebase Android BoM для управления версией библиотеки.Кроме того, в рамках настройки Analytics вам необходимо добавить SDK Firebase для Google Analytics в ваше приложение.
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.14.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 , ваше приложение всегда будет использовать совместимые версии библиотек Android Firebase.
Ищете модуль библиотеки, специфичный для котлина? Начиная с октября 2023 года ( Firebase BoM 32.5.0) , разработчики Kotlin и Java могут зависеть от основного библиотечного модуля (подробности см. FAQ об этой инициативе ).(Альтернатива) Добавить зависимости библиотеки 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.4.0") }
Шаг 2: Получите 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);
Объект Singleton используется для хранения значений параметров по умолчанию в приложении, получения обновленных значений параметров из бэкэнда и управления, когда извлеченные значения доступны для вашего приложения.
Во время разработки рекомендуется установить относительно низкий минимальный интервал выборки. Смотрите дросселирование для получения дополнительной информации.
Шаг 3: Установите значения параметров по умолчанию в приложении
Вы можете установить значения параметров по умолчанию в приложении в объекте Remote Config , чтобы ваше приложение ведет себя так, как задумано, прежде чем подключиться к Remote Config , и поэтому значения по умолчанию доступны, если их не установлены в бэкэнд.
Определите набор имен параметров и значения параметров по умолчанию, используя объект MAP или файл ресурса XML, хранящийся в папке
res/xml
вашего приложения. В примере Remote Config QuickStart используется 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
На вкладке «Параметры» откройте меню и выберите «Значения по умолчанию» .
При запросе, включите .xml для Android , затем нажмите «Загрузить файл» .
Добавьте эти значения в объект 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)
. Чтобы получить эти значения, вызовите метод, перечисленный ниже, который отображает тип данных, ожидаемый вашим приложением, предоставляя ключ параметра в качестве аргумента:
Шаг 5: Установите значения параметров в бэкэнде Remote Config
Используя консоль Firebase или API-интерфейсы Remote Config , вы можете создать новые значения по умолчанию на стороне сервера, которые переопределяют значения в приложении в соответствии с желаемой условной логикой или таргетингом пользователя. В этом разделе описываются шаги консоли Firebase для создания этих значений.
- В консоли Firebase откройте свой проект.
- Выберите Remote Config в меню, чтобы просмотреть Remote Config .
- Определите параметры с теми же именами, что и параметры, которые вы определили в вашем приложении. Для каждого параметра вы можете установить значение по умолчанию (которое в конечном итоге будет переопределить соответствующее значение по умолчанию в приложении), и вы также можете установить условные значения. Чтобы узнать больше, см. Remote Config .
При использовании пользовательских условий сигнала определите атрибуты и их значения. Следующие примеры показывают, как определить пользовательское условие сигнала.
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: Принесите и активируйте значения
- Чтобы получить значения параметров из Remote Config , вызовите метод
fetch()
. Любые значения, которые вы устанавливаете в бэкэнде, извлекаются и хранятся в объекте Remote Config . Чтобы сделать полученные значения параметров, доступных для вашего приложения, вызовите метод
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(); } });
Поскольку эти обновленные значения параметров влияют на поведение и внешний вид вашего приложения, вы должны активировать извлекаемые значения за раз, которые обеспечивают плавный опыт для вашего пользователя, например, в следующий раз, когда пользователь открывает ваше приложение. См. Удаленную стратегии загрузки конфигурации для получения дополнительной информации и примеров.
Шаг 7: Слушайте обновления в режиме реального времени
После того, как вы получите значения параметров, вы можете использовать Remote Config в реальном времени для прослушивания обновлений из Remote Config . Remote Config в реальном времени на подключенные устройства, когда доступны обновления, и автоматически получает изменения после публикации новой версии Remote Config .
Обновления в реальном времени поддерживаются Firebase SDK для Android V21.3.0+ ( Firebase BoM V31.2.4+).
В вашем приложении используйте
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); } });
В следующий раз, когда вы публикуете новую версию вашей Remote Config , устройств, которые запускают ваше приложение и прислушиваются к изменениям, вызовут
ConfigUpdateListener
.
Дросселирование
Если приложение приносит слишком много раз за короткий период, вызовы избирателей углублены, а SDK возвращает FirebaseRemoteConfigFetchThrottledException
. Перед версией SDK 17.0.0 лимит был 5 запросов избрать в 60 -минутном окне (новые версии имеют более разрешительные ограничения).
Во время разработки приложений вы можете захотеть извлечь и активировать конфигурации очень часто (много раз в час), чтобы вы могли быстро итерации по мере разработки и тестирования своего приложения. Обновления Remote Config в реальном времени автоматически обходят кэш, когда конфигурация обновляется на сервере. Чтобы приспособить быструю итерацию в проекте с 10 разработчиками, вы можете временно установить объект FirebaseRemoteConfigSettings
с низким минимальным интервалом выборки ( setMinimumFetchIntervalInSeconds
) в вашем приложении.
Минимальный интервал по умолчанию для Remote Config составляет 12 часов, что означает, что конфигурации не будут извлечены из бэкэнда более одного раза в 12 -часовом окне, независимо от того, сколько вызовов на самом деле сделано. В частности, минимальный интервал выборки определяется в следующем порядке:
- Параметр в
fetch(long)
- Параметр в
FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
- Значение по умолчанию 12 часов
Чтобы установить минимальный интервал выборки на пользовательское значение, используйте 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: