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

É possível configurar modelos para casos de uso de cliente e servidor. Modelos de clientes são disponibilizados a todas as instâncias de apps que implementam as SDKs de de clientes do Firebase para a Configuração remota, incluindo Android, Apple, Web, Unity, Flutter e apps C++. Os parâmetros e valores da Configuração remota dos modelos específicos de servidor são disponibilizados para implementações da Configuração remota (incluindo o Cloud Run e o Cloud Functions) que usam o papel Administrador do Firebase SDK do Node.js v12.1.0 ou mais recente.

Importante: este guia discute parâmetros e condições específicos do cliente. Para mais informações sobre segmentação condicional para casos de uso de servidor, consulte Usar a Configuração remota em ambientes de servidor.

Ao usar o Console do Firebase ou as APIs de back-end da 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 substituir valores padrão no app definindo valores de parâmetros. 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.

Importante: não armazene dados confidenciais em chaves ou valores de parâmetros da Configuração remota. Os dados da Configuração remota são criptografados em trânsito, mas os usuários finais podem acessar qualquer parâmetro padrão ou buscado desse recurso que esteja disponível para a instância do app cliente.

Com o Console do Firebase, o SDK Admin ou a API REST da 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 da Configuração remota. A versão anterior é armazenada, o que permite fazer uma recuperação ou reversão conforme necessário. Essas operações estão disponíveis no Console do Firebase, no SDK Admin do Firebase e na API REST. Elas são descritas em mais detalhes em Gerenciar versões de modelos da Configuração remota.

Este guia explica parâmetros, condições, regras, valores condicionais e como os diversos valores de parâmetros são priorizados no servidor da 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 app pode exibir imagens diferentes com base no tipo de SO usando a regra simples if device_os = Android:

Como opção, uma condição de tempo pode ser usada para controlar quando seu app 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. Na guia Parâmetros do Console do Firebase, é possível ver a porcentagem de busca de valores condicionais para cada parâmetro. Essa métrica indica a porcentagem de solicitações nas últimas 24 horas que receberam cada valor.

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 da Configuração remota e qual valor é usado em determinada instância de app em um dado momento:

Os valores de parâmetros 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 interface 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.

   Observação: quando um parâmetro da Configuração remota estiver sendo usado em um experimento ativo do Teste A/B do Firebase, os valores do experimento terão precedência sobre qualquer valor condicional da Configuração remota.

2. Se não houver valores condicionais com condições que sejam avaliadas como true, o valor padrão do Configuração remota 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 definido como Usar no app padrão, nenhum valor será fornecido para esse parâmetro quando um app for buscado.

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 da Configuração remota não tiverem sido ativados, o app vai usar o valor padrão dentro dele.

   Saiba mais sobre como receber e definir valores padrão em Fazer o download dos padrões do modelo da Configuração remota.

3. Se nenhum valor padrão no app tiver sido definido, o app vai usar um valor de tipo estático (como 0 para int e false para boolean).

Veja neste gráfico como os valores de parâmetros são priorizados no back-end da Configuração remota e no seu app:

Tipos de dados de valores de parâmetros

A Configuração remota permite que você selecione um tipo de dados para cada parâmetro e valida todos os valores da Configuração remota em relação a esse tipo antes de uma atualização de modelo. O tipo de dados é armazenado e retornado em uma solicitação getRemoteConfig.

Os tipos compatíveis no momento são os seguintes:

• String
• Boolean
• Number
• JSON

Na interface do Console do Firebase, o tipo de dados pode ser selecionado em uma lista suspensa ao lado da chave de parâmetro. Nos tipos da API REST, é possível definir usando o campo value_type no objeto de parâmetro.

Observação: a seleção de um tipo de dados não afeta como os valores são retornados para os SDKs do cliente. No entanto, verifique se o método get está transmitindo o valor para o tipo de dados pretendido no app.

Grupos de parâmetros

É possível agrupar parâmetros com a Configuração remota, permitindo uma maior organização da interface 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. A Configuração remota 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.

Observação: os grupos de parâmetros ajudam a organizar o Console do Firebase e a API REST da Configuração remota. No entanto, eles não alteram como os parâmetros são referenciados no SDK do cliente.

É possível criar grupos de parâmetros usando o Console do Firebase ou a API REST da Configuração remota. Cada grupo de parâmetros criado tem um nome exclusivo no modelo da 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 da Configuração remota possibilita a criação e a publicação de grupos de parâmetros de maneira automatizada. 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 da Configuração remota, conforme detalhado na página referência de expressão condicional.

Tipo de regra	Operadores	Valores	Observação
App	==	Selecione em uma lista de IDs de apps associados ao seu projeto do Firebase.	Ao adicionar um app ao Firebase, insira um ID do pacote ou um nome de pacote do Android que define um atributo exposto como ID do app nas regras da Configuração remota. Use o atributo desta maneira: Para plataformas da Apple: use o CFBundleIdentifier do app. Localize o identificador do pacote na guia Geral para o destino principal do aplicativo no Xcode. Para Android: use o applicationId do app. 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: =, ≠, >, ≥, <, ≤	Especifique as versões do seu app a serem segmentadas. Antes de usar essa regra, utilize uma regra de ID do app para selecionar um app Android/Apple associado ao seu projeto do Firebase.	Para plataformas da Apple: use o CFBundleShortVersionString do app. Observação: verifique se o app Apple está usando a versão 6.24.0 ou uma mais recente do SDK para Firebase das plataformas da Apple, já que CFBundleShortVersionString não é enviado em versões anteriores. Saiba mais em Notas de lançamento. Para Android: use o versionName do app. As comparações de strings para essa regra diferenciam maiúsculas de minúsculas. Ao usar o operador correspondência exata, 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 à toda a string de versão de destino ou parte dela. 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: =, ≠, >, ≥, <, ≤	Especifique os build(s) do app a serem segmentados. Antes de usar essa regra, utilize uma regra de ID do app para selecionar um app Apple ou Android associado ao seu projeto do Firebase.	Esse operador está disponível apenas para apps Apple e Android. Ele corresponde ao CFBundleVersion para Apple e ao versionCode para Android. 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.
Plataforma	==	iOS Android Web
Sistema operacional	==	Especifique os sistemas operacionais a serem segmentados. Antes de usar essa regra, utilize uma regra de ID do app para selecionar um app da Web associado ao seu projeto do Firebase.	Essa regra mudará para true em relação a uma determinada instância de app da Web se o sistema operacional e a versão dele corresponderem a um valor de destino na lista especificada.
Navegador	==	Especifique os navegadores a serem segmentados. Antes de usar essa regra, utilize uma regra de ID do app para selecionar um app da Web associado ao seu projeto do Firebase.	Essa regra vai mudar para true em relação a uma determinada instância de app da Web se o navegador e a versão dele corresponderem a um valor de destino na lista especificada.
Categoria do dispositivo	é, não é	dispositivo móvel	Essa regra avalia se o dispositivo que acessa seu app da Web é um dispositivo móvel ou não (computador ou console). Esse tipo de regra só está disponível para apps da Web.
Idiomas	está em	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.
País/região	está em	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 o código do país determinado pelo Firebase Analytics (se os dados do Analytics forem compartilhados com o Firebase).
Público(s)-alvo	Inclui pelo menos um	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.
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, a 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: Definir propriedades de usuários na Apple Definir propriedades do usuários no Android 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 da Configuração remota.
Usuário na porcentagem aleatória	Controle deslizante (no Console do Firebase. A API REST usa os operadores <=, > e between).	0 a 100	Use esse campo para aplicar uma alteração em uma amostra aleatória de instâncias de apps (com tamanhos de amostra de 0,0001%), usando o widget de controle deslizante para segmentar usuários de forma aleatória (instâncias de apps) em grupos. Cada instância de apps é associada de maneira permanente a um número aleatório inteiro ou fracionário, de acordo com uma semente definida nesse projeto. Os valores de semente podem ter entre um e 32 caracteres, contendo valores alfanuméricos, pontos, hífens e/ou sublinhados. A regra vai usar a chave padrão (mostrada como Editar semente no Console do Firebase), a menos que você modifique o valor de semente. Desmarque o campo Semente para fazer com que uma regra volte a usar a chave padrão. Para abordar consistentemente as mesmas instâncias de apps em determinados intervalos de porcentagem, use o mesmo valor de semente em todas as condições. Também é possível selecionar um novo grupo de instâncias de apps atribuído aleatoriamente para um determinado intervalo de porcentagem especificando uma nova semente. 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, configure uma condição para corresponder a uma porcentagem entre 0% e 5% e outra para um intervalo de 5% a 10%. Para permitir que alguns usuários apareçam de forma aleatória nos dois grupos, use valores de semente diferentes para as regras em cada condição.
Segmento importado	está em	Selecione um ou mais segmentos importados.	Essa regra requer a configuração de segmentos importados personalizados.
Data/hora	Antes, Depois	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.
Primeiro acesso	Antes, Depois	Uma data e hora especificadas no fuso horário definido.	Corresponde a usuários que abriram o app segmentado pela primeira vez no período especificado. Requer os seguintes SDKs: SDK do Firebase para Google Analytics SDK das plataformas da Apple v9.0.0+ ou SDK do Android v21.1.1+ (BoM do Firebase v30.3.0+)
ID de instalação	está em	Especifique um ou mais IDs de instalação (até 50) para segmentar.	Essa regra será avaliada como true para uma determinada instalação se o ID dela estiver na lista de valores separados por vírgulas. Para saber como conseguir os IDs de instalação, consulte Recuperar identificadores de cliente.
Usuários	(sem operadores)	Segmenta todos os usuários de todos os apps no projeto atual.	Use essa regra de condição para todos os usuários no projeto, independentemente do aplicativo ou da plataforma. Ao usar a personalização da Configuração remota, use esse operador para garantir que todos os usuários no projeto recebam valores personalizados.

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 da 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 dos valores de parâmetro não pode exceder 1.000.000 caracteres.

Como visualizar as alterações de parâmetros e condições

É possível ver as alterações mais recentes nos seus modelos da Configuração remota do Console do Firebase. Para cada parâmetro e condição individual, é possível:

• Ver o nome do usuário que modificou o parâmetro ou a condição pela última vez.

• Se a mudança ocorreu no mesmo dia, veja o número de minutos ou horas decorridos desde que ela foi publicada no modelo ativo da Configuração remota.

• Se a mudança ocorreu há um ou mais dias, veja a data em que ela foi publicada no modelo ativo da Configuração remota.

Atualizações de parâmetros

Na página Parâmetros da Configuração remota, a coluna Última publicação mostra o último usuário que modificou cada parâmetro e a data da última publicação da mudança:

• Para ver os metadados de mudança dos parâmetros agrupados, expanda o grupo de parâmetros.

• Para classificar em ordem crescente ou decrescente por data de publicação, clique no rótulo da coluna Última publicação.

Atualizações de condição

Na página Condições da Configuração remota, é possível ver o último usuário que modificou a condição e a data da modificação ao lado de Última modificação, abaixo de cada condição.

Próximas etapas

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