Parâmetros e condições do Configuração remota

Ao usar o Console do Firebase ou as APIs de back-end do Configuração remota, você define um ou mais parâmetros (pares de chave-valor) e informa valores padrão dentro do app para esses parâmetros. É possível modificar os valores padrão dentro do app definindo valores de parâmetros do lado do servidor. As chaves e os valores de parâmetros são strings, mas esses valores podem ser transmitidos como outros tipos de dados quando você usa esses valores no seu app.

Usando o Console do Firebase ou a API REST do Configuração remota, é possível criar novos valores padrão para os parâmetros, além de valores condicionais usados para segmentar grupos de instâncias de apps. Cada vez que você atualiza sua configuração no Console do Firebase, a plataforma cria e publica uma nova versão do seu modelo do Configuração remota. A versão anterior é armazenada, o que permite fazer uma recuperação ou um rollback conforme necessário. Essas operações também estão disponíveis por meio da API REST.

Este guia explica parâmetros, condições, regras, valores condicionais e como os diversos valores de parâmetros são priorizados no servidor do Configuração remota e no seu app. Ele também contém detalhes dos tipos de regras usados para criar condições.

Condições, regras e valores condicionais

Uma condição é usada para segmentar um grupo de instâncias de aplicativos. As condições são constituídas por uma ou mais regras que precisam ser avaliadas como true para que a condição seja avaliada como true em uma determinada instância do aplicativo. Se o valor de uma regra for indefinido (por exemplo, quando não houver valor disponível), essa regra será avaliada como false.

Por exemplo, um parâmetro que define a página inicial de um aplicativo pode exibir imagens diferentes com base no tipo de sistema operacional usando a regra simples if device_os = Android:

Como opção, uma condição de tempo pode ser usada para controlar quando seu aplicativo exibe itens promocionais especiais.

Um parâmetro pode ter diversos valores condicionais que usam condições diferentes. Os parâmetros podem compartilhar condições em um projeto.

Prioridade dos valores de parâmetros

Um parâmetro pode ter diversos valores condicionais associados. As regras a seguir determinam qual valor é recuperado do servidor do Configuração remota e qual valor é usado em determinada instância de app em um dado momento:

Os valores de parâmetros do servidor são buscados de acordo com a seguinte lista de prioridades:

  1. Primeiro, os valores condicionais são aplicados, se houver condições que sejam avaliadas como true para determinada instância de app. Se várias condições forem avaliadas como true, a primeira (superior) mostrada na IU do Console do Firebase terá precedência e os valores condicionais associados a essa condição serão fornecidos quando um app recuperar valores do back-end. É possível alterar a prioridade das condições ao arrastar e soltá-las na guia Condições.

  2. Se não houver valores condicionais com condições que sejam avaliadas como true, o valor padrão do servidor será fornecido quando um app buscar valores do back-end. Se um parâmetro não existir no back-end ou se o valor padrão for Sem valor, nenhum valor será fornecido para esse parâmetro quando um app buscar valores.

No seu app, os valores dos parâmetros são retornados por métodos get de acordo com a seguinte lista de prioridades:

  1. Se um valor tiver sido buscado no back-end e ativado, o app usará o valor recuperado. Os valores dos parâmetros ativados são permanentes.
  2. Se nenhum valor tiver sido buscado no back-end, ou se os valores buscados no back-end do Configuração remota não tiverem sido ativados, o app usará o valor padrão dentro dele.
  3. Se nenhum valor padrão no app tiver sido definido, o app usará um valor de tipo estático (como 0 para int e false para boolean).

Este gráfico resume como os valores de parâmetros são priorizados no back-end do Configuração remota e no seu aplicativo:

Grupos de parâmetros

O Configuração remota permite agrupar parâmetros, permitindo uma maior organização da IU e do modelo mental.

Por exemplo, digamos que você precise ativar ou desativar três tipos de autenticação diferentes ao lançar um novo recurso de login. O Configuração permite criar os três parâmetros para ativar os tipos como quiser e organizá-los em um grupo chamado "Novo login", sem necessidade de adicionar prefixos ou classificação especial.

É possível criar grupos de parâmetros usando o Console do Firebase ou a API REST do Configuração remota. Cada grupo de parâmetros criado tem um nome exclusivo no modelo do Configuração remota. Ao criar grupos de parâmetros, lembre-se:

  • Os parâmetros podem ser incluídos em apenas um grupo por vez, e uma chave de parâmetro ainda precisa ser exclusiva em todos os parâmetros.
  • Os nomes dos grupos de parâmetros são limitados a 256 caracteres.
  • Se você usa a API REST e o Console do Firebase, verifique se qualquer lógica da API REST está atualizada para lidar com grupos de parâmetros na publicação.

Criar ou modificar grupos de parâmetros usando o Console do Firebase

É possível agrupar parâmetros na guia Parâmetros do Console do Firebase. Para criar ou modificar um grupo:

  1. Selecione Gerenciar grupos.
  2. Marque as caixas de seleção dos parâmetros que você quer adicionar e selecione Mover para o grupo.
  3. Para selecionar um grupo atual ou criar um novo grupo, digite um nome e uma descrição e selecione Criar novo grupo. Depois de salvar um grupo, ele estará disponível para ser publicado usando o botão Publicar alterações.

Criar grupos de maneira programática

A API REST do Configuração remota fornece uma maneira automatizada de criar e publicar grupos de parâmetros. Supondo que você esteja familiarizado com o REST e pronto para autorizar solicitações à API, execute estas etapas para gerenciar grupos de maneira programática:

  1. Recuperar o modelo atual
  2. Adicionar objetos JSON para representar seus grupos de parâmetros
  3. Publicar os grupos de parâmetros usando uma solicitação HTTP PUT.

O objeto parameterGroups contém chaves de grupo, com uma descrição aninhada e uma lista de parâmetros agrupados. Cada chave de grupo precisa ser globalmente exclusiva.

Por exemplo, veja um trecho de uma revisão de modelo que adiciona o grupo de parâmetros "novo menu" com um parâmetro, pumpkin_spice_season:

{
  "parameters": {},
  "version": {
    "versionNumber": "1",

    …

  },
  "parameterGroups": {
    "new menu": {
      "description": "New Menu",
      "parameters": {
        "pumpkin_spice_season": {
          "defaultValue": {
            "value": "true"
          },
          "description": "Whether it's currently pumpkin spice season."
        }
      }
    }
  }
}

Tipos de regra de condição

Os seguintes tipos de regras são compatíveis com o Console do Firebase. Um recurso equivalente está disponível na API REST do Configuração remota, conforme detalhado na página Referência de expressão condicional.

Tipo de regra OperadoresValoresObservação
App == Selecione em uma lista de códigos de apps associados ao seu projeto do Firebase. Ao adicionar um app ao Firebase, você insere um ID do pacote de iOS ou um nome de pacote do Android que define um atributo exposto como código do app nas regras do Configuração remota.

Use o atributo desta maneira:
  • Para iOS: use o CFBundleIdentifier do aplicativo. Localize o identificador do pacote na guia Geral para o destino principal do aplicativo no Xcode.
  • Para Android: use o applicationId do aplicativo. Localize applicationId no seu arquivo build.gradle no nível do aplicativo.
Versão do app Para valores de string:
corresponde exatamente,
contém,
não contém,
expressão regular

Para valores numéricos:
=, ≠, >, ≥, <, ≤
Insira um valor para especificar determinada versão ou versões relacionadas do seu app. Antes de usar essa regra, você precisa usar uma regra de ID do app para selecionar um app para Android associado ao seu projeto do Firebase. Este operador está disponível apenas em apps para Android e corresponde ao nome da versão do app. As comparações de strings para essa regra diferenciam maiúsculas de minúsculas.

Ao usar o operador corresponde exatamente, contém, não contém ou expressão regular, é possível selecionar vários valores.

Ao utilizar o operador de expressão regular, é possível criar expressões regulares no formato RE2. A expressão regular precisa corresponder a toda ou parte da string de versão de destino. Use as âncoras ^ e $ para corresponder ao começo, ao final ou a toda uma string de destino.

Número do build Para valores de string:
corresponde exatamente,
contém,
não contém,
expressão regular

Para valores numéricos:
=, ≠, >, ≥, <, ≤
Insira um valor para especificar determinada verão ou versões relacionadas do seu app. Antes de usar essa regra, você precisa usar uma regra de ID do app para selecionar um app para iOS associado ao seu projeto do Firebase. Esse operador está disponível apenas em apps para iOS e corresponde à CFBundleVersion do app. As comparações de strings para essa regra diferenciam maiúsculas de minúsculas.

Ao usar o operador corresponde exatamente, contém, não contém ou expressão regular, é possível selecionar vários valores.

Ao utilizar o operador de expressão regular, é possível criar expressões regulares no formato RE2. A expressão regular precisa corresponder a toda ou parte da string de versão de destino. Use as âncoras ^ e $ para corresponder ao começo, ao final ou a toda uma string de destino.

Tipo de SO == iOS
Android
 
Data/hora <=, > Uma data e hora especificadas, no fuso horário do dispositivo ou em um fuso horário especificado, como "(GMT+11) horário de Sydney". Compara a hora atual com o tempo de busca do dispositivo.
Usuário na porcentagem aleatória. <=, > 0 a 100

Use este campo para aplicar uma alteração a uma amostra aleatória de instâncias de apps (com tamanhos de amostra de ,0001%), usando os operadores <= e > para segmentar os usuários (instâncias do app) em grupos.

Cada instância de app é associada de maneira permanente a um número aleatório inteiro ou fracionário, de acordo com uma chave definida nesse projeto. Uma regra usará a chave padrão (mostrada como DEF no Console do Firebase) a menos que você selecione ou crie outra chave. É possível fazer com que uma regra volte a usar a chave padrão ao desmarcar o campo Randomizar usuários utilizando esta chave. Você pode usar uma só chave entre regras para abordar consistentemente as mesmas instâncias de apps dentro de determinados intervalos de porcentagem. Ou você pode selecionar um novo grupo de instâncias de apps atribuído aleatoriamente para determinado intervalo de porcentagem criando uma nova chave.

Por exemplo, para criar duas condições relacionadas em que cada uma se aplica a 5% não sobrepostos dos usuários de um app, você pode ter uma condição que inclua uma regra <= 5% e outra que inclua uma regra > 5% e outra <=10%. Para permitir que alguns usuários apareçam aleatoriamente em ambos os grupos, use chaves diferentes para as regras em cada condição.

Usuário no público == Selecione um ou mais públicos-alvo em uma lista do Google Analytics configurada para o projeto.

Esta regra requer uma regra de código de app para selecionar um app associado ao seu projeto do Firebase.

Observação: como muitos públicos do Firebase Analytics são definidos por eventos ou propriedades de usuários que podem ter como base as ações de usuários do app, pode levar algum tempo para que uma regra Usuário no público tenha efeito em determinada instância do app.

Região/país do dispositivo == Selecione uma ou mais regiões ou países. Essa regra será avaliada como true para determinada instância de app se a instância estiver em uma das regiões ou países listados. O código do país do dispositivo é determinado por meio do endereço IP do dispositivo na solicitação ou do código do país determinado pelo Firebase Analytics (se os dados do Analytics forem compartilhados com o Firebase).
Idioma do dispositivo == Selecione um ou mais idiomas. Essa regra será avaliada como true para determinada instância de app se a instância estiver instalada em um dispositivo que usa um dos idiomas listados.
Propriedade do usuário Para valores de string:
contém,
não contém,
corresponde exatamente a,
expressão regular

Para valores numéricos:
=, ≠, >, ≥, <, ≤

Observação: no cliente, defina apenas valores de sequência para propriedades do usuário. Para condições que usam operadores numéricos, o Configuração remota converte o valor da propriedade de usuário correspondente em um inteiro/float.
Selecione em uma lista de propriedades de usuário no Google Analytics disponíveis. Para aprender a usar as propriedades do usuário para personalizar o app de acordo com segmentos muito específicos da sua base de usuários, consulte Configuração remota e propriedades do usuário.

Para saber mais sobre as propriedades do usuário, consulte os seguintes guias:

Ao usar o operador corresponde exatamente, contém, não contém ou expressão regular, é possível selecionar vários valores.

Ao utilizar o operador de expressão regular, é possível criar expressões regulares no formato RE2. A expressão regular precisa corresponder a toda ou parte da string de versão de destino. Use as âncoras ^ e $ para corresponder ao começo, ao final ou a toda uma string de destino.

Observação: as propriedades do usuário coletadas automaticamente não estão disponíveis durante a criação de condições do Configuração remota.

Como pesquisar parâmetros e condições

Pesquise as chaves dos parâmetros, os valores de parâmetros e as condições do projeto no Console do Firebase usando a caixa de pesquisa na parte superior da guia Parâmetros do Configuração remota.

Limites de parâmetros e condições

Dentro de um projeto do Firebase, você tem até 2.000 parâmetros e 500 condições. As chaves dos parâmetros podem ter até 256 caracteres e precisam começar com sublinhado ou uma letra (A-Z, a-z), além de incluir números. O tamanho total das strings desses valores não pode exceder 800.000 caracteres.

Próximas etapas

Para começar a configurar seu projeto do Firebase, consulte Configurar um projeto do Configuração remota do Firebase.