Modificar o Configuração remota de maneira programática

Neste documento, descrevemos como ler e modificar de maneira programática o conjunto de parâmetros e condições formatados em JSON conhecidos como modelo de Remote Config. Isso permite que você modifique o modelo do back-end que o app cliente pode buscar usando a biblioteca de cliente.

Usando a API REST de Remote Config ou os Admin SDKs descritos neste guia, é possível ignorar o gerenciamento do modelo no console de Firebase para integrar diretamente as mudanças de Remote Config nos seus próprios processos. Por exemplo, com as APIs de back-end de Remote Config, é possível:

• Programar atualizações de Remote Config. Ao usar chamadas de API com um cron job, é possível alterar os valores de Remote Config regularmente.
• Importar valores de configuração em lote para fazer a transição de modo eficiente do seu próprio sistema para Firebase Remote Config.

• Usar Remote Config com Cloud Functions for Firebase, mudando valores no app com base em eventos que acontecem no servidor. Por exemplo, é possível utilizar Remote Config para promover um novo recurso no app e desativar automaticamente a promoção ao perceber que um número suficiente de pessoas já interagiu com o novo recurso.

  

As seções a seguir deste guia descrevem as operações que você pode realizar com as APIs de back-end de Remote Config. Para descobrir alguns códigos que executam essas tarefas usando a API REST, consulte um destes apps de exemplo (em inglês):

• Guia de início rápido em Java da API REST da Configuração remota do Firebase
• Guia de início rápido em Node.js da API REST da Configuração remota do Firebase
• Guia de início rápido em Python da API REST da Configuração remota do Firebase

Modificar a Configuração remota usando o SDK Admin do Firebase

O Admin SDK é um conjunto de bibliotecas de servidor que permite a interação com o Firebase em ambientes privilegiados. Além de realizar atualizações em Remote Config, Admin SDK permite a geração e a verificação de tokens de autenticação do Firebase, a leitura e a gravação em Realtime Database e assim por diante. Para saber mais sobre os pré-requisitos e a configuração de Admin SDK, consulte Adicionar o SDK Admin do Firebase ao servidor.

Em um fluxo comum de Remote Config, é possível acessar o modelo atual, modificar alguns dos parâmetros ou grupos de parâmetros e condições, validar o modelo e publicá-lo. Antes de fazer essas chamadas de API, você precisa autorizar solicitações do SDK.

Inicializar o SDK e autorizar solicitações de API

Quando você inicializa Admin SDK sem parâmetros, o SDK usa o Google Application Default Credentials e lê as opções da variável de ambiente FIREBASE_CONFIG. Se o conteúdo da variável FIREBASE_CONFIG começar com {, ele será analisado como um objeto JSON. Caso contrário, a string será tratada pelo SDK como o nome de um arquivo JSON que contém as opções.

Exemplo:

const admin = require('firebase-admin');
admin.initializeApp();

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

Conferir o modelo atual da Configuração remota

Ao trabalhar com modelos de Remote Config, lembre-se de que eles têm versões e cada versão tem uma vida útil limitada, que vai desde a criação até a substituição por meio de uma atualização: 90 dias, com um limite total de 300 versões armazenadas. Consulte Modelos e controle de versões para mais informações.

É possível usar as APIs de back-end para acessar a versão ativa atual do modelo de Remote Config no formato JSON.

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 ver o modelo:

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

Modificar parâmetros da Configuração remota

É possível modificar e adicionar parâmetros e grupos de parâmetros de Remote Config de maneira programática. Por exemplo, para um grupo de parâmetros atual chamado new_menu, é possível adicionar um parâmetro para controlar a exibição de informações sazonais:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

A API permite que você crie novos parâmetros e grupos de parâmetros ou modifique valores padrão, valores condicionais e descrições. Em todos os casos, você precisa publicar explicitamente o modelo depois de fazer as modificações.

Modificar condições da Configuração remota

É possível modificar e adicionar condições e valores condicionais de Remote Config de maneira programática. Por exemplo, para adicionar uma nova condição:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

Em todos os casos, você precisa publicar explicitamente o modelo depois de fazer as modificações.

As APIs de back-end de Remote Config oferecem várias condições e operadores de comparação que podem ser usados para mudar o comportamento e a aparência do app. Para saber mais sobre as condições e os operadores compatíveis, consulte a referência de expressão condicional.

Validar o modelo da Configuração remota

Se preferir, valide as atualizações antes de publicá-las, conforme mostrado a seguir:

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

Esse processo de validação verifica se há erros, como chaves duplicadas de parâmetros e condições, nomes de condições inválidas ou 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.

Publicar o modelo da Configuração remota

Depois de recuperar um modelo e revisá-lo com as atualizações desejadas, será possível publicá-lo. Ao publicar um modelo, conforme descrito nesta seção, você substitui todo o modelo atual pelo arquivo atualizado. Além disso, o novo modelo ativo recebe uma versão que é um número maior do que aquele que foi substituído.

Se necessário, use a API REST para reverter para a versão anterior. Para reduzir o risco de erros em uma atualização, valide antes de publicar.

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.

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

Modificar a Configuração remota usando a API REST

Esta seção descreve os principais recursos da API REST de Remote Config em https://firebaseremoteconfig.googleapis.com. Para detalhes completos, consulte a referência da API.

Receber um token de acesso para autenticar e autorizar solicitações de API

Os projetos do Firebase oferecem suporte a contas de serviço do Google, que podem ser usadas para chamar APIs do servidor do Firebase a partir do seu servidor de aplicativos ou de um ambiente confiável. Se você estiver desenvolvendo código ou implantando o aplicativo localmente, será possível usar credenciais recebidas por essa conta de serviço para autorizar solicitações do servidor.

Para autenticar uma conta de serviço e autorizá-la para acessar os serviços do Firebase, gere um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada da conta de serviço, siga estas etapas:

1. No console Firebase, abra Configurações > Contas de serviço.

2. Clique em Gerar nova chave privada e selecione Gerar chave para confirmar.

3. Armazene com segurança o arquivo JSON que contém a chave.

Ao autorizar por meio de uma conta de serviço, existem duas opções para fornecer as credenciais ao seu aplicativo. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou transmita explicitamente o caminho para a chave da conta de serviço no código. A primeira opção é mais segura e é altamente recomendável.

Para definir a variável de ambiente:

Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, defina a variável novamente.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Depois de concluir as etapas acima, o Application Default Credentials (ADC) pode determinar implicitamente suas credenciais, permitindo que você use as credenciais da conta de serviço ao testar ou executar em ambientes que não são do Google.

Use as credenciais do Firebase com a Biblioteca do Google Auth para sua linguagem preferida e recupere um token de acesso do OAuth 2.0 de curta duração:

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

public static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
FirebaseRemoteConfigSnippets.java

O método de atualização de token é chamado automaticamente para recuperar um token atualizado após o de acesso expirar.

Para autorizar o acesso ao Remote Config, solicite o escopo https://www.googleapis.com/auth/firebase.remoteconfig.

Modificar o modelo da Configuração remota

Ao trabalhar com modelos de Remote Config, lembre-se de que eles têm versões e cada versão tem uma vida útil limitada, que vai desde a criação até a substituição por meio de uma atualização: 90 dias, com um limite total de 300 versões armazenadas. Consulte Modelos e controle de versões para mais informações.

Conferir o modelo atual da Configuração remota

É possível usar as APIs de back-end para acessar a versão ativa atual do modelo de Remote Config no formato JSON.

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.

Use os seguintes comandos:

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

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

Validar o modelo da Configuração remota

Se preferir, valide suas atualizações antes de publicá-las. Para validar as atualizações do modelo, inclua o parâmetro de URL ?validate_only=true na solicitação de publicação. Na resposta, um código de status 200 e uma ETag atualizada com o sufixo -0 significa que sua atualização foi validada com êxito. Qualquer resposta que não tenha o código 200 indica que os dados JSON contêm erros que precisam ser corrigidos antes da publicação.

Atualizar o modelo da Configuração remota

Depois de recuperar um modelo e revisar o conteúdo do JSON com as atualizações desejadas, ele estará pronto para publicação. Ao publicar um modelo, conforme descrito nesta seção, você substitui todo o modelo atual pelo arquivo atualizado. Além disso, o novo modelo ativo recebe uma versão que é um número maior do que aquele que foi substituído.

Se necessário, use a API REST para reverter para a versão anterior. Para reduzir o risco de erros em uma atualização, valide antes de publicar.

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.

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

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

Modificar condições da Configuração remota

É possível modificar de maneira programática as condições e os valores condicionais de Remote Config. Na API REST, antes de publicar o modelo, é necessário editá-lo diretamente para modificar as condições.

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

As modificações acima definem primeiro um conjunto de condições e, em seguida, os valores padrão e de parâmetros baseados em condições (valores condicionais) de cada parâmetro. Além disso, adicionam uma descrição opcional para cada elemento. Assim como os comentários de código, eles são para uso do desenvolvedor e não são exibidos no aplicativo. ETag também é fornecida para fins de controle de versão.

As APIs de back-end de Remote Config oferecem várias condições e operadores de comparação que podem ser usados para mudar o comportamento e a aparência do app. Para saber mais sobre as condições e os operadores compatíveis, consulte a referência de expressão condicional.

Códigos de erro HTTP

Um código de status 200 indica que o modelo de Remote Config (parâmetros, valores e condições do projeto) foi atualizado e agora está disponível para apps que usam esse projeto. Outros códigos de status indicam que o modelo de Remote Config que existia anteriormente ainda está em vigor.

Depois de enviar atualizações para o modelo, acesse o console de Firebase e verifique se as mudanças estão aparecendo conforme o esperado. Esta ação é fundamental, já que a ordem das condições afeta o modo como elas são definidas. A primeira condição que tiver uma definição true entrará em vigor.

Uso de ETag e atualizações forçadas

A API REST de Remote Config usa uma tag de entidade (ETag) para evitar disputas e sobreposições das atualizações nos recursos. Para saber mais sobre ETags, acesse ETag – HTTP.

Para a API REST, o Google recomenda armazenar em cache a ETag fornecida pelo comando GET mais recente e usar esse valor de ETag no cabeçalho da solicitação If-Match ao emitir comandos PUT. Se o comando PUT resultar em um código de status HTTPS 409, emita um novo comando GET para receber uma nova ETag e um novo modelo a ser usado com seu próximo comando PUT.

É possível evitar o uso de ETag e da proteção fornecida por ele forçando a atualização do modelo de Remote Config da seguinte maneira: If-Match: * No entanto, essa abordagem não é recomendada porque pode causar a perda de atualizações no modelo de Remote Config caso vários clientes estejam atualizando o modelo de Remote Config. Esse tipo de conflito poderá ocorrer se vários clientes estiverem usando a API ou se houver atualizações conflitantes de clientes de APIs e usuários do console de Firebase.

Para conferir orientações sobre o gerenciamento de versões de modelos de Remote Config, consulte Modelos e controle de versões da Configuração remota.