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 conhecido 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 da Configuração remota ou os SDKs administrativos descritos neste guia, você pode ignorar o gerenciamento do modelo no Console do Firebase para integrar diretamente as alterações da Configuração remota aos seus próprios processos. Por exemplo, com 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 da Configuração remota regularmente.
• Importe valores de configuração em lote para fazer a transição eficiente do seu próprio sistema proprietário para o Firebase Remote Config.

• Use a Configuração remota com o Cloud Functions para Firebase , alterando valores no seu aplicativo com base em eventos que acontecem no servidor. Por exemplo, você pode usar a Configuração remota para promover um novo recurso no seu aplicativo e, em seguida, desativar essa promoção automaticamente quando detectar que um número suficiente de pessoas 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 do Configuração remota. Para revisar alguns códigos que executam essas tarefas por meio da API REST, consulte um destes aplicativos de exemplo:

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

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

O Admin SDK é um conjunto de bibliotecas de servidor que permite interagir com o Firebase em ambientes privilegiados. Além de realizar atualizações no Configuração remota, 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 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 Google Application Default Credentials e lê 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, o SDK assume que a string é o nome de um arquivo JSON que contém as opções.

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

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 uma vida útil limitada 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 em modelos exportados.

Para obter 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 do Configuração remota

Você pode modificar e adicionar programaticamente parâmetros e grupos de parâmetros do Configuração remota. Por exemplo, a um grupo de parâmetros existente chamado "new_menu", você poderia 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 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 modificações.

Modificar condições do Configuração remota

Você pode modificar e adicionar condições e valores condicionais do Configuração remota 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ê deve publicar explicitamente o modelo após fazer modificações.

As APIs de back-end do Configuração remota fornecem diversas condições e operadores de comparação que você pode usar para alterar o comportamento e a aparência do seu app. Para saber mais sobre as condições e os operadores suportados por 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:

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

Este 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 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 .

Publicar o modelo do Configuração remota

Depois de recuperar um modelo e revisá-lo com as atualizações desejadas, você poderá 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 que ele substituiu.

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 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.

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 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 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 a partir do seu servidor de aplicativos ou ambiente confiável. Se estiver desenvolvendo código localmente ou implantando seu aplicativo localmente, você 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 é altamente 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 sua conta de serviço. Esta variável se aplica apenas à sua sessão atual do shell, portanto, 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) poderá determinar implicitamente suas credenciais, permitindo que você use credenciais de 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:

 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

Depois que seu token de acesso expirar, o método de atualização de token será 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 uma vida útil limitada 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 em 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 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 um etag atualizado 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 devem ser corrigidos antes da publicação.

Atualizar o modelo do Configuração remota

Depois de recuperar um modelo e revisar o conteúdo JSON com as atualizações desejadas, você poderá 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 que ele substituiu.

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 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.

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 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 definem primeiro 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; assim como os 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 diversas condições e operadores de comparação que você pode usar para alterar o comportamento e a aparência do seu app. Para saber mais sobre as condições e os operadores suportados por essas condições, consulte a referência de expressão condicional .

Códigos de erro HTTP

Um código de status 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 ao seu modelo, acesse o console do Firebase para verificar se as alterações aparecem conforme o esperado. Isto é crítico porque a ordem das condições afeta a forma 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 de recursos. Para saber mais sobre ETags, consulte ETag - HTTP .

Para a API REST, o Google recomenda armazenar em cache o ETag fornecido pelo comando GET mais recente e usar 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ê deverá emitir um novo comando GET para adquirir uma nova ETag e um novo modelo para usar com seu próximo comando PUT .

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

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