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

1. Introdução

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

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

A Configuração remota do Firebase é um serviço em nuvem que permite a alteração do comportamento e da aparência do app sem exigir que os usuários façam download de uma atualização do app. Ao usar a Configuração remota, você cria valores padrão no app que controlam o comportamento e a aparência dele. Em seguida, 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 do aplicativo ou para segmentos da sua base de usuários. O app controla quando as atualizações são aplicadas e pode verificar com frequência se há atualizações e aplicá-las com um impacto insignificante no desempenho.

Como funciona?

O recurso Configuração remota inclui uma biblioteca de cliente que trata tarefas importantes, como a busca e o armazenamento em cache de valores de parâmetros, sem deixar de oferecer a você o 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 do seu app, controlando o tempo das alterações.

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

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

O que você vai aprender

• Como implementar a Configuração remota do Firebase
• Como usar a Configuração remota do Firebase para mudar 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 Android físico para executar o app
• Conhecimentos básicos de Java ou Kotlin

2. Etapas da configuração

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

Neste codelab, você vai criar seu próprio app de teste, mas, se quiser conferir e executar o app de exemplo atual, 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:

Fazer o download do código-fonte

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

…ou clone o repositório do GitHub da 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 escolha "Import project" na tela inicial. Em seguida, abra a pasta transferida por download e selecione a pasta config. Em seguida, clique em "open".

Criar um novo projeto do Android

1. No Android Studio, inicie um novo projeto.
2. Selecione Basic Activity.
3. Na tela "Configure Your Project":
4. Escolha o nome do projeto. O nome do pacote e o local de salvamento 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 app Android, é preciso criar um projeto do Firebase para então conectá-lo ao app. Acesse Noções básicas sobre projetos do Firebase para saber mais.

1. No Console do Firebase, clique em Adicionar projeto e depois 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.

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 do Firebase. Consulte Noções básicas sobre projetos do Firebase para saber mais sobre 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 seu projeto do Firebase. Para usar um identificador específico, é necessário editar seu ID do projeto durante essa etapa de configuração.

3. Clique em Continuar.
4. Configure o Google Analytics para seu projeto, o que permite ter uma experiência ideal usando 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, selecione para usar uma conta do Google Analytics ou criar uma nova. Se você escolher criar uma nova conta, selecione o local de relatórios do Analytics e aceite as configurações de compartilhamento de dados pessoais e os Termos do Google Analytics para 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 do Firebase. Quando o processo for concluído, você será direcionado para a página de visão geral do seu projeto do Firebase no Console do Firebase.

Registrar o app no 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 saber mais sobre considerações e práticas recomendadas para adicionar apps a um projeto do Firebase, incluindo como gerenciar diversas variantes de build.

1. Acesse o Console do Firebase.
2. Na parte de cima da página de 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) Insira o Apelido do app.
5. Deixe o campo SHA-1 em branco, já que o SHA-1 não é necessário para esse projeto.
6. Clique em Registrar app.

Adicionar o arquivo de configuração do Firebase

Em seguida, você vai receber uma solicitação para fazer o download de um arquivo de configuração que contém 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 para envolvidos no projeto (build.gradle), adicione regras para incluir o plug-in do Gradle para Serviços do Google. Verifique se você tem o repositório Maven do Google também.

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 seu arquivo Gradle do módulo (nível do app) (geralmente app/build.gradle), aplique o plug-in de Serviços do Google para Gradle:

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

apply plugin: ‘com.android.application'

// Adicione a seguinte linha:

apply plugin: ‘com.google.gms.google-services' // Plug-in de Serviços do Google

android {

// ...

}

Adicionar o SDK do Firebase ao seu app Android

Na Configuração Remota, o Google Analytics é usado na segmentação condicional de instâncias de apps para propriedades do usuário e públicos-alvo. Verifique se o Google Analytics está ativado no seu projeto.

Isso já foi feito no código de início rápido de amostra.

Usando a BoM do Firebase para Android, declare a dependência da biblioteca Android do recurso Configuração remota no seu arquivo do Gradle (nível do app) do módulo, que geralmente é app/build.gradle. Ao usar a BoM do Firebase para Android, seu app sempre 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 o 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 o projeto com arquivos do Gradle

Para garantir que todas as dependências estejam disponíveis para seu app, sincronize o projeto com arquivos do Gradle selecionando File > Sync Project with Gradle Files.

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

Agora vamos analisar 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 analisar 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âmetro padrão no app, buscar valores de parâmetro atualizados no back-end e controlar quando os valores buscados 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.

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

2. Definir valores de parâmetros 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.

É possível definir um conjunto de nomes de parâmetro e valores de parâmetro padrão usando um objeto Map ou um arquivo de recursos XML 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. Confira 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 mudar os valores padrão no arquivo XML do guia de início rápido da Configuração remota.
4. Adicione esses valores ao objeto do Configuração remota usando setDefaultsAsync(int), como mostrado abaixo:

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

3. Receba os valores de parâmetros para usar no seu 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, depois, ativá-los, eles estarão disponíveis para seu app. Caso contrário, você receberá os valores no app configurados usando 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()

4. Busque e ative valores

1. Para buscar valores de parâmetro usando o back-end do 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 os valores de parâmetro recuperados ao aplicativo, chame o método activate(). Se quiser 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 app:

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

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 a Configuração remota. 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 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 (em inglês).

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 do app, talvez você queira buscar e ativar configurações com muita frequência (muitas vezes por hora) para permitir a realização de iterações à medida que desenvolve e testa seu app. Para acomodar a iteração rápida em um projeto com até 10 desenvolvedores, é possível definir temporariamente um objeto FirebaseRemoteConfigSettings com um intervalo de busca mínimo baixo (setMinimumFetchIntervalInSeconds) no 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).

Essa configuração deve ser usada apenas para desenvolvimento e não para um aplicativo em execução na produção. Se você estiver apenas testando o app com uma equipe de desenvolvimento pequena de 10 pessoas, vai ser improvável atingir 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.

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 para algo diferente.

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 de 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. Analise a mensagem de boas-vindas na visualização principal.

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

Agora vamos testar o envio de valores pela 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 o Console do Firebase e abra seu projeto.
2. Selecione Configuração remota no menu à esquerda na seção "Engage" para conferir o painel da Configuração remota.
3. Em Adicionar um parâmetro , insira a Parameter key. Em Default value adicione o texto que quiser. Em seguida, clique em "Add Parameter". Para este codelab, vamos usar as chaves de parâmetro no arquivo res/xml/remote_config_defaults.xml. Confira mais detalhes na tabela abaixo:

Chave de parâmetro	Valor padrão (remote_config_defaults.xml)	Descrição
loading_phrase	Buscando configuração...	String; exibida ao buscar valores da Configuração remota.
welcome_message_caps	falso	Booleano; se verdadeiro, muda welcome_message para todas as letras maiúsculas
welcome_message	Bem-vindo ao meu app incrível!	mensagem de boas-vindas

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 "Buscar boas-vindas remotas" desta vez.

6. A mensagem de recepção será atualizada com base no parâmetro e nos valores da Configuração remota.

6. Parabéns

Parabéns, você usou corretamente a Configuração remota para mudar a mensagem de boas-vindas. Há muitas outras maneiras de usar a Configuração remota para mudar e personalizar apps. Consulte os recursos adicionais abaixo:

• Introdução à Configuração remota do Firebase
• O que posso fazer com o Configuração remota?
• API da Configuração remota do Firebase
• Criar experimentos da Configuração remota do Firebase com o Teste A/B