Usa la API de REST de Remote Config

En este documento se describe cómo usar la API de REST de Remote Config para leer y modificar el conjunto de parámetros y condiciones con formato JSON conocido como la plantilla de Remote Config. Esto permite administrar la plantilla de forma programática, realizando cambios en el backend que la app cliente puede obtener mediante la biblioteca de cliente.

Si usas esta API, puedes aplicar los cambios de Remote Config de forma directa en tus propios procesos, sin que sea necesario administrar la plantilla en la consola de Remote Config. Por ejemplo, con la API de REST de Remote Config podrías:

  • Programar actualizaciones de Remote Config. Puedes usar la API de REST junto con un trabajo cron para cambiar los valores de Remote Config periódicamente.
  • Importar los valores de configuración por lotes para realizar una transición eficiente de tu propio sistema a Firebase Remote Config.
  • Usar Remote Config con Cloud Functions para Firebase, cambiando los valores en tu app según los eventos que ocurren en el servidor. Por ejemplo, puedes usar Remote Config para promocionar una función nueva en tu app y luego desactivar automáticamente esa promoción una vez que detectes que suficientes usuarios interactuaron con la función.

Las siguientes secciones de esta guía explican los pasos necesarios para comenzar a usar la API de REST de Remote Config. Si prefieres ejecutar solo el código, además de inspeccionarlo, consulta una de las apps de ejemplo que demuestran cómo usar la API de REST de Remote Config.

Comienza a usar la API de REST de Remote Config

En los pasos de esta sección, se describe cómo obtener y modificar una plantilla de Remote Config con la API.

Paso 1: Configura valores en Firebase console

Por lo general, debes comenzar por configurar valores en Firebase console. Solo como ejemplo, supongamos que configuraste la app de muestra del inicio rápido de Remote Config para iOS o Android. Para esta app, solo debes agregar los siguientes dos parámetros a Firebase console:

Clave de parámetro Valor predeterminado Notas
welcome_message Bienvenido a esta app de ejemplo Cámbialo si deseas usar un mensaje de bienvenida diferente.
welcome_message_caps false Asígnale el valor true para que el mensaje de bienvenida se muestre en mayúsculas.

Paso 2: Obtén un token de acceso para autenticar y autorizar las solicitudes a la API

Los proyectos de Firebase son compatibles con las cuentas de servicio de Google, las que puedes usar para llamar a las API del servidor de Firebase desde tu servidor de apps o un entorno de confianza. Si desarrollas código de manera local e implementas tu aplicación de manera local o en una nube que no es de Google ni es compatible con el servicio de credenciales predeterminadas de la aplicación (ADC), puedes usar credenciales obtenidas por la cuenta de servicio para autorizar las solicitudes del servidor.

Para autenticar una cuenta de servicio y autorizar su acceso a los servicios de Firebase, debes generar un archivo de claves privadas en formato JSON.

Sigue estos pasos a fin de generar un archivo de claves privadas para tu cuenta de servicio:

  1. En Firebase console, abre Configuración > Cuentas de servicio.

  2. Haz clic en Generar nueva clave privada y, luego, en Generar clave para confirmar.

  3. Almacena de forma segura el archivo JSON que contiene la clave. Necesitarás este archivo para autorizar las solicitudes del servidor de forma manual.

Para recuperar el token de acceso de OAuth 2.0 de corta duración, usa las credenciales de Firebase y la biblioteca cliente de la API de Google en tu lenguaje preferido, y haz referencia al archivo JSON de la clave privada como se muestra a continuación:

Node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    var key = require('./service-account.json');
    var jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

Python

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 {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

Cuando venza el token de acceso, se llamará a su método de actualización automáticamente para obtener un token actualizado.

Para autorizar el acceso a Remote Config, solicita el alcance https://www.googleapis.com/auth/firebase.remoteconfig.

Paso 3: Obtén JSON desde el servicio de Remote Config con la API

A continuación, puedes usar la API para obtener la plantilla de la versión activa actual de Remote Config en formato JSON. Para ello, usa el siguiente comando y escribe el ID de tu proyecto (disponible en el panel Configuración de Firebase console) en lugar de <my-project-id>:

Comando curl:

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

Este comando envía la carga útil JSON a un archivo y los encabezados (incluida la Etag) a un archivo independiente.

Solicitud HTTP sin procesar:

Host: firebaseremoteconfig.googleapis.com

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

Esta llamada de API muestra el siguiente JSON, junto con un encabezado independiente que incluye una ETag que debes usar para la solicitud posterior. El siguiente ejemplo incluye el JSON que se muestra como resultado de la operación:

{
  "parameters":[
    {
      "key":"welcome_message",
      "value_options":[
        {
          "value":"Welcome to this sample app"
        }
      ]
    },
    {
      "key":"welcome_message_caps",
      "value_options":[
        {
          "value":"false"
        }
      ]
    }
  ],
  "version":{
    "version_number": "42",
    "update_time":"2018-05-11T18:46:40Z",
    "update_user":{
      "name":"Jane Developer",
      "email":"jane@developer.org",
      "imageUrl":"http://image.google.com/path-to-profile-photo-for-jane"
    },
    "description":"Adding welcome messages",
    "update_origin":"CONSOLE",
    "update_type":"INCREMENTAL_UPDATE"
  }
}

Paso 4: Agrega condiciones a los datos de JSON

A continuación, agrega algunas condiciones y valores condicionales para actualizar la app de muestra a fin de lograr lo siguiente:

  • Mostrar un mensaje levemente distinto (que incluya la palabra "nuevo") al 10% de los usuarios.
  • Mostrar el mensaje en mayúsculas para los usuarios de Estados Unidos o el Reino Unido.

Para extender el JSON de estas maneras, crea un archivo que contenga lo siguiente:

{
  "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."
    }
  }
}

El JSON anterior define en primer lugar un conjunto de condiciones y, luego, define los valores predeterminados y de parámetros basados en condiciones (valores condicionales) para cada parámetro. También agrega una descripción opcional para cada elemento. Al igual que los comentarios de código, estas son para el uso de los programadores y no se muestran en la app. Además, se proporciona una ETag en un encabezado independiente para fines de control de versión.

La API de REST de Remote Config proporciona varias condiciones y operadores de comparación que puedes usar para cambiar el comportamiento y el aspecto de tu app. Si quieres obtener más información sobre las condiciones y sus respectivos operadores compatibles, consulta la información de referencia de las expresiones condicionales.

Paso 5: Publica datos JSON para reemplazar datos en el servicio de Remote Config

Después de crear un archivo JSON para actualizar tu plantilla de Remote Config, puedes publicarlo. Para ello, agrega al siguiente comando el JSON que se mostró antes y reemplaza la configuración existente. Esta operación reemplaza toda la plantilla de configuración existente por el archivo actualizado, y a la plantilla activa nueva se le asigna un número de versión con un número mayor que el de la plantilla que reemplazó.

Para el comando curl, puedes especificar el contenido mediante el carácter “@” seguido del nombre del archivo.

Si es necesario, puedes regresar a la versión anterior. Para mitigar el riesgo de errores en una actualización, puedes validarla antes de publicarla.

Comando curl:

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

Solicitud HTTP sin procesar:

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

Debido a que se trata de una solicitud de escritura, este comando modifica la ETag y se proporciona una actualizada en los encabezados de respuesta del siguiente comando PUT.

Validar antes de publicar

Además, puedes validar tus actualizaciones antes de publicarlas. Para ello, adjunta a tu solicitud de publicación el parámetro de URL ?validate_only=true. Si la respuesta tiene el código de estado 200 y la ETag actualizada con el sufijo -0, la actualización se validó correctamente. Cualquier respuesta que no sea 200 indica que los datos de JSON contienen errores que debes corregir antes de publicar.

Códigos de error

Código de estado Significado
200 Se actualizó correctamente.
400 Se produjo un error de validación. Por ejemplo, una solicitud que contiene más claves que la cantidad permitida (2,000) mostraría el código 400 (Solicitud incorrecta) con el mensaje de error Param count too large.
401 Se produjo un error de autorización (no se proporcionó ningún token de acceso o no se agregó la API de REST de Firebase Remote Config a tu proyecto en Cloud Developer Console)
403 Ocurrió un error de autenticación (se proporcionó el token de acceso incorrecto)
409 Este código de estado HTTPS puede ocurrir en dos situaciones:
  • Ocurrió un error de coincidencia de versión debido a que el conjunto de valores y condiciones se actualizó desde que recuperaste el valor de una ETag por última vez. Para resolver esto, debes usar un comando GET para obtener una plantilla nueva y el valor de la ETag, actualizar la plantilla y, a continuación, enviarla con el valor de la ETag nueva.
  • Se aplicó un comando PUT (solicitud de plantilla de actualización de Remote Config) sin especificar un encabezado If-Match.
500 Se produjo un error interno. En este caso, envía un ticket de asistencia de Firebase.

Un código de estado 200 significa que la plantilla de Remote Config (parámetros, valores y condiciones del proyecto) se actualizó y ahora está disponible para las apps que usan este proyecto. Otros códigos de estado indican que la plantilla de Remote Config que existía anteriormente sigue en vigencia.

Después de enviar actualizaciones a tu plantilla, ve a Firebase console para verificar que los cambios aparezcan como esperabas. Esto es fundamental, ya que el orden de las condiciones afecta la manera en que se evalúan (se aplica la primera condición evaluada como true).

Uso de la ETag y actualizaciones forzadas

La API de REST de Remote Config usa una etiqueta de entidad (ETag) para evitar condiciones de carrera y la superposición de actualizaciones en los recursos. Para obtener más información sobre ETags, consulta ETag - HTTP.

Google recomienda almacenar en caché la ETag que proporcionó el comando GET más reciente y usar el valor de esa ETag en el encabezado de la solicitud If-Match cuando emitas comandos PUT. Si el comando PUT genera un código de estado HTTPS 409, debes emitir un comando GET nuevo para obtener una ETag y una plantilla nueva para usar con el siguiente comando PUT.

Para evadir la ETag y su protección, puedes forzar la actualización de la plantilla de Remote Config de la siguiente manera: If-Match: * Sin embargo, no es recomendable utilizar este método, ya que se corre el riesgo de causar la pérdida de las actualizaciones en tu plantilla de Remote Config si varios clientes están actualizándola simultáneamente. Este tipo de conflicto podría ocurrir si hay varios clientes usando la API o si varios clientes de la API y usuarios de Firebase console envían actualizaciones incompatibles.

Para obtener orientación sobre cómo administrar las versiones de plantillas de Remote Config, consulta Plantillas y control de versiones de Remote Config.

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.