Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Modificar o Configuração remota programaticamente

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Este documento descreve como você pode ler e modificar programaticamente o conjunto de parâmetros e condições formatados em JSON conhecido como modelo de configuração remota . Isso permite que você faça alterações de modelo no back-end que o aplicativo cliente pode buscar usando a biblioteca cliente.

Usando a API REST do Remote Config ou os Admin SDKs descritos neste guia, você pode ignorar o gerenciamento do modelo no Firebase console para integrar diretamente as alterações do Remote Config em seus próprios processos. Por exemplo, com as APIs de back-end do Remote Config, você pode:

  • Agendamento de atualizações do Remote Config . Ao usar chamadas de API em conjunto com um cron job, você pode alterar os valores do Remote Config regularmente.
  • Importe valores de configuração em lote para fazer a transição eficiente de seu próprio sistema proprietário para o Firebase Remote Config.
  • Use o Remote Config com Cloud Functions para Firebase , alterando valores em seu aplicativo com base em eventos que acontecem no lado do servidor. Por exemplo, você pode usar o Remote Config para promover um novo recurso em seu aplicativo e, em seguida, desativar essa promoção automaticamente assim que detectar que um número suficiente de pessoas interagiu com o novo recurso.

    Diagrama mostrando o back-end do Configuração remota interagindo com ferramentas e servidores personalizados

As seções a seguir deste guia descrevem as operações que você pode fazer com as APIs de back-end do Configuração remota. Para revisar algum código que executa essas tarefas por meio da API REST, consulte um destes aplicativos de amostra:

Modifique o Remote Config usando o Firebase Admin SDK

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

Em um fluxo de configuração remota típico, você pode obter o modelo atual, modificar alguns dos parâmetros ou grupos de parâmetros e condições, validar o modelo e, em seguida, publicá-lo. Antes de fazer essas chamadas de API, você deve autorizar as solicitações do SDK.

Inicialize o SDK e autorize solicitações de API

Quando você inicializa o 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 um { , ele será analisado como um objeto JSON. Caso contrário, o SDK assume que a string é o nome de um arquivo JSON contendo as opções.

Por exemplo:

Node.js

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

Java

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

Obtenha o modelo de configuração remota atual

Ao trabalhar com modelos do Remote Config, lembre-se de que eles são versionados e que cada versão tem um tempo de vida limitado desde o momento de sua criação até o momento em que você a substitui por uma atualização: 90 dias, com um limite total de 300 versões armazenadas. Consulte Modelos e controle de versão para obter mais informações.

Você pode usar as APIs de back-end para obter a versão ativa atual do modelo de configuração remota no formato JSON.

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

Para obter o modelo:

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

Modificar parâmetros do Remote Config

Você pode modificar e adicionar parâmetros e grupos de parâmetros do Remote config programaticamente. Por exemplo, para um grupo de parâmetros existente chamado "new_menu", você pode adicionar um parâmetro para controlar a exibição de informações sazonais:

Node.js

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

Java

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

A API permite criar novos parâmetros e grupos de parâmetros ou modificar valores padrão, valores condicionais e descrições. Em todos os casos, você deve publicar explicitamente o modelo após fazer as modificações.

Modificar as condições do Remote Config

Você pode modificar e adicionar condições e valores condicionais do Remote Config programaticamente. Por exemplo, para adicionar uma nova condição:

Node.js

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

Java

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

Em todos os casos, você deve publicar explicitamente o modelo após fazer as modificações.

As APIs de back-end do Remote Config fornecem várias condições e operadores de comparação que você pode usar para alterar o comportamento e a aparência do seu aplicativo. Para saber mais sobre as condições e os operadores com suporte para essas condições, consulte a referência de expressão condicional .

Validar o modelo de configuração remota

Opcionalmente, você pode validar suas atualizações antes de publicá-las, conforme mostrado:

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

Este processo de validação verifica erros como chaves duplicadas para parâmetros e condições, nomes de condição inválidos ou inexistentes ou etags formatados incorretamente. 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 .

Publicar o modelo de configuração remota

Depois de recuperar um modelo e revisá-lo com as atualizações desejadas, você pode publicá-lo. A publicação de um modelo conforme descrito nesta seção substitui todo o modelo de configuração existente pelo arquivo atualizado, e o novo modelo ativo recebe um número de versão um número maior do que o modelo substituído.

Se necessário, você pode usar a API REST para reverter para a versão anterior . Para mitigar o risco de erros em uma atualização, você pode validar antes de publicar .

As personalizações e condições do Remote Config 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 aplicativo ou públicos) devem existir no projeto de destino antes da publicação.

    Por exemplo, se você tiver um parâmetro de configuração remota que usa uma condição que especifica um valor de plataforma iOS , o modelo pode 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 ou público de usuário específico 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á ser ativado no projeto de destino.

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

Modificar configuração remota usando a API REST

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

Obtenha 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 você pode usar para chamar APIs do servidor Firebase de seu servidor de aplicativos ou ambiente confiável. Se você estiver desenvolvendo código localmente ou implantando seu aplicativo no local, poderá usar as credenciais obtidas por meio dessa conta de serviço para autorizar solicitações de servidor.

Para autenticar uma conta de serviço e autorizá-la a acessar os serviços do Firebase, você deve gerar um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada para sua conta de serviço:

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

  2. Clique em Gerar nova chave privada e confirme clicando em Gerar chave .

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

Ao autorizar por meio de uma conta de serviço, você tem duas opções para fornecer as credenciais ao seu aplicativo. Você pode definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS ou passar explicitamente o caminho para a chave da conta de serviço no código. A primeira opção é mais segura e é fortemente recomendada.

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. Esta variável aplica-se apenas à sua sessão de shell atual, portanto, se você abrir uma nova sessão, defina a variável novamente.

Linux ou macOS

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

janelas

Com PowerShell:

$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 sejam do Google.

Use suas credenciais do Firebase junto com a biblioteca Google Auth para seu idioma preferido para recuperar um token de acesso OAuth 2.0 de curta duração:

node.js

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

Neste exemplo, a biblioteca cliente da API do Google autentica a solicitação com um token da web JSON ou JWT. Para obter mais informações, consulte tokens da web JSON .

Pitão

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

Java

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

Após a expiração do token de acesso, o método de atualização do token é chamado automaticamente para recuperar um token de acesso atualizado.

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

Modifique o modelo de configuração remota

Ao trabalhar com modelos do Remote Config, lembre-se de que eles são versionados e que cada versão tem um tempo de vida limitado desde o momento de sua criação até o momento em que você a substitui por uma atualização: 90 dias, com um limite total de 300 versões armazenadas. Consulte Modelos e controle de versão para obter mais informações.

Obtenha o modelo de configuração remota atual

Você pode usar as APIs de back-end para obter a versão ativa atual do modelo de configuração remota no formato JSON.

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

Use os seguintes comandos:

ondulação

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

Esse comando gera a carga JSON em um arquivo e os cabeçalhos (incluindo o Etag) em um arquivo separado.

Solicitação HTTP bruta

Host: firebaseremoteconfig.googleapis.com

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

Essa chamada de API retorna o seguinte JSON, junto com um cabeçalho separado que inclui uma ETag que você usa para a solicitação subsequente.

Validar o modelo de configuração remota

Opcionalmente, você pode validar suas atualizações antes de publicá-las. Valide as atualizações do modelo anexando à sua solicitação de publicação o parâmetro de URL ?validate_only=true . Na resposta, um código de status 200 e um etag atualizado com o sufixo -0 significam que sua atualização foi validada com sucesso. Qualquer resposta diferente de 200 indica que os dados JSON contêm erros que você deve corrigir antes de publicar.

Atualize o modelo de configuração remota

Depois de recuperar um modelo e revisar o conteúdo JSON com as atualizações desejadas, você pode publicá-lo. A publicação de um modelo conforme descrito nesta seção substitui todo o modelo de configuração existente pelo arquivo atualizado, e o novo modelo ativo recebe um número de versão um número maior do que o modelo substituído.

Se necessário, você pode usar a API REST para reverter para a versão anterior . Para mitigar o risco de erros em uma atualização, você pode validar antes de publicar .

As personalizações e condições do Remote Config 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 aplicativo ou públicos) devem existir no projeto de destino antes da publicação.

    Por exemplo, se você tiver um parâmetro de configuração remota que usa uma condição que especifica um valor de plataforma iOS , o modelo pode 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 ou público de usuário específico 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á ser ativado no projeto de destino.

ondulaçã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 -d @filename

Para este comando curl , você pode especificar o conteúdo usando o caractere "@", seguido do nome do arquivo.

Solicitação HTTP bruta

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

Como esta é uma solicitação de gravação, a ETag é modificada por este comando e uma ETag atualizada é fornecida nos cabeçalhos de resposta do próximo comando PUT .

Modificar as condições do Remote Config

Você pode modificar programaticamente as condições do Remote Config e os valores condicionais. Com a API REST, você deve editar o modelo diretamente para modificar as condições antes de publicar o modelo.

{
  "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 primeiro definem um conjunto de condições e, em seguida, definem valores padrão e valores de parâmetros baseados em condições (valores condicionais ) para cada parâmetro. Ele também adiciona uma descrição opcional para cada elemento; como comentários de código, eles são para uso do desenvolvedor e não são exibidos no aplicativo. Uma ETag também é fornecida para fins de controle de versão.

As APIs de back-end do Remote Config fornecem várias condições e operadores de comparação que você pode usar para alterar o comportamento e a aparência do seu aplicativo. Para saber mais sobre as condições e os operadores com suporte para essas condições, consulte a referência de expressão condicional .

Códigos de erro HTTP

Código de estado Significado
200 Atualizado com sucesso
400 Ocorreu um erro de validação. Por exemplo, uma solicitação contendo mais do que o número permitido de chaves — 2.000 — retornaria 400 (Solicitação inválida) com a mensagem de erro Param count too large . Além disso, este código de status HTTPS pode ocorrer nestas duas situações:
  • Ocorreu um erro de incompatibilidade de versão porque o conjunto de valores e condições foi atualizado desde a última vez que você recuperou um valor ETag. Para resolver isso, você deve usar um comando GET para obter um novo modelo e valor ETag, atualizar o modelo e, em seguida, enviar usando esse modelo e o novo valor ETag.
  • Um comando PUT (atualizar solicitação de modelo de configuração remota) foi feito sem especificar um cabeçalho If-Match .
401 Ocorreu um erro de autorização (nenhum token de acesso foi fornecido ou a API REST do Firebase Remote Config não foi adicionada ao seu projeto no Cloud Developer Console)
403 Ocorreu um erro de autenticação (o token de acesso errado foi fornecido)
500 Ocorreu um erro interno. Se esse erro ocorrer, abra um tíquete de suporte do Firebase

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

Depois de enviar atualizações para seu modelo, acesse o Firebase console para verificar se suas alterações aparecem conforme o esperado. Isso é crítico porque a ordem das condições afeta como elas são avaliadas (a primeira condição que avalia true entra em vigor).

Uso de ETag e atualizações forçadas

A API REST de configuração remota usa uma tag de entidade (ETag) para evitar condições de corrida e atualizações sobrepostas para recursos. Para saber mais sobre ETags, consulte ETag - HTTP .

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

Você pode contornar a ETag e a proteção que ela fornece, forçando o modelo de configuração remota a ser atualizado da seguinte forma: If-Match: * No entanto, essa abordagem não é recomendada porque corre o risco de causar a perda de atualizações em sua configuração remota modelo se vários clientes estiverem atualizando o modelo de configuração remota. Esse tipo de conflito pode ocorrer com vários clientes usando a API ou com atualizações conflitantes de clientes de API e usuários do Firebase console.

Para obter orientação sobre como gerenciar versões de modelo do Configuração remota, consulte Modelos e controle de versão do Configuração remota .