Os modelos da Configuração remota são conjuntos de parâmetros e condições no formato JSON que você criou para seu projeto do Firebase. Você pode criar modelos de cliente, de onde seu app busca valores, e de servidor, de onde os clientes do servidor podem buscar valores.
Esta seção discute os modelos de cliente. Para saber mais sobre modelos específicos de servidor, clique em Modelos de servidor.É possível modificar e gerenciar o modelo usando o Console do Firebase, que exibe o conteúdo do modelo em formato de gráfico nas guias Guias Parâmetros e Condições.
Também é possível usar a API REST da Configuração remota e o SDK Admin ou a CLI do Firebase para modificar e gerenciar seu modelo de cliente.
Confira um exemplo de arquivo de modelo de cliente:
{
"conditions": [
{
"name": "ios",
"expression": "device.os == 'ios'"
}
],
"parameters": {
"welcome_message": {
"defaultValue": {
"value": "Welcome to this sample app"
},
"conditionalValues": {
"ios": {
"value": "Welcome to this sample iOS app"
}
}
},
"welcome_message_caps": {
"defaultValue": {
"value": "false"
}
},
"header_text": {
"defaultValue": {
"useInAppDefault": true
}
}
},
"version": {
"versionNumber": "28",
"updateTime": "2020-05-14T18:39:38.994Z",
"updateUser": {
"email": "user@google.com"
},
"updateOrigin": "CONSOLE",
"updateType": "INCREMENTAL_UPDATE"
}
}
É possível realizar estas tarefas de gerenciamento de versões com o console do Firebase:
- Listar todas as versões de modelos armazenadas.
- Recuperar uma versão específica.
- Reverter para uma versão específica de cliente
- Exclua os modelos da Configuração remota na página Histórico de alterações
Também é possível listar, recuperar e reverter modelos usando as APIs de back-end da CLI do Firebase e da Configuração remota.
Há um limite total de 300 versões armazenadas com ciclo de vida por tipo de modelo (300 modelos de cliente e 300 de servidor), o que inclui números de versão armazenados para modelos excluídos. Se você publicar mais de 300 por tipo de modelo durante a vida útil de um projeto, as versões mais antigas são excluídas, mantendo no máximo 300 versões desse tipo.
Sempre que os parâmetros são atualizados, o Configuração remota cria um novo modelo com controle de versão e armazena o anterior como uma versão que você pode recuperar ou reverter conforme necessário. Os números de versão
são aumentados sequencialmente partindo do valor inicial armazenado pelo Configuração remota.
Todos os modelos incluem um campo version
conforme mostrado. Ele contém metadados sobre essa
versão específica.
É possível excluir os modelos da Configuração remota conforme necessário na página Histórico de alterações do console da Configuração remota.
Gerenciar versões do modelo da Configuração remota
Veja nesta seção como gerenciar versões do modelo da Configuração remota.
Para mais informações sobre como criar, modificar e salvar modelos programaticamente, consulte Modificar a Configuração remota de maneira programática.
Listar todas as versões armazenadas do modelo da Configuração remota
É possível recuperar uma lista de todas as versões armazenadas de modelos do Configuração remota. As etapas para fazer isso:
Console do Firebase
Na guia Parâmetros, selecione o ícone de relógio exibido no canto superior direito. Isso abrirá a página Histórico de alterações com a lista de todas as versões de modelos armazenadas em um menu em lista à direita.
Os detalhes exibidos para cada versão armazenada informam se a alteração foi feita por meio do Console, da API REST ou de uma reversão ou se foram alterações incrementais devido a um salvamento forçado do modelo.
CLI do Firebase
firebase remoteconfig:versions:list
Use a opção --limit
para limitar o número de versões retornadas.
Envie "0" para buscar todas as versões.
Node.js
function listAllVersions() {
admin.remoteConfig().listVersions()
.then((listVersionsResult) => {
console.log("Successfully fetched the list of versions");
listVersionsResult.versions.forEach((version) => {
console.log('version', JSON.stringify(version));
});
})
.catch((error) => {
console.log(error);
});
}
Java
ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get(); while (page != null) { for (Version version : page.getValues()) { System.out.println("Version: " + version.getVersionNumber()); } page = page.getNextPage(); } // Iterate through all versions. This will still retrieve versions in batches. page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get(); for (Version version : page.iterateAll()) { System.out.println("Version: " + version.getVersionNumber()); }
REST
curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:listVersions
A lista de modelos inclui metadados para todas as versões armazenadas, incluindo as hora da atualização, o usuário que a fez e como ela foi feita. Veja um exemplo de um elemento da versão:
```json
{
"versions": [{
"version_number": "6",
"update_time": "2022-05-12T02:38:54Z",
"update_user": {
"name": "Jane Smith",
"email": "jane@developer.org",
"imageUrl": "https://lh3.googleusercontent.com/a-/..."
},
"description": "One small change on the console",
"origin": "CONSOLE",
"update_type": "INCREMENTAL_UPDATE"
}]
}
```
Recuperar uma versão específica do modelo do Configuração remota
É possível recuperar qualquer versão armazenada específica do modelo do Configuração remota. Para recuperar uma versão de modelo armazenada:
Console do Firebase
Por padrão, o painel de detalhes na guia Histórico de alterações exibe o modelo ativo atual. Para ver detalhes de outra versão na lista, selecione-a no menu à direita.
Para visualizar uma comparação detalhada entre a versão selecionada e qualquer outra versão armazenada, passe o cursor sobre o menu de contexto de qualquer versão não selecionada e clique em Comparar com a versão selecionada.
CLI do Firebase
firebase remoteconfig:get -v VERSION_NUMBER
Como alternativa, é possível gravar a saída em um arquivo especificado com -o, FILENAME
.
Node.js
Envie getTemplate()
sem argumentos para recuperar a versão mais recente do modelo.
Para recuperar uma versão específica, use getTemplateAtVersion()
.
// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
.then((template) => {
console.log("Successfully fetched the template with ETag: " + template.etag);
})
.catch((error) => {
console.log(error);
});
Java
Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get(); // See the ETag of the fetched template. System.out.println("Successfully fetched the template with ETag: " + template.getETag());
REST
curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig?version_number=6
O parâmetro de URL ?version_number
é válido apenas para operações GET
.
Não é possível utilizá-lo para especificar números de versão para atualizações. Uma solicitação GET
semelhante sem o parâmetro ?version_number
recuperaria o modelo ativo atual.
Reverter para uma versão específica armazenada do modelo do Configuração remota
É possível reverter para qualquer versão armazenada do modelo. Para reverter um modelo:
Console do Firebase
Para as versões de modelo anteriores qualificadas para reversão, um botão com a opção de reverter para essa versão é exibido no canto superior direito da página Histórico de alterações. Clique e confirme essa opção apenas se tiver certeza de que você quer reverter para essa versão e usar esses valores imediatamente para todos os apps e usuários.
CLI do Firebase
firebase remoteconfig:rollback -v VERSION_NUMBER
Node.js
// Roll back to template version: 6
admin.remoteConfig().rollback('6')
.then((template) => {
console.log("Successfully rolled back to template version 6.");
console.log("New ETag: " + template.etag);
})
.catch((error) => {
console.log('Error trying to rollback:', e);
})
Java
try { Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get(); System.out.println("Successfully rolled back to template version: " + versionNumber); System.out.println("New ETag: " + template.getETag()); } catch (ExecutionException e) { if (e.getCause() instanceof FirebaseRemoteConfigException) { FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause(); System.out.println("Error trying to rollback template."); System.out.println(rcError.getMessage()); } }
REST
Se você quiser reverter para um modelo armazenado do Configuração remota, emita uma solicitação HTTP POST com
o método personalizado :rollback
e, no corpo da solicitação, a versão específica
a ser aplicada. Exemplo:
curl --compressed -D headers -H "Authorization: Bearer <var>token</var>" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/remoteConfig:rollback -d '{"version_number": 6}'
A resposta apresenta o conteúdo do modelo armazenado que está ativo atualmente com os novos metadados de versão.
Na realidade, essa operação de reversão cria uma nova versão numerada. Por exemplo, a reversão da versão 10 para a versão 6 cria uma nova cópia da versão 6, que é diferente da original apenas porque o número de versão é 11. A versão 6 original ainda é armazenada, caso não tenha atingido a expiração, e a versão 11 se torna o modelo ativo.
Excluir um modelo da Configuração remota
Você pode excluir modelos da Configuração remota no console do Firebase. Para excluir um modelo da Configuração remota:
1. Na página Parâmetros da Configuração remota, clique em Histórico de alterações.Alterne para o modelo que você quer excluir, clique em
Mais e selecione Excluir.Clique em Excuir para confirmar a exclusão.
Fazer o download e publicar modelos da Configuração remota
Faça o download e publique modelos da Configuração remota para integrá-los aos seus sistemas de compilação e controle de origem, automatizar atualizações de configurações e manter os parâmetros e valores sincronizados em vários projetos.
É possível fazer o download do modelo da Configuração remota ativo no momento, de maneira programática ou É possível atualizar o arquivo JSON exportado e publicá-lo no mesmo projeto ou em um projeto novo ou existente.
Digamos que você tenha vários projetos que representem estágios diferentes do ciclo de vida de desenvolvimento de software, como ambientes de desenvolvimento, teste, preparo e produção. Nesse caso, é possível promover um modelo totalmente testado do seu ambiente de preparo para seu ambiente de produção, fazendo o download dele no projeto de preparo e a publicação no projeto de produção.
Também é possível usar esse método para migrar configurações de um projeto para outro ou preencher automaticamente um novo projeto com parâmetros e valores de um projeto estabelecido.
Os parâmetros e os valores de parâmetro criados especificamente como variantes em um experimento do Teste A/B não estão incluídos nos modelos exportados.
Para exportar e importar modelos da Configuração remota:
- Faça o download do modelo atual da Configuração remota.
- Valide o modelo da Configuração remota.
- Publique o modelo da Configuração remota.
Faça o download do modelo atual da Configuração remota
Use o seguinte para fazer o download do modelo ativo da Configuração remota no formato JSON:
Console do Firebase
- Na guia Parâmetros ou condições da Configuração remota, abra o Menu e selecione Fazer o download do arquivo de configuração atual.
- Quando solicitado, clique em Fazer o download do arquivo de configuração, escolha o local onde você quer salvar o arquivo e clique em Salvar.
CLI do Firebase
firebase remoteconfig:get -o filename
Node.js
function getTemplate() { var config = admin.remoteConfig(); config.getTemplate() .then(function (template) { console.log('ETag from server: ' + template.etag); var templateStr = JSON.stringify(template); fs.writeFileSync('config.json', templateStr); }) .catch(function (err) { console.error('Unable to get template'); console.error(err); }); }
Java
Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get(); // See the ETag of the fetched template. System.out.println("ETag from server: " + template.getETag());
REST
curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename
Este comando exporta o payload do JSON para um arquivo e os cabeçalhos
(incluindo a ETag) para um arquivo headers
separado.
Validar o modelo da Configuração remota
É possível validar as atualizações do seu modelo antes da publicação usando o SDK Admin do Firebase ou a API REST. Os modelos também são validados quando você tenta publicar na CLI do Firebase ou no Console do Firebase.O processo de validação do modelo verifica se há erros, como chaves duplicadas de
parâmetros e condições, nomes de condições inválidas e condições não existentes ou
ETags incorretas. Por exemplo, uma solicitação que contém mais do que o número
permitido de chaves (2.000) retornaria a mensagem de erro Param count too
large
.
Node.js
function validateTemplate(template) { admin.remoteConfig().validateTemplate(template) .then(function (validatedTemplate) { // The template is valid and safe to use. console.log('Template was valid and safe to use'); }) .catch(function (err) { console.error('Template is invalid and cannot be published'); console.error(err); }); }
Java
try { Template validatedTemplate = FirebaseRemoteConfig.getInstance() .validateTemplateAsync(template).get(); System.out.println("Template was valid and safe to use"); } catch (ExecutionException e) { if (e.getCause() instanceof FirebaseRemoteConfigException) { FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause(); System.out.println("Template is invalid and cannot be published"); System.out.println(rcError.getMessage()); } }
REST
Para validar as atualizações do modelo, inclua o parâmetro de URL ?validate_only=true
à sua solicitação de publicação:
curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig?validate_only=true -d @filename
Se o modelo tiver sido validado, o comando "curl" vai retornar o
modelo JSON enviado e, no arquivo headers
salvo, você encontra
o status 200 do HTTP/2 e uma ETag atualizada com o sufixo -0
. Se o
modelo não foi validado, você vai receber o erro de validação na
resposta JSON e o arquivo headers
vai apresentar uma resposta que não é 200
(e nenhuma ETag).
Publicar o modelo da Configuração remota
Depois de fazer o download de um modelo, fazer as alterações necessárias no conteúdo JSON e validá-lo, é possível publicar o modelo em um projeto.
A publicação substitui todo o modelo da configuração atual pelo arquivo atualizado e incrementa a versão do modelo em um. Como toda a configuração é substituída, se você excluir um parâmetro do arquivo JSON e publicá-lo, o parâmetro é deletado do servidor e fica indisponível para os clientes.
Após a publicação, as alterações nos parâmetros e valores são disponibilizadas imediatamente para os apps e usuários. Se necessário, reverta para a versão anterior.
Use os seguintes comandos para publicar o modelo:
Console do Firebase
- Na guia Parâmetros ou condições da Configuração remota, abra o Menu e selecione Publicar de um arquivo.
- Quando solicitado, clique em Procurar, navegue até o arquivo da Configuração remota que você quer publicar e clique em Selecionar.
- O arquivo vai ser validado e, se for bem-sucedido, você pode clicar em Publicar para disponibilizar a configuração imediatamente para seus apps e usuários.
Node.js
function publishTemplate() { var config = admin.remoteConfig(); var template = config.createTemplateFromJSON( fs.readFileSync('config.json', 'UTF8')); config.publishTemplate(template) .then(function (updatedTemplate) { console.log('Template has been published'); console.log('ETag from server: ' + updatedTemplate.etag); }) .catch(function (err) { console.error('Unable to publish template.'); console.error(err); }); }
Java
try { Template publishedTemplate = FirebaseRemoteConfig.getInstance() .publishTemplateAsync(template).get(); System.out.println("Template has been published"); // See the ETag of the published template. System.out.println("ETag from server: " + publishedTemplate.getETag()); } catch (ExecutionException e) { if (e.getCause() instanceof FirebaseRemoteConfigException) { FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause(); System.out.println("Unable to publish template."); System.out.println(rcError.getMessage()); } }
REST
curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename
Para este comando curl
, especifique o conteúdo usando o caractere
"@" seguido pelo nome do arquivo.
As personalizações e condições da Configuração remota estão incluídas nos modelos salvos. Por isso, é importante estar ciente das seguintes limitações ao tentar publicar em um projeto diferente:
As personalizações não podem ser importadas de um projeto para outro.
Por exemplo, se as personalizações estiverem ativadas no seu projeto e você fizer o download e editar um modelo, é possível publicá-lo no mesmo projeto, mas não em outro, a menos que você exclua as personalizações.
As condições podem ser importadas de projeto para projeto. No entanto, é necessário que todos os valores condicionais específicos (como IDs do app ou públicos-alvo) apareçam no projeto de destino antes da publicação.
Por exemplo, se você tiver um parâmetro da Configuração remota usando uma condição que especifique um valor de
iOS
para a plataforma, o modelo pode ser publicado em outro projeto, porque os valores da plataforma são iguais para qualquer projeto. No entanto, se houver uma condição que depende de um ID do app ou público de usuário específico que não existe no projeto de destino, a validação vai apresentar falhas.Se o modelo que você planeja publicar contém condições que dependem do Google Analytics, ele precisa estar ativo no projeto de destino.
Fazer o download dos padrões do modelo da Configuração remota
Como o app nem sempre está conectado à Internet, é necessário configurar os valores padrão do app no lado do cliente para todos os parâmetros da Configuração remota. Além disso, você precisa sincronizar periodicamente os valores padrão do cliente do app e os valores de parâmetros padrão do back-end da Configuração remota, porque podem mudar ao longo do tempo.
Conforme descrito nos links específicos da plataforma no final desta seção, é possível definir esses padrões manualmente no app ou simplificar o processo fazendo o download de arquivos que contenham apenas os pares de chave-valor de todos os parâmetros e os respectivos valores padrão no modelo ativo da Configuração remota. Em seguida, inclua esse arquivo no projeto e configure o app para importar esses valores.
É possível fazer o download desses arquivos em formato XML para apps do Android, no formato de lista de propriedades (plist) para apps iOS e em JSON para apps da Web.
Recomendamos fazer o download periódico dos padrões da Configuração remota antes de lançar uma nova versão para garantir que o app e o back-end desse recurso permaneçam sincronizados.
Para fazer o download de um arquivo com padrões de modelo:
REST
curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'
Use XML
, PLIST
ou JSON
como o valor format
, dependendo do formato de arquivo
que você quer transferir por download.
Console do Firebase
- Na guia Parâmetros, abra o Menu e selecione Fazer o download dos valores padrão.
- Se aparecer uma solicitação, clique no botão de rádio correspondente ao formato do arquivo que você quer transferir e clique em Fazer download do arquivo.
Saiba mais sobre como importar valores padrão da Configuração remota para seu app em: