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


Use a Configuração remota do Firebase 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 as noções básicas e os exemplos de código, que estão disponíveis para clonagem ou download no repositório do GitHub firebase/quickstart-android (em inglês).

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. Na Configuração remota, o Google Analytics é necessário para a segmentação condicional de instâncias de apps para propriedades do usuário e públicos-alvo. Ative o Google Analytics no seu 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 da Configuração remota para Android. Para gerenciar o controle de versões das bibliotecas, recomendamos usar a BoM do Firebase para Android.

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

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.1.1"))

    // 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 BoM do Firebase para Android, 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 a BoM

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

    Se você usa várias bibliotecas do Firebase no seu app, recomendamos utilizar a 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.0")
    implementation("com.google.firebase:firebase-analytics:22.0.2")
}
    Está procurando um módulo de biblioteca específico do Kotlin? A partir de outubro de 2023 (BoM do Firebase 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).

Etapa 2: conseguir o objeto Singleton da Configuração remota

Receba uma instância de objeto da Configuração remota 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âmetro padrão no app

Você pode definir os valores de parâmetro padrão no app no objeto da Configuração remota. Assim, o app se comporta de maneira previsível antes de se conectar ao back-end da Configuração remota, e os valores padrão vão estar disponíveis se nenhum tiver sido definido no back-end.

  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 no guia de início rápido da Configuração remota usa um arquivo XML para definir nomes e valores de parâmetros padrão.

    Depois de configurar os valores de parâmetro de back-end da Configuração remota, 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 da Configuração remota 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âmetro para uso no app

Agora você pode receber valores de parâmetro do objeto da Configuração remota. 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 configurados no app usando setDefaultsAsync(int). Para isso, chame o método listado a seguir, que é associado ao tipo de dados esperado pelo app, fornecendo a chave de parâmetro como argumento:

Etapa 5: definir valores de parâmetro no back-end da Configuração remota

Usando o Console do Firebase ou as APIs de back-end da Configuração remota, você pode criar valores padrão do lado do servidor que substituem os valores no app conforme a lógica condicional ou a segmentação de usuário necessárias. Nesta seção, descrevemos as etapas do Console do Firebase para criar esses valores.

  1. Abra seu projeto no Console do Firebase.
  2. Selecione Configuração remota no menu para explorar o painel do recurso.
  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 da Configuração remota.

Etapa 6: buscar e ativar os valores

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

  2. Para disponibilizar esse valores de parâmetro recuperados ao aplicativo, chame o método activate().

    Se quiser buscar e ativar valores em uma chamada, use uma solicitação fetchAndActivate() para buscar valores no back-end da Configuração remota e disponibilizá-los para o 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.

Etapa 7: detectar atualizações em tempo real

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

O SDK do Firebase para Android v21.3.0 e as versões mais recentes (BoM do Firebase v31.2.4 e versões mais recentes) oferecem suporte a atualizações em tempo real.

  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() {
            @Override
            public void onComplete(@NonNull Task 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 da Configuração remota, os dispositivos que estão executando seu 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).

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 seu app. As atualizações da Configuração remota 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) no seu app.

O intervalo de busca mínimo padrão da Configuração remota é 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 independe de quantas chamadas de busca forem 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).

Próximas etapas

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