Introdução à Configuração remota do Firebase

iOS+ Android Web Flutter Unity C++

Importante: nesta seção, descrevemos as etapas para configurar Remote Config com clientes da Web e de dispositivos móveis. Para ambientes de servidor, consulte Usar Remote Config em ambientes de servidor.

Use Firebase Remote Config para definir parâmetros no app e atualizar os respectivos valores na nuvem. Assim, você modifica a aparência e o comportamento do app sem precisar distribuir uma atualização. Este guia traz noções básicas e exemplos de código, que estão disponíveis para clonagem ou download no repositório do GitHub firebase/quickstart-android.

Etapa 1: adicionar o Firebase e o SDK da Configuração remota ao app

1. Adicione o Firebase ao projeto para Android, caso ainda não tenha feito isso.

2. Em Remote Config, Google Analytics é necessário para a segmentação condicional de instâncias de app para propriedades de usuário e públicos. Ative Google Analytics no projeto.

3. No arquivo Gradle do módulo (nível do app) (geralmente <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), adicione a dependência da biblioteca do Remote Config para Android. Recomendamos o uso do Firebase Android BoM para controlar o controle de versões da biblioteca.

   Além disso, como parte da configuração de Analytics, você precisa adicionar o SDK do Firebase para Google Analytics ao app.

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

   Com a Firebase Android BoM, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.

   (Alternativa) Adicionar dependências das bibliotecas do Firebase sem usar o BoM

   Se você preferir não usar o Firebase BoM, especifique cada versão das bibliotecas do Firebase na linha de dependência correspondente.

   Se você usa várias bibliotecas do Firebase no app, recomendamos utilizar o BoM para gerenciar as versões delas, porque isso ajuda a garantir a compatibilidade de todas as bibliotecas.

   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.0.1")
       implementation("com.google.firebase:firebase-analytics:22.1.2")
   }

   Está procurando um módulo de biblioteca específico do Kotlin? A partir de outubro de 2023 (Firebase BoM 32.5.0), os desenvolvedores Kotlin e Java poderão depender do módulo da biblioteca principal. Para mais detalhes, consulte Perguntas frequentes sobre essa iniciativa.

Observação: como o SDK do Android tem uma dependência na API REST de Remote Config, não desative essa API, que é ativada por padrão em um projeto comum.

Etapa 2: acessar o objeto singleton de Remote Config

Receba uma instância de objeto de Remote Config e defina o intervalo mínimo de busca para permitir atualizações frequentes:

Kotlin+KTX

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

O objeto Singleton é usado para armazenar valores de parâmetro padrão no app, buscar valores de parâmetro atualizados no back-end e controlar quando eles são disponibilizados para o app.

Durante o desenvolvimento, recomendamos definir um intervalo de busca mínimo relativamente baixo. Para mais informações, consulte Limitação.

Etapa 3: definir os valores de parâmetros padrão no app

É possível definir os valores de parâmetro padrão no app com Remote Config. Assim, o app se comporta de maneira previsível antes de se conectar ao back-end de Remote Config e os valores padrão ficam disponíveis, caso nenhum tenha sido definido no back-end.

Importante: não armazene dados confidenciais em chaves ou valores de parâmetros de Remote Config. Os dados de Remote Config são criptografados em trânsito, mas os usuários finais podem acessar qualquer parâmetro padrão ou buscado de Remote Config que esteja disponível para a instância do app cliente.

1. Defina um conjunto de nomes de parâmetro e valores de parâmetro padrão usando um objeto Map ou um arquivo de recursos XML (ambos em inglês) armazenado na pasta res/xml do app. O app de exemplo do guia de início rápido de Remote Config usa um arquivo XML para definir nomes e valores de parâmetro padrão.

   Depois de configurar os valores de parâmetro de back-end de Remote Config, faça o download de um arquivo XML gerado com todos os valores padrão para salvar no diretório res/xml do app:

   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
   

   Console do Firebase

   1. Na guia Parâmetros, abra o Menu e selecione Fazer o download dos valores padrão.

   2. Quando solicitado, ative a opção .xml para Android e clique em Fazer o download do arquivo.

2. Adicione esses valores ao objeto de Remote Config usando setDefaultsAsync(int), conforme mostrado:

   Kotlin+KTX

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

Etapa 4: receber valores de parâmetros para uso no app

Agora você pode receber valores de parâmetro do objeto de Remote Config. Se você definir valores no back-end, buscá-los e ativá-los, eles vão estar disponíveis para o app. Caso contrário, você vai receber os valores de parâmetro configurados no app com setDefaultsAsync(int). Para ter esses valores, chame o método listado a seguir que está associado ao tipo de dado esperado pelo app, fornecendo a chave de parâmetro como argumento:

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

Etapa 5: definir valores de parâmetros no back-end de Remote Config

Com o console de Firebase ou as APIs de back-end de Remote Config, é possível criar valores padrão do lado do servidor que substituem os valores no app de acordo com a lógica condicional ou a segmentação de usuário pretendidas. Nesta seção, descrevemos as etapas a serem seguidas no console de Firebase para criar esses valores.

1. Abra o projeto no console de Firebase.
2. Selecione Remote Config no menu para acessar o painel de Remote Config.
3. Defina os parâmetros com nomes iguais aos que estão no app. Para cada um, você pode definir um valor padrão, que vai substituir o valor padrão correspondente no app, e valores condicionais. Saiba mais em Parâmetros e condições de Remote Config.

Etapa 6: buscar e ativar os valores

1. Para buscar os valores de parâmetro do back-end de Remote Config, chame o método fetch(). Todos os valores definidos no back-end são buscados e armazenados no objeto de Remote Config.

2. Para disponibilizar valores de parâmetro buscados ao seu app, chame o método activate().

   Para buscar e ativar valores em uma chamada, use uma solicitação fetchAndActivate() para buscar valores no back-end de Remote Config e disponibilizá-los ao app:

   Kotlin+KTX

   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();
               }
           });

Esses valores de parâmetro atualizados afetam o comportamento e a aparência do app. Por isso, ative-os sem prejudicar a experiência do usuário, como da próxima vez que ele abrir o app. Confira informações e exemplos em Estratégias de carregamento da Configuração remota.

Observação: se o app não foi criado com o Gradle, adicione manualmente a ele o recurso de string google_app_id correto para inicializar Remote Config Em geral, isso é feito automaticamente pelo plug-in do Gradle google-services, mas é possível encontrar o valor apropriado no arquivo google-services.json, disponível para download no console de Firebase. Para mais informações sobre como receber o valor google_app_id do arquivo google-services.json, consulte Como processar o arquivo JSON.

Etapa 7: detectar atualizações em tempo real

Depois de buscar valores de parâmetros, é possível usar Remote Config em tempo real para detectar atualizações do back-end de Remote Config. Remote Config em tempo real sinaliza para dispositivos conectados quando atualizações estão disponíveis e busca as mudanças automaticamente depois que você publica uma nova versão de Remote Config.

O SDK de Firebase para Android v21.3.0 e mais recente (Firebase BoM v31.2.4 e mais recente) é compatível com atualizações em tempo real.

Importante: Remote Config em tempo real também exige a API Realtime de Firebase Remote Config, que já deve estar ativada. Para verificar, abra o console de Google Cloud, selecione o projeto e abra a página APIs e serviços. A API precisa aparecer como ativada. Se ela estiver ausente ou desativada, clique em Ativar APIs e serviços, encontre a API Realtime de Firebase Remote Config e ative-a.

1. No seu app, use addOnConfigUpdateListener() para detectar atualizações e buscar novos valores de parâmetros automaticamente. Implemente o callback onUpdate() para ativar a configuração atualizada.

   Kotlin+KTX

   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. Na próxima vez que você publicar uma nova versão de Remote Config, os dispositivos que estão executando o app e detectando as mudanças vão chamar ConfigUpdateListener.

Limitação

Se um aplicativo fizer muitas buscas em um curto período, as chamadas de busca serão limitadas e o SDK retornará FirebaseRemoteConfigFetchThrottledException. Antes da versão 17.0.0 do SDK, o limite era de cinco solicitações de busca em um intervalo de 60 minutos (as versões mais recentes têm limites mais permissivos).

Dica: desde o SDK do Android v21.3.0 ou mais recente (Firebase BoM v31.3.0 ou mais recente), é possível usar Remote Config em tempo real para buscar automaticamente valores de parâmetro atualizados no back-end de Remote Config assim que eles são publicados, ignorando qualquer configuração mínima do intervalo de busca. Para mais informações, consulte Detectar atualizações em tempo real.

Durante o desenvolvimento de apps, recomendamos que você faça buscas e ative as configurações frequentemente (várias vezes por hora) para permitir a iteração rápida enquanto desenvolve e testa o app. As atualizações de Remote Config em tempo real ignoram automaticamente o cache quando a configuração é atualizada no servidor. Para acomodar a iteração rápida em um projeto com até 10 desenvolvedores, é possível adicionar temporariamente um objeto FirebaseRemoteConfigSettings com um baixo intervalo de busca mínimo (setMinimumFetchIntervalInSeconds) ao app.

O intervalo de busca mínimo padrão de Remote Config é de 12 horas. Portanto, a busca pelas configurações no back-end não vai acontecer mais de uma vez em 12 horas, e isso não é impactado pelo número de chamadas de busca realmente realizadas. O intervalo mínimo de busca é determinado especificamente na seguinte ordem:

1. O parâmetro em fetch(long)
2. O parâmetro em FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
3. O valor padrão de 12 horas

Para definir o intervalo mínimo de busca para um valor personalizado, use FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long).

Essa configuração deve ser usada apenas para desenvolvimento e não para um aplicativo em execução na produção. Se você está apenas testando seu aplicativo com uma equipe de desenvolvimento pequena de 10 pessoas, é improvável que atinja os limites de cota do serviço por hora. No entanto, se você transferiu seu aplicativo para milhares de usuários de teste com um intervalo de busca mínimo muito baixo, seu app provavelmente atingirá essa cota.

Próximas etapas

Se ainda não tiver feito isso, confira os casos de uso de Remote Config, bem como alguns dos principais conceitos e a documentação de estratégias avançadas, que incluem:

• Gerenciar versões de modelo de Remote Config
• Estratégias de carregamento de configuração