Codelab: Como integrar a Configuração remota no Android

1. Introdução

Última atualização:09/03/2021

O que é a Configuração remota do Firebase?

A Configuração remota do Firebase é um serviço em nuvem que permite alterar o comportamento e a aparência do aplicativo sem exigir que os usuários façam o download de uma atualização do aplicativo sem nenhum custo. Ao usar a Configuração remota, você cria valores padrão no app que controlam o comportamento e a aparência dele. Depois, você pode usar o Console do Firebase ou as APIs de back-end da Configuração remota para substituir os valores padrão no app para todos os usuários ou segmentos da sua base de usuários. O app controla quando as atualizações são aplicadas e pode verificar frequentemente se há atualizações e aplicá-las com impacto insignificante no desempenho.

Como funciona?

A Configuração remota inclui uma biblioteca de cliente que lida com tarefas importantes, como a busca e o armazenamento em cache de valores de parâmetro, sem deixar de oferecer a você controle sobre quando os novos valores são ativados para afetar a experiência do usuário do seu app. Isso permite que você proteja a experiência no seu app controlando o tempo das alterações.

Os métodos get da biblioteca de cliente da Configuração remota oferecem um único ponto de acesso para os valores de parâmetros. Seu app recebe valores do lado do servidor usando a mesma lógica usada para receber os valores padrão dentro do app. Assim, você pode adicionar os recursos da Configuração remota ao seu app sem escrever muito código.

Para substituir os valores padrão no app, use o Console do Firebase ou as APIs de back-end da Configuração remota para criar parâmetros com os mesmos nomes dos parâmetros usados no seu app. Para cada parâmetro, é possível definir um valor padrão do servidor para substituir o padrão no app, além de criar valores condicionais para substituir o valor padrão no app para instâncias que atendem a determinadas condições. Este gráfico mostra como os valores de parâmetros são priorizados no back-end da Configuração remota e no seu app:

O que você vai aprender

• Como implementar a Configuração remota do Firebase
• Como usar a Configuração remota do Firebase para alterar valores sem atualizar o app.

O que é necessário

• A versão mais recente do Android Studio.
• Uma conta do Firebase
• (recomendado, mas opcional) Um dispositivo físico Android para executar o app.
• Conhecimento básico de Java ou Kotlin.

2. Etapas da configuração

(Opcional) Fazer o download do exemplo de código

Neste codelab, você criará seu próprio app de teste, mas se quiser ver e executar o app de exemplo já existente, faça o download do exemplo de código do guia de início rápido.

Clique no botão abaixo para fazer o download de todo o código para este codelab:

Download do código-fonte

Descompacte o arquivo ZIP transferido por download. Isso descompactará uma pasta raiz chamada quickstart-android-master.

...ou clonar o repositório do GitHub pela linha de comando.

$ git clone https://github.com/firebase/quickstart-android.git

O repositório contém várias pastas. Vamos usar a pasta config.

(Opcional) Importar o exemplo de código

Inicie o Android Studio e selecione Import project na tela inicial. Em seguida, abra a pasta salva e selecione a pasta config. Em seguida, clique em "Abrir".

Criar novo projeto Android

1. No Android Studio, inicie um novo projeto
2. Selecionar atividade básica
3. No menu "Configure seu projeto", tela:
4. Escolha o nome do projeto. O nome do pacote e o local para salvar serão gerados automaticamente.
5. Linguagem: Java
6. SDK mínimo 16

3. Adicionar o Firebase e o Firebase Analytics ao seu projeto do Android

Criar um projeto do Firebase

Antes de adicionar o Firebase ao seu app Android, é preciso criar um projeto do Firebase para conectá-lo ao seu app iOS. Consulte Noções básicas sobre projetos do Firebase para mais informações.

1. No Console do Firebase, clique em Adicionar projeto e selecione ou insira o Nome do projeto.

Se você tiver um projeto do Google Cloud Platform (GCP), poderá selecioná-lo no menu suspenso para adicionar recursos do Firebase a ele.

2. (Opcional) Se você estiver criando um novo projeto, poderá editar o ID do projeto.

O Firebase atribui automaticamente um ID exclusivo ao seu projeto. Acesse "Noções básicas sobre projetos do Firebase" para saber como o Firebase usa o ID do projeto.

Observação: não será possível alterar o ID do projeto depois que o Firebase provisionar os recursos para o projeto. Para usar um identificador específico, é necessário editar o ID do projeto durante essa etapa de configuração.

3. Clique em Continuar.
4. Configure o Google Analytics para seu projeto e tenha a melhor experiência possível ao usar qualquer um dos seguintes produtos do Firebase:

• Firebase Crashlytics
• Firebase Previsões
• Firebase Cloud Messaging
• Mensagens no app do Firebase
• Configuração remota do Firebase
• Teste A/B do Firebase

Quando solicitado, escolha entre usar uma conta do Google Analytics ou criar uma nova. Se você optar por criar uma nova conta, selecione o local dos relatórios do Analytics e aceite as configurações de compartilhamento de dados e os termos do Google Analytics referentes ao seu projeto.

5. Clique em Criar projeto (ou Adicionar Firebase, se você estiver usando um projeto do GCP).

O Firebase provisiona recursos automaticamente para seu projeto. Quando o processo for concluído, você será direcionado para a página de visão geral do seu projeto no Console do Firebase.

Registrar o app com o Firebase

Depois de criar um projeto do Firebase, é possível adicionar seu app Android a ele.

Consulte Noções básicas sobre projetos do Firebase para ver práticas recomendadas e informações sobre como adicionar apps a um projeto, incluindo como lidar com diversas variantes de build.

1. Acesse o Console do Firebase.
2. Na parte de cima da página "Visão geral do projeto", clique no ícone Android para iniciar o fluxo de trabalho de configuração. Se você já adicionou um app ao seu projeto do Firebase, clique em "Adicionar app" para exibir as opções da plataforma.
3. Digite o nome do pacote do app no campo Nome do pacote Android.
4. (Opcional) Digite o apelido do app.
5. Deixe o campo SHA-1 em branco, porque SHA-1 não é obrigatório para este projeto.
6. Clique em Registrar app.

Adicionar o arquivo de configuração do Firebase

Em seguida, você receberá uma solicitação para fazer o download de um arquivo de configuração que contenha todos os metadados necessários do Firebase para seu app. Clique em Fazer o download do google-services.json para receber o arquivo de configuração do Firebase para Android (google-services.json).

No arquivo do Gradle no nível do projeto (build.gradle), adicione regras para incluir o plug-in do Gradle para Serviços do Google. Verifique se você também tem o repositório Maven do Google.

build.gradle no nível do projeto (<project>/build.gradle):

buildscript {

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
  }

  dependencies {
    // ...

    // Add the following line:
    classpath 'com.google.gms:google-services:4.3.5'  // Google Services plugin
  }
}

allprojects {
  // ...

  repositories {
    // Check that you have the following line (if not, add it):
    google()  // Google's Maven repository
    // ...
  }
}

No arquivo Gradle do módulo (nível do app), que geralmente é app/build.gradle, aplique o plug-in do Gradle para Serviços do Google:

build.gradle no nível do app (<project>/<app-module>/build.gradle):

apply plugin: "com.android.application"

// Adicione a linha a seguir:

apply plugin: 'com.google.gms.google-services' // Plug-in do Google Services

android {

// ...

}

Adicionar o SDK do Firebase ao seu app Android

Na Configuração remota, o Google Analytics é necessário para a segmentação condicional de instâncias de apps para públicos-alvo e propriedades do usuário. Ative o Google Analytics no seu projeto.

Isso já é feito no exemplo de código do guia de início rápido.

Usando a BoM do Firebase para Android, declare a dependência da biblioteca Android da Configuração remota no seu arquivo do Gradle (nível do app) do módulo, que geralmente é app/build.gradle. Com a BoM do Firebase para Android, seu app sempre vai usar versões compatíveis das bibliotecas do Firebase para Android.

Além disso, como parte da configuração do Google Analytics, você precisa adicionar o SDK do Firebase para Google Analytics ao seu app. Em dependências, adicione o seguinte código:

app/build.gradle

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

    // Declare 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'
}

Sincronizar seu projeto com arquivos do Gradle

Para garantir que todas as dependências estejam disponíveis para o app, sincronize o projeto com os arquivos do Gradle selecionando File > Sincronizar o projeto com arquivos do Gradle (link em inglês).

4. Analisar os principais componentes da Configuração remota

Agora vamos revisar as etapas para usar a Configuração remota em um app. Essas etapas já foram concluídas no código do codelab de início rápido. Use esta seção ao revisar o código do codelab de início rápido para entender o que está acontecendo.

1. Acessar 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:

MainActivity.java

mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);

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

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

Ao colocar isso em MainActivity.java, novos valores serão buscados quando o app for iniciado. O exemplo de início rápido busca os valores de parâmetro atualizados ao pressionar o botão.

2. Definir valores de parâmetros padrão no app

É possível definir os valores de parâmetros padrão no app no objeto do Configuração remota. Assim, o app se comporta de maneira previsível antes de se conectar ao back-end do recurso e os valores padrão estarão disponíveis, caso nenhum tenha sido definido no back-end.

É possível definir um conjunto de valores padrão e nomes de parâmetros usando um objeto Map ou um arquivo de recursos XML armazenado na pasta res/xml do app. O app de amostra do guia de início rápido da Configuração remota usa um arquivo XML para definir valores e nomes de parâmetros padrão. Veja como criar seu próprio arquivo XML:

1. Crie uma pasta xml na pasta res.

2. Clique com o botão direito do mouse na pasta xml recém-criada e crie um arquivo.

3. Defina os valores padrão. Na próxima seção, você vai tentar alterar os valores padrão no arquivo XML do guia de início rápido da Configuração remota.
4. Adicione esses valores ao objeto da Configuração remota usando setDefaultsAsync(int), conforme mostrado:

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

3. Receber valores de parâmetros para uso no app

É possível receber valores de parâmetro do objeto da Configuração remota. Se você definir valores no back-end, buscá-los e ativá-los, eles estarão disponíveis para o app. Caso contrário, você recebe os valores de parâmetros no app configurados usando setDefaultsAsync(int). Para receber esses valores, chame o método listado abaixo que está associado ao tipo de dado esperado pelo app, fornecendo a chave de parâmetro como argumento:

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

4. buscar e ativar valores

1. Para buscar valores de parâmetro usando o 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 valores de parâmetro recuperados ao seu app, chame o método activate(). Para casos em que você quer buscar e ativar valores em uma chamada, é possível usar uma solicitação fetchAndActivate() para buscar valores de back-end do Configuração remota e disponibilizá-los para o aplicativo:

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

Como esses valores de parâmetro atualizados afetam o comportamento e a aparência do aplicativo, ative os valores buscados em um momento que garanta uma boa experiência para o usuário, como na próxima vez que ele abrir o aplicativo. Consulte Estratégias de carregamento da Configuração remota para mais informações e exemplos.

Observação:se o app não for criado com o Gradle, adicione manualmente o recurso de string google_app_id correto para que a Configuração remota seja inicializada. O plug-in do Gradle google-services normalmente adiciona isso automaticamente, mas você pode encontrar o valor apropriado no arquivo google-services.json, disponível para download no Console do Firebase. Para mais informações sobre como receber o valor google_app_id do arquivo google-services.json, consulte Como processar o arquivo JSON.

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 uma janela de 60 minutos. As versões mais recentes têm limites mais flexíveis.

Durante o desenvolvimento de apps, é recomendável buscar e ativar configurações com muita frequência (várias vezes por hora) para permitir uma rápida iteração conforme você desenvolve e testa o app. Para acomodar a iteração rápida em um projeto com até 10 desenvolvedores, é possível definir 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. Isso significa que as configurações não serão buscadas no back-end mais de uma vez em uma janela de 12 horas, independentemente 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 como um valor personalizado, use FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long).

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

5. Mudar o comportamento do app com a Configuração remota

Mudar os parâmetros padrão no app

Abra res/xml/remote_config_defaults.xml e mude os valores padrão.

res/xml/remote_config_defaults.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- START xml_defaults -->
<defaultsMap>
    <entry>
        <key>loading_phrase</key>
        <value>Fetching config...</value>
    </entry>
    <entry>
        <key>welcome_message_caps</key>
        <value>false</value>
    </entry>
    <entry>
        <key>welcome_message</key>
        <value>Welcome to my awesome app!</value>
    </entry>
</defaultsMap>
    <!-- END xml_defaults -->

Verificar a mudança no valor padrão no app

1. Execute o projeto em um emulador ou usando um dispositivo de teste para confirmar o comportamento.
2. Clique em Open na versão Java ou Kotlin.

3. Revise a mensagem de recepção na visualização principal.

Definir valores de parâmetro no back-end da Configuração remota

Agora vamos testar o envio de valores pela Configuração remota. Com o Console do Firebase ou as APIs de back-end da Configuração remota, é possível criar novos valores padrão do lado do servidor que substituem os valores no app de acordo com a lógica condicional ou a segmentação por usuário desejadas. Esta seção descreve as etapas do Console do Firebase para criar esses valores.

1. Abra o Console do Firebase e abra seu projeto.
2. Selecione Configuração remota no menu à esquerda da seção "Envolver" para ver o painel da Configuração remota.
3. Em Adicionar um parâmetro, insira Parameter key.. Em Default value, adicione o texto que você quiser. Em seguida, clique em "Adicionar parâmetro". Neste codelab, vamos usar as chaves de parâmetro no arquivo res/xml/remote_config_defaults.xml. Consulte a tabela abaixo para mais detalhes:

Chave de parâmetro	Valor padrão (remote_config_defaults.xml)	Descrição
loading_phrase	Buscando configuração...	String; Exibido ao buscar valores da Configuração remota.
welcome_message_caps	falso	Booleano; Se verdadeiro, altera a Welcome_message para todas as letras maiúsculas
welcome_message	Este é meu app incrível!	String; Mensagem de recepção

Exemplo de captura de tela:

4. Quando terminar de adicionar parâmetros, clique em "Publicar alterações".
5. Execute o app em um emulador ou dispositivo novamente e clique no botão "Fetch Remote Welcome". agora.

6. A mensagem de boas-vindas precisa ser atualizada com base no parâmetro e nos valores da Configuração remota.

6. Parabéns

Parabéns! Você usou a Configuração remota para alterar a mensagem de recepção. Há muitas outras maneiras de utilizar a Configuração remota para alterar e personalizar apps. Confira os recursos adicionais abaixo:

• Primeiros passos com a Configuração remota do Firebase
• O que posso fazer com a Configuração remota?
• API Firebase Remote Config
• Criar experimentos de Configuração remota do Firebase com o Teste A/B