Modelos e controle de versões da Configuração remota

Os modelos de Remote Config são conjuntos de parâmetros e condições no formato JSON que você criou para o projeto do Firebase. Você pode criar modelos de cliente, onde o app busca valores, e modelos de servidor, onde os clientes do servidor podem buscar valores.

É possível modificar e gerenciar o modelo usando o console de 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 o SDK Admin e a API REST de Remote Config ou a CLI de Firebase para modificar e gerenciar o modelo de cliente.

Confira um exemplo de arquivo de modelo de servidor:

{
  "parameters": {
    "preamble_prompt": {
      "defaultValue": {
        "value": "You are a helpful assistant who knows everything there is to know about Firebase! "
      },
      "description": "Add this prompt to the user's prompt",
      "valueType": "STRING"
    },
    "model_name": {
      "defaultValue": {
        "value": "gemini-pro-test"
      },
      "valueType": "STRING"
    },
    "generation_config": {
      "defaultValue": {
        "value": "{\"temperature\": 0.9, \"maxOutputTokens\": 2048, \"topP\": 0.9, \"topK\": 20}"
      },
      "valueType": "JSON"
    },
  },
  "version": {
    "versionNumber": "19",
    "isLegacy": true
  }
}

É possível realizar estas tarefas de gerenciamento de versões com o console de 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 de Remote Config da página Histórico de alterações

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 você atualiza os parâmetros, Remote Config cria um modelo de Remote Config com controle de versões 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 de maneira sequencial com base no valor inicial armazenado por Remote Config. Todos os modelos incluem um campo version, conforme mostrado, que contém metadados sobre essa versão específica.

É possível excluir modelos de Remote Config conforme necessário na página Histórico de alterações do console de Remote Config.

Gerenciar versões do modelo de Remote Config

Esta seção descreve como gerenciar versões do modelo de Remote Config.

Listar todas as versões armazenadas do modelo de Remote Config

É possível recuperar uma lista de todas as versões armazenadas do modelo de Remote Config. As etapas para fazer isso:

firebase remoteconfig:versions:list

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

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

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 de Remote Config

É possível recuperar qualquer versão específica armazenada do modelo de Remote Config. Para recuperar uma versão de modelo armazenada:

firebase remoteconfig:get -v VERSION_NUMBER

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

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

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

Reverter para uma versão específica armazenada do modelo de Remote Config

É possível reverter para qualquer versão armazenada do modelo. Para reverter um modelo:

firebase remoteconfig:rollback -v VERSION_NUMBER

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

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

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}'

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 de Remote Config

É possível excluir modelos de Remote Config no console de Firebase. Para excluir um modelo de Remote Config, faça o seguinte:

1. Alterne para o modelo que você quer excluir, clique em more_vertMais e selecione Excluir.

2. Clique em Excluir para confirmar a exclusão.

Fazer o download e publicar modelos de Remote Config

Faça o download e publique modelos de Remote Config para integrá-los aos sistemas de build e controle de origem, automatizar atualizações de configuração e manter os parâmetros e valores sincronizados em vários projetos.

É possível fazer o download do modelo de Remote Config ativo no momento, no console de Firebase. É possível atualizar o arquivo JSON exportado e publicá-lo no mesmo projeto ou em um projeto novo ou atual.

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 de A/B Testing não estão incluídos nos modelos exportados.

Para exportar e importar modelos de Remote Config:

1. Faça o download do modelo de Remote Config atual.
2. Valide o modelo de Remote Config.
3. Publique o modelo de Remote Config.

Faça o download do modelo atual da Configuração remota

Use o seguinte para fazer o download do modelo de Remote Config ativo no formato JSON:

firebase remoteconfig:get -o filename

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

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

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

Validar o modelo da Configuração remota

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.

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

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

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

Publicar o modelo de Remote Config

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:

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

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

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

As personalizações e condições de Remote Config estão incluídas nos modelos salvos. Por isso, é importante estar ciente das seguintes limitações ao tentar fazer a publicação 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 de Remote Config 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 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 de Google Analytics, Analytics precisa estar ativado no projeto de destino.

Fazer o download dos padrões do modelo de Remote Config

Como o app nem sempre está conectado à Internet, é necessário configurar os valores padrão do app do cliente para todos os parâmetros de Remote Config. Além disso, você precisa sincronizar periodicamente os valores padrão do cliente do app e os valores de parâmetro padrão do back-end de Remote Config, porque eles 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 de Remote Config. 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 de Remote Config antes de lançar uma nova versão do app para garantir que o app e o back-end de Remote Config permaneçam sincronizados.

Para fazer o download de um arquivo com padrões de modelo:

curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=file_format'

Para saber como importar valores padrão de Remote Config no app, acesse:

• Definir valores de parâmetros padrão no app para Android

• Definir valores de parâmetros padrão no app para iOS

• Definir valores de parâmetros padrão no app para a Web

• Definir valores de parâmetros padrão no app para Unity

• Definir valores de parâmetros padrão no app para C++