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 |
{ |
SERIE | JSON | JSON object |
{"firefox":{"name":"Firefox","pref_url":"about:config"}} |
men: |
SERIE | YAML | string |
`"men:
|
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