Modelos e controle de versão de configuração remota

O modelo do Configuração remota é o conjunto de parâmetros e condições formatados em JSON do lado do servidor que você criou para seu projeto do Firebase. Você pode modificar e gerenciar o modelo usando o console do Firebase, que exibe o conteúdo do modelo em formato gráfico nas guias Parâmetros e Condições . Você também pode usar a API REST do Configuração remota e o SDK Admin ou a CLI do Firebase para modificar e gerenciar sua configuração.

Aqui está um exemplo de arquivo de modelo:

  {
    "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"
    }
  }

Cada vez que você atualiza os parâmetros, o Configuração remota cria um novo modelo com versão do Configuração remota e armazena o modelo anterior como uma versão que você pode recuperar ou reverter conforme necessário. Os números de versão são incrementados sequencialmente a partir do valor inicial armazenado pelo Configuração remota. Todos os modelos incluem um campo version conforme mostrado, contendo metadados sobre essa versão específica.

Com o Console do Firebase, a CLI do Firebase ou as APIs de back-end do Configuração remota, você pode realizar estas tarefas de gerenciamento de versão:

  • Listar todas as versões de modelos armazenados
  • Recuperar uma versão específica
  • Reverter para uma versão específica

Você pode excluir modelos do Configuração remota conforme necessário na página Histórico de alterações no console do Configuração remota. Há um limite total de 300 versões armazenadas vitalícias, que inclui números de versão armazenados para modelos excluídos. Se você publicar mais de 300 versões de modelo durante a vida de um projeto, as versões mais antigas serão excluídas, mantendo no máximo 300 versões.

Gerenciar versões de modelo do Configuração remota

Esta seção descreve como gerenciar versões do seu modelo do Configuração remota. Para obter mais detalhes sobre como criar, modificar e salvar modelos de forma programática, consulte Modificar a Configuração remota programaticamente .

Listar todas as versões armazenadas do modelo do Configuração remota

Você pode recuperar uma lista de todas as versões armazenadas do modelo do Configuração remota. Por exemplo:

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

DESCANSAR

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

Console do Firebase

Na guia Parâmetros , selecione o ícone “relógio” exibido no canto superior direito. Isso abre a página Histórico de alterações , listando todas as versões de modelos armazenadas em um menu de lista à direita.

Os detalhes exibidos para cada versão armazenada incluem informações sobre se as alterações foram originadas na Console, com a API REST, de uma reversão ou se foram alterações incrementais de 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. Passe '0' para buscar todas as versões.

A lista de modelos inclui metadados para todas as versões armazenadas, incluindo a hora da atualização, o usuário que a fez e se foi feita por meio do console ou da API REST. Aqui está um exemplo de um elemento de versão:

{
  "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

Você pode recuperar qualquer versão armazenada específica do modelo do Configuração remota. Por exemplo:

Node.js

Passe getTemplate() sem nenhum argumento para recuperar a versão mais recente do modelo ou, 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());

DESCANSAR

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 URL ?version_number é válido apenas para operações GET ; você não pode usá-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.

Console do Firebase

Por padrão, o painel de detalhes na guia Histórico de alterações exibe o modelo ativo atual. Para visualizar detalhes de outra versão na lista, selecione-a no menu direito.

Você pode visualizar uma comparação detalhada da versão atualmente selecionada e de qualquer outra versão armazenada passando o mouse sobre o menu de contexto de qualquer versão não selecionada e selecionando Comparar com a versão selecionada.

CLI do Firebase

firebase remoteconfig:get -v VERSION_NUMBER

Opcionalmente, você pode gravar a saída em um arquivo especificado com -o, FILENAME .

Reverter para uma versão armazenada específica do modelo do Configuração remota

Você pode reverter para qualquer versão armazenada do modelo. Por exemplo:

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

DESCANSAR

Para reverter para um modelo armazenado do Configuração remota, emita um HTTP POST com o método personalizado :rollback e, no corpo da solicitação, a versão específica a ser aplicada. Por 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 contém o conteúdo do modelo armazenado agora ativo, com seus metadados da nova versão.

Console do Firebase

Para versões anteriores do modelo qualificadas para reversão, um botão de opção para reverter para essa versão é exibido no canto superior direito da página Histórico de alterações . Clique e confirme apenas se tiver certeza de que deseja reverter para essa versão e usar esses valores imediatamente para todos os aplicativos e usuários.

CLI do Firebase

firebase remoteconfig:rollback -v VERSION_NUMBER

Observe que esta operação de reversão cria efetivamente uma nova versão numerada. Por exemplo, reverter da versão 10 para a versão 6 cria efetivamente uma nova cópia da versão 6, diferindo da original apenas porque seu número de versão é 11. A versão 6 original ainda está armazenada, presumindo que ainda não tenha expirado, e a versão 11 se torna o modelo ativo.

Excluir um modelo do Configuração remota

Você pode excluir modelos do Configuração remota no console do Firebase. Para excluir um modelo do Configuração remota:

  1. Na página Parâmetros de configuração remota, clique em Histórico de alterações .

  2. Alterne para o modelo que deseja excluir, clique em Mais e selecione Excluir .

  3. Quando solicitado a confirmar a exclusão, clique em Excluir .

Fazer download e publicar modelos do Configuração remota

Baixe e publique modelos do Configuração remota para integrá-los ao seu controle de origem e sistemas de criação, automatizar atualizações de configuração e manter parâmetros e valores sincronizados em vários projetos.

Você pode fazer download do modelo do Configuração remota atualmente ativo de forma programática ou no console do Firebase. Você pode então atualizar o arquivo JSON exportado e publicá-lo no mesmo projeto ou publicá-lo em um projeto novo ou existente.

Digamos que você tenha vários projetos que representam diferentes estágios do ciclo de vida de desenvolvimento de software, como ambientes de desenvolvimento, teste, preparação e produção. Nesse caso, você poderia promover um modelo totalmente testado do seu ambiente de teste para o ambiente de produção, baixando-o do seu projeto de teste e publicando-o no seu projeto de produção.

Você também pode usar esse método para migrar configurações de um projeto para outro ou preencher um novo projeto com parâmetros e valores de um projeto estabelecido.

Parâmetros e valores de parâmetros criados especificamente como variantes em um experimento de teste A/B não são incluídos em modelos exportados.

Para exportar e importar modelos do Configuração remota:

  1. Faça download do modelo atual do Configuração remota .
  2. Valide o modelo do Configuração remota .
  3. Publique o modelo do Configuração remota .

Baixe o modelo de configuração remota atual

Você pode fazer download do modelo atual e ativo do Configuração remota de maneira programática ou usando o console do Firebase.

Use os seguintes comandos para fazer download do modelo ativo do Configuração remota no formato JSON:

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

DESCANSAR

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Este comando gera a carga JSON em um arquivo e os cabeçalhos (incluindo o ETag) em um arquivo headers separado.

Console do Firebase

  1. Na guia Parâmetros ou condições de configuração remota , abra o menu e selecione Baixar arquivo de configuração atual .
  2. Quando solicitado, clique em Baixar arquivo de configuração , escolha o local onde deseja salvar o arquivo e clique em Salvar .

CLI do Firebase

firebase remoteconfig:get -o filename

Validar o modelo do Configuração remota

Você pode validar as atualizações do seu modelo antes de publicá-las 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 erros como chaves duplicadas para parâmetros e condições, nomes de condições inválidos ou condições inexistentes ou ETags mal formatadas. Por exemplo, uma solicitação contendo 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());
  }
}

DESCANSAR

Valide as atualizações do modelo anexando 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 seu modelo foi validado com sucesso, o comando curl retorna o modelo JSON que você enviou e, no arquivo headers salvo, você encontrará um status HTTP/2 200 e uma ETag atualizada com o sufixo -0 . Se o seu modelo não foi validado, você receberá o erro de validação na resposta JSON e seu arquivo headers conterá uma resposta diferente de 200 (e nenhuma ETag).

Publicar o modelo do Configuração remota

Depois de baixar um modelo, fazer as alterações necessárias no conteúdo JSON e validá-lo, você poderá publicá-lo em um projeto.

A publicação de um modelo substitui todo o modelo de configuração existente pelo arquivo atualizado e aumenta 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 será excluído do servidor e não estará mais disponível para os clientes.

Após a publicação, as alterações nos parâmetros e valores ficam imediatamente disponíveis para seus aplicativos e usuários. Se necessário, você pode reverter para uma versão anterior .

Use os seguintes comandos para publicar seu modelo:

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

DESCANSAR

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 , você pode especificar o conteúdo usando o caractere “@”, seguido do nome do arquivo.

Console do Firebase

  1. Na guia Parâmetros ou condições da configuração remota , abra o menu e selecione Publicar de um arquivo .
  2. Quando solicitado, clique em Procurar , navegue e selecione o arquivo do Configuração remota que deseja publicar e clique em Selecionar .
  3. O arquivo será validado e, se for bem-sucedido, você poderá clicar em Publicar para disponibilizar a configuração imediatamente para seus aplicativos e usuários.

As personalizações e condições do Configuração remota estão incluídas nos modelos baixados, 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 projeto para projeto.

    Por exemplo, se você tiver personalizações habilitadas em seu projeto e baixar e editar um modelo, poderá publicá-lo no mesmo projeto, mas não poderá publicá-lo em um projeto diferente, a menos que exclua as personalizações do modelo.

  • As condições podem ser importadas de projeto para projeto, mas observe que quaisquer valores condicionais específicos (como IDs de aplicativos ou públicos) devem existir no projeto de destino antes da publicação.

    Por exemplo, se você tiver um parâmetro do Configuração remota que usa uma condição que especifica um valor de plataforma iOS , o modelo poderá ser publicado em outro projeto, porque os valores de plataforma são os mesmos para qualquer projeto. No entanto, se contiver uma condição que dependa de um ID de aplicativo específico ou de um público de usuário que não exista no projeto de destino, a validação falhará.

  • Se o modelo que você planeja publicar contiver condições que dependem do Google Analytics, o Analytics deverá estar ativado no projeto de destino.

Fazer download dos padrões do modelo do Configuração remota

Como seu aplicativo nem sempre está conectado à Internet, você deve configurar os valores padrão do aplicativo do lado do cliente para todos os parâmetros do Configuração remota. Você também deve sincronizar periodicamente os valores padrão do cliente do aplicativo e os valores padrão dos parâmetros de back-end do Configuração remota, porque eles podem mudar com o tempo.

Conforme descrito nos links específicos da plataforma no final desta seção, você pode definir manualmente esses padrões no seu aplicativo ou agilizar esse processo baixando arquivos que contêm apenas os pares de valores-chave para todos os parâmetros e seus valores padrão no arquivo modelo ativo do Configuração remota. Você pode então incluir esse arquivo em seu projeto e configurar seu aplicativo para importar esses valores.

Você pode baixar esses arquivos em formato XML para aplicativos Android, formato de lista de propriedades (plist) para aplicativos iOS e JSON para aplicativos web.

Recomendamos fazer o download periódico dos padrões do Configuração remota antes de qualquer lançamento de novo aplicativo para garantir que seu aplicativo e o back-end do Configuração remota permaneçam sincronizados.

Para baixar um arquivo que contém padrões de modelo:

DESCANSAR

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 valor format , dependendo do formato de arquivo que você deseja baixar.

Console do Firebase

  1. Na guia Parâmetros , abra o menu e selecione Baixar valores padrão .
  2. Quando solicitado, clique no botão de opção que corresponde ao formato de arquivo que você deseja baixar e clique em Baixar arquivo .

Para obter mais informações sobre como importar valores padrão do Configuração remota para seu app, consulte: