IBM Cloud Docs
SDK de cliente de App Configuration JavaScript

SDK de cliente de App Configuration JavaScript

Para mejorar la seguridad de las aplicaciones que utilizan ' ibm-appconfiguration-js-client-sdk', se recomienda encarecidamente utilizar una APIKey cifrada en lugar de la APIKey normal en el método init. Este cambio es vital para evitar la exposición de credenciales sensibles cuando los usuarios inspeccionan su aplicación web. Si ya está utilizando una APIKey sin cifrar, actualice su aplicación para generar y utilizar la APIKey cifrada siguiendo los pasos que se mencionan aquí.

Visión general

IBM Cloud App Configuration JavaScript Client SDK se utiliza para realizar la evaluación de propiedades y banderas de características en aplicaciones web y realizar el seguimiento de métricas personalizadas para Experimentación basadas en la configuración en el servicio IBM Cloud {{site {{site.data.keyword.appconfig_short}} servicio.

IBM Cloud App Configuration es un servicio centralizado de gestión y configuración de funciones en IBM Cloud para su uso con aplicaciones web y móviles, microservicios y entornos distribuidos distribuidos.

Instrumente sus aplicaciones web con App Configuration JavaScript Client SDK, y utilice el cuadro de mandos, la CLI o la API App Configuration para definir banderas o propiedades de características, organizadas en colecciones y dirigidas a segmentos. Alterne los estados de las banderas de funciones en la nube para activar o desactivar funciones en su aplicación o entorno, cuando sea necesario. Realice experimentos y mida el efecto de los indicadores de funciones en los usuarios finales mediante el seguimiento de métricas personalizadas. También puede gestionar las propiedades para aplicaciones distribuidas de forma central.

Compatibilidad con navegadores: El SDK es compatible con los principales navegadores. El navegador debe ser compatible con la API " fetch() ".

Integración de SDK de cliente para JavaScript

Instalación

Instale el SDK. Utilice el siguiente código para instalar como módulo desde el gestor de paquetes.

npm install ibm-appconfiguration-js-client-sdk

Puede importar el SDK en la etiqueta script haciendo referencia a él desde un sitio alojado en su backend o desde una CDN como se indica a continuación:

Ejemplo:

<script type="text/javascript" src="https://unpkg.com/ibm-appconfiguration-js-client-sdk/dist/appconfiguration.js"></script>

Inicializar SDK

Inicialice el sdk para conectarse con la instancia de servicio de App Configuration.

const region = AppConfiguration.REGION_US_SOUTH;
const guid = '<guid>';
const apikey = '<encrypted_apikey>';

const collectionId = 'airlines-webapp';
const environmentId = 'dev';

const appConfigClient = AppConfiguration.getInstance();

async function initialiseAppConfig() {
    appConfigClient.init(region, guid, apikey);
    await appConfigClient.setContext(collectionId, environmentId);
}

try {
    await initialiseAppConfig();
    console.log("app configuration sdk init successful");
} catch (e) {
    console.error("failed to initialise app configuration sdk", e);
}

En el fragmento anterior, la función asíncrona initialiseAppConfig() devolverá un objeto de respuesta ( Promise<void> ) que se resolverá cuando las configuraciones se obtengan correctamente. En caso contrario, arroja un error si no se consigue.

Se espera que la inicialización se realice una sola vez.

Una vez que el SDK se haya inicializado correctamente, la bandera de características y las propiedades se pueden recuperar utilizando el appConfigClient, como se muestra en el siguiente fragmento de código.

Ampliar para ver el fragmento de ejemplo
// other-file.js
const appConfigClient = AppConfiguration.getInstance();

const feature = appConfigClient.getFeature('online-check-in');
const result = feature.getCurrentValue(entityId, entityAttributes);
console.log(result);

const property = appConfigClient.getProperty('check-in-charges');
const result = property.getCurrentValue(entityId, entityAttributes);
console.log(result);

donde,

  • región: Nombre de la región donde se crea la instancia del servicio App Configuration. Consulte aquí la lista de lugares compatibles. Por ejemplo: us-south, au-syd, etc.
  • guid: ID de instancia del servicio App Configuration. Obténgala en la sección de credenciales de servicio del panel App Configuration.
  • apikey: La APIKey encriptada generada como se describe aquí.
  • collectionId: ID de la colección creada en la instancia de servicio App Configuration en la sección Colecciones.
  • environmentId: ID del entorno creado en la instancia de servicio App Configuration en el apartado Entornos.

Utilice siempre la APIKey encriptada para evitar exponer información sensible.
Asegúrese de crear las credenciales de servicio con el rol " Client SDK ", ya que tiene los permisos de acceso mínimos adecuados para su uso en aplicaciones basadas en navegador.

Ejemplos para utilizar API relacionadas con propiedades y características

Consulte los ejemplos siguientes para utilizar las API relacionadas con características.

Obtener una única característica

const feature = appConfigClient.getFeature('featureId'); // throws error incase the featureId is invalid or doesn't exist
console.log(`Feature Name ${feature.getFeatureName()} `);
console.log(`Feature Id ${feature.getFeatureId()} `);
console.log(`Feature Type ${feature.getFeatureDataType()} `);

Obtener todas las características

const features = appConfigClient.getFeatures();
const feature = features['featureId'];

if (feature !== undefined) {
  console.log(`Feature Name ${feature.getFeatureName()} `);
  console.log(`Feature Id ${feature.getFeatureId()} `);
  console.log(`Feature Type ${feature.getFeatureDataType()} `);
  console.log(`Is feature enabled? ${feature.isEnabled()} `);
}

Evaluar una característica

Utilice el método feature.getCurrentValue(entityId, entityAttributes) para evaluar el valor del indicador de característica. Este método devuelve uno de los valores Habilitado/Inhabilitado/Sobrescrito basándose en la evaluación. El tipo de datos del valor devuelto coincide con el del distintivo de característica.

const entityId = 'john_doe';
const entityAttributes = {
  city: 'Bangalore',
  country: 'India',
};

const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
  • entityId: ID de la entidad. Será un identificador de serie relacionado con la entidad con la que se evalúa la característica. Por ejemplo, una entidad puede ser una instancia de una aplicación que se ejecuta en un dispositivo móvil, o un usuario que accede a la aplicación web. Para que cualquier entidad pueda interactuar con App Configuration, debe proporcionar un ID de entidad único.
  • entityAttributes: un objeto JSON que consta del nombre de atributo y sus valores que define la entidad especificada. Este es un parámetro opcional si el distintivo de característica no está configurado con ninguna definición de destino. Si el destino está configurado, se debe proporcionar entityAttributes para la evaluación de reglas. Un atributo es un parámetro que se utiliza para definir un segmento. El SDK utiliza los valores de atributo para determinar si la entidad especificada satisface las reglas de destino y devuelve el valor de distintivo de característica adecuado.

Enviar métricas personalizadas

Registre métricas personalizadas para utilizarlas en experimentos mediante la función de seguimiento.

appConfigClient.track(eventKey, entityId)

donde

  • eventKey: La clave de evento para la métrica asociada con el experimento en ejecución. La clave de evento en su métrica y la clave de evento en su código deben coincidir exactamente.

Obtener una única propiedad

const property = appConfigClient.getProperty('propertyId'); // throws error incase the propertyId is invalid or doesn't exist
console.log(`Property Name ${property.getPropertyName()} `);
console.log(`Property Id ${property.getPropertyId()} `);
console.log(`Property Type ${property.getPropertyDataType()} `);

Obtener todas las propiedades

const properties = appConfigClient.getProperties();
const property = properties['propertyId'];

if (property !== undefined) {
  console.log(`Property Name ${property.getPropertyName()} `);
  console.log(`Property Id ${property.getPropertyId()} `);
  console.log(`Property Type ${property.getPropertyDataType()} `);
}

Evaluar una propiedad

Utilice el método property.getCurrentValue(entityId, entityAttributes) para evaluar el valor de la propiedad. Este método devuelve el valor de propiedad predeterminado o su valor alterado temporalmente basándose en la evaluación. El tipo de datos del valor devuelto coincide con el de la propiedad.

const entityId = 'john_doe';
const entityAttributes = {
  city: 'Bangalore',
  country: 'India',
};

const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
  • entityId: ID de la entidad. Será un identificador de serie relacionado con la entidad con la que se evalúa la propiedad. Por ejemplo, una entidad puede ser una instancia de una aplicación que se ejecuta en un dispositivo móvil, o un usuario que accede a la aplicación web. Para que cualquier entidad pueda interactuar con App Configuration, debe proporcionar un ID de entidad único.
  • entityAttributes: un objeto JSON que consta del nombre de atributo y sus valores que define la entidad especificada. Este es un parámetro opcional si la propiedad no está configurada con ninguna definición de destino. Si el destino está configurado, se debe proporcionar entityAttributes para la evaluación de reglas. Un atributo es un parámetro que se utiliza para definir un segmento. El SDK utiliza los valores de atributo para determinar si la entidad especificada cumple las reglas de destino y devuelve el valor de propiedad adecuado.

Registro

Establece el nivel de registro a uno de 'debug' | 'info' | 'warning' | 'error'. El nivel de registro por defecto es info.

appConfigClient.setLogLevel('debug');

Tipos de datos soportados

El servicio App Configuration permite configurar el distintivo de característica y las propiedades en los siguientes tipos de datos: Booleano, Numérico, Serie. El tipo de datos Serie puede tener el formato de una serie de texto, JSON o YAML. El SDK procesa cada como se muestra en la siguiente tabla.

Tabla de vista
Valor de característica o propiedad DataType DataFormat Tipo de datos devueltos
por getCurrentValue()
Ejemplo de salida
true BOOLEAN no aplicable boolean true
25 NUMERIC no aplicable number 25
"a string text" SERIE TEXTO string a string text
{
"firefox": {
"name": "Firefox",
"pref_url": "about:config"
}
}
SERIE JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}}
men:
- John Smith
- Bill Jones
women:
- Mary Smith
- Susan Williams
SERIE YAML string

`"men:

  • John Smith
  • Bill Jones
    women:
  • Mary Smith
  • Susan Williams"`
Uso del indicador de función Ejemplo
const feature = appConfigClient.getFeature('json-feature');
feature.getFeatureDataType(); // STRING
feature.getFeatureDataFormat(); // JSON

// Example (traversing the returned JSON)
let result = feature.getCurrentValue(entityId, entityAttributes);
console.log(result.key) // prints the value of the key

const feature = appConfigClient.getFeature('yaml-feature');
feature.getFeatureDataType(); // STRING
feature.getFeatureDataFormat(); // YAML
feature.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check the table)
Ejemplo de uso de propiedad
const property = appConfigClient.getProperty('json-property');
property.getPropertyDataType(); // STRING
property.getPropertyDataFormat(); // JSON

// Example (traversing the returned JSON)
let result = property.getCurrentValue(entityId, entityAttributes);
console.log(result.key) // prints the value of the key

const property = appConfigClient.getProperty('yaml-property');
property.getPropertyDataType(); // STRING
property.getPropertyDataFormat(); // YAML
property.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check the table)

Establecer un receptor para los cambios de datos de características y propiedades

El SDK proporciona un mecanismo basado en eventos para notificarle en tiempo real cuando cambia la configuración de un indicador o propiedad. Puedes escuchar el evento ' configurationUpdate ' usando el mismo appConfigClient.

appConfigClient.emitter.on('configurationUpdate', () => {
  // **add your code**
  // To find the effect of any configuration changes, you can call the feature or property related methods

  // feature = appConfigClient.getFeature('online-check-in');
  // newValue = feature.getCurrentValue(entityId, entityAttributes);
});

Ejemplos

Pruebe esta aplicación de ejemplo en la carpeta examples para aprender más sobre la evaluación de características y propiedades.

Licencia

Este proyecto se publica bajo la licencia Apache 2.0. El texto completo de la licencia puede encontrarse en LICENCIA