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?

O Configuração remota do Firebase é um serviço em nuvem que permite mudar o comportamento e a aparência do app sem exigir que os usuários façam o download de uma atualização do app sem custo financeiro. 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 a aplicação das atualizações e consegue verificar frequentemente a existência de atualizações e aplicá-las com impacto insignificante no desempenho.

Como funciona?

A 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 mudanças.

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 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 daqueles usados no app. Para cada parâmetro, é possível definir um valor padrão do lado do servidor para substituir o valor padrão no app. Também é possível criar valores condicionais para substituir o valor padrão no app em instâncias que atendam 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 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
• Conhecimento básico de Java ou Kotlin

2. Etapas da configuração

(Opcional) Faça o download do exemplo de código

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

(Opcional) Importar o exemplo de código

Inicie o Android Studio e escolha Import project na tela de boas-vindas. Em seguida, abra a pasta baixada e selecione a pasta config. Em seguida, clique em "Abrir".

Criar um projeto do Android

1. No Android Studio, inicie um novo projeto.
2. Selecionar "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 para você.
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 conectá-lo ao app iOS. Acesse Noções básicas sobre projetos do Firebase para saber mais.

1. No console do Firebase, clique em Adicionar projeto e selecione ou insira um 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 como o Firebase usa o ID do projeto.

Observação:não é possível mudar o ID do projeto depois que o Firebase provisiona 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 o projeto e tenha uma experiência ideal 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, selecione para usar uma conta do Google Analytics ou criar uma nova. Se você optar por criar uma nova conta, selecione seu local de relatórios do Analytics e aceite as configurações de compartilhamento de dados e os termos do Google Analytics relacionados 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 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 práticas recomendadas e considerações sobre como adicionar apps a um projeto do Firebase, 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 do 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 do Android.
4. (Opcional) Insira o apelido do app.
5. Deixe o campo SHA-1 em branco, já que ele não é necessário para este projeto.
6. Clique em Registrar app.

Adicionar o arquivo de configuração do Firebase

Em seguida, você vai receber uma solicitação para baixar 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 Gradle para envolvidos no 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) (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'

// Add the following line:

apply plugin: ‘com.google.gms.google-services' // Google Services plugin

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. Ative o Google Analytics no seu projeto.

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

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 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 "dependencies", 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'
}

Sincronize seu projeto com arquivos do Gradle

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

4. Revise 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 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â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. Consulte Limitação para mais informações.

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

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

É possível definir os valores de parâmetro padrão no app usando o 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 caso nenhum tenha sido definido no back-end.

Você pode definir um conjunto de nomes e valores padrão de parâmetro usando um objeto Map ou um arquivo de recursos XML armazenado na pasta res/xml do app. O app de exemplo do guia de início rápido da Configuração remota usa um arquivo XML para definir nomes e valores de parâmetros padrão. Veja como criar um 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), conforme mostrado:

MainActivity.java

mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

3. Receber valores de parâmetros 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 estarão disponíveis para seu app. Caso contrário, você receberá os valores 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 os valores de parâmetro buscados ao app, chame o método activate(). Se quiser buscar e ativar valores em uma chamada, use uma solicitação fetchAndActivate() para buscar valores do back-end da 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();
            }
        });

Como esses valores de parâmetro atualizados afetam o comportamento e a aparência do app, ative-os quando isso não prejudicar a experiência do usuário. Por exemplo, na próxima vez em que ele abrir o app. Consulte Estratégias de carregamento da Configuração remota para mais informações e exemplos.

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.

Limitação

Se um app fizer muitas buscas em um curto período, as chamadas de busca serão limitadas, e o SDK vai 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. Para possibilitar 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 app em execução na produção. Se você estiver apenas testando o app 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.

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 outra coisa.

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 "Abrir" na versão Java ou Kotlin.

3. Revise 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. Com o console do Firebase ou as APIs de back-end da Configuração remota, é 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 desejadas. Nesta seção, descrevemos as etapas do console do Firebase para criar esses valores.

1. Abra o console do Firebase e seu projeto.
2. Selecione Configuração remota no menu lateral da seção "Engajamento" para acessar o painel do recurso.
3. Em Adicionar um parâmetro, insira o Parameter key.. Em Default value, adicione o texto que 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. 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. Mostrada ao buscar valores da Configuração remota.
welcome_message_caps	falso	Booleano. Se for "true", muda welcome_message para maiúsculas.
welcome_message	Este é 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 boas-vindas precisa ser atualizada com base nos parâmetros e valores da Configuração remota.

6. Parabéns

Parabéns! Você usou 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. Confira outros recursos abaixo:

• Começar a usar a Configuração remota do Firebase
• O que posso fazer com a Configuração remota?
• API de Configuração remota do Firebase
• Criar experimentos da Configuração remota do Firebase com o Teste A/B