获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

Modificar o Configuração remota programaticamente

Este documento descreve como você pode ler e modificar programaticamente o conjunto de parâmetros e condições formatados em JSON conhecidos como modelo do 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 Configuração remota ou os SDKs Admin descritos neste guia, você pode ignorar o gerenciamento do modelo no console do Firebase para integrar diretamente as alterações do Configuração remota em seus próprios processos. Por exemplo, com as APIs de back-end do Configuração remota, você pode:

  • Agendamento de atualizações do Configuração remota . Ao usar chamadas de API em conjunto com um cron job, você pode alterar os valores do Remote Config regularmente.
  • Valores de configuração de importação em lote para fazer a transição eficiente do seu próprio sistema proprietário para o Firebase Remote Config.
  • Use o Configuração remota com o Cloud Functions para Firebase , alterando os valores no seu aplicativo com base em eventos que ocorrem no servidor. Por exemplo, você pode usar o Configuração remota 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 interagiram com o novo recurso.

    Diagrama mostrando o back-end do Remote Config 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 alguns códigos que executam essas tarefas por meio da API REST, consulte um destes aplicativos de exemplo:

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

O Admin SDK é um conjunto de bibliotecas de servidor que permite interagir com o Firebase a partir de ambientes privilegiados. Além de realizar atualizações no Configuração remota, o SDK Admin 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 SDK Admin, consulte Adicionar o SDK Admin do Firebase ao seu servidor .

Em um fluxo típico do Configuração remota, você pode obter 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ê deve autorizar 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 que contém 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 Configuração remota, lembre-se de que eles são versionados e que cada versão tem um tempo de vida limitado desde o momento da 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 do 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 Configuração remota

Você pode modificar e adicionar programaticamente parâmetros e grupos de parâmetros do Configuração remota. 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 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ê deve publicar explicitamente o modelo após fazer as modificações.

Modificar as condições do Configuração remota

Você pode modificar e adicionar programaticamente condições e valores condicionais do Configuração remota. 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 Configuração remota 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 do 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());
  }
}

Esse processo de validação verifica erros como chaves duplicadas para parâmetros e condições, nomes de condições inválidos ou condições inexistentes ou tags mal formatadas. Por exemplo, uma solicitação contendo mais do que o número permitido de chaves—2000—retornaria a mensagem de erro, Param count too large .

Publicar o modelo do 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 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 arquivos .

As personalizações e as 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-alvo) 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 de iOS , o modelo pode ser publicado em outro projeto, pois os valores de plataforma são os mesmos para qualquer projeto. No entanto, se ele 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á 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 o Configuração remota usando a API REST

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

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

Os projetos do Firebase são compatíveis com contas de serviço do Google , que você pode usar para chamar as APIs do servidor Firebase do seu servidor de aplicativos ou ambiente confiável. Se você estiver desenvolvendo código localmente ou implantando seu aplicativo no local, poderá usar credenciais obtidas por meio dessa conta de serviço para autorizar solicitações do 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 pode 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 para o caminho do arquivo JSON que contém sua chave de conta de serviço. Esta variável só se aplica à 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 Google Auth Library 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 Configuração remota, solicite o escopo https://www.googleapis.com/auth/firebase.remoteconfig .

Modificar o modelo do Configuração remota

Ao trabalhar com modelos do Configuração remota, lembre-se de que eles são versionados e que cada versão tem um tempo de vida limitado desde o momento da 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 do 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

Este comando gera a carga JSON para um arquivo e os cabeçalhos (incluindo o Etag) para 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 JSON a seguir, juntamente com um cabeçalho separado que inclui uma ETag que você usa para a solicitação subsequente.

Validar o modelo do 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 uma etag atualizada com o sufixo -0 significa 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.

Atualizar o modelo do 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 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 arquivos .

As personalizações e as 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-alvo) 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 de iOS , o modelo pode ser publicado em outro projeto, pois os valores de plataforma são os mesmos para qualquer projeto. No entanto, se ele 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á 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 pelo 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 esse comando e uma ETag atualizada é fornecida nos cabeçalhos de resposta do próximo comando PUT .

Modificar as condições do Configuração remota

Você pode modificar programaticamente as condições e os valores condicionais do Configuração remota. 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. 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 Configuração remota 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 status 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—2000—retornaria 400 (Bad Request) 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 enviar usando esse modelo e o novo valor ETag.
  • Um comando PUT (solicitação de modelo de atualização 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 (foi fornecido o token de acesso incorreto)
500 Ocorreu um erro interno. Se esse erro ocorrer, envie um tíquete de suporte do Firebase

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

Depois de enviar atualizações para seu modelo, acesse o console do Firebase para verificar se as alterações aparecem conforme o esperado. Isso é crítico porque a ordenação 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 do Configuração remota usa uma tag de entidade (ETag) para evitar condições de corrida e atualizações sobrepostas nos recursos. Para saber mais sobre ETags, consulte 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 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 oferece, forçando a atualização do modelo do Remote config da seguinte forma: If-Match: * No entanto, essa abordagem não é recomendada porque corre o risco de causar a perda de atualizações do Remote config modelo se vários clientes estiverem atualizando o modelo do Configuração remota. Esse tipo de conflito pode ocorrer com vários clientes usando a API ou com atualizações conflitantes de clientes da API e usuários do console do Firebase.

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 .