App Configuration JavaScript
Pour renforcer la sécurité de vos applications utilisant le " ibm-appconfiguration-js-client-sdk, il est fortement recommandé d'utiliser un APIKey crypté au lieu de l'APIKey simple dans la méthode init. Cette
modification est essentielle pour éviter l'exposition d'informations d'identification sensibles lorsque les utilisateurs inspectent votre application web. Si vous utilisez déjà une APIKey ordinaire, veuillez mettre à jour votre application afin
de générer et d'utiliser l'APIKey cryptée en suivant les étapes mentionnées ici.
Présentation
IBM Cloud App Configuration JavaScript Client SDK est utilisé pour effectuer l'évaluation des caractéristiques et des propriétés dans les applications web et suivre les métriques personnalisées pour l'expérimentation en fonction de la configuration sur IBM Cloud {{site {{site.data.keyword.appconfig_short}}
IBM Cloud App Configuration est un service centralisé de gestion et de configuration des fonctionnalités sur IBM Cloud pour les applications web et mobiles, les microservices et les environnements distribués distribués.
Instrumentez vos applications web avec App Configuration Et utilisez le tableau de bord App Configuration, le CLI ou l'API pour définir des drapeaux ou des propriétés de fonctionnalités, organisés en collections et ciblés sur des segments. Basculer les états des drapeaux de fonctionnalités dans dans le nuage pour activer ou désactiver des fonctionnalités dans votre application ou votre environnement, le cas échéant. Réalisez des expériences et mesurez l'effet des drapeaux sur les utilisateurs finaux en suivant des paramètres personnalisés. Vous pouvez également gérer les propriétés des applications réparties de manière centralisée.
Compatibilité avec les navigateurs : Le SDK est pris en charge par tous les principaux navigateurs. Le navigateur doit prendre en charge l'API " fetch()
Intégration du SDK client pour JavaScript
Installation
Installez le kit de développement de logiciels (SDK). Utilisez le code suivant pour l'installer en tant que module à partir du gestionnaire de paquets.
npm install ibm-appconfiguration-js-client-sdk
Vous pouvez importer le SDK dans la balise de script en le référençant à partir d'un site hébergé sur votre backend ou à partir d'un CDN comme suit :
Exemple :
<script type="text/javascript" src="https://unpkg.com/ibm-appconfiguration-js-client-sdk/dist/appconfiguration.js"></script>
Initialisation du logiciel SDK
Initialisez le sdk pour vous connecter à votre instance de service 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);
}
Dans l'extrait précédent, la fonction asynchrone initialiseAppConfig() renvoie un objet Promise<void> qui se résout lorsque les configurations sont récupérées avec succès. Dans le cas contraire, une erreur est
générée si l'opération n'aboutit pas.
Il est prévu que l'initialisation se fasse " une seule fois.
Une fois le SDK initialisé avec succès, l'indicateur de fonctionnalité et les propriétés peuvent être récupérés à l'aide de l' appConfigClient, comme indiqué dans l'extrait de code suivant.
Développez pour voir l'exemple d'extrait
// 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);
Où,
- région: Nom de la région où l'instance de service App Configuration est créée. Voir la liste des lieux pris en charge ici. Par exemple :
us-south,au-sydetc. - guid: Instance ID du service App Configuration. Vous pouvez l'obtenir dans la section "Service credentials" du tableau de bord App Configuration.
- apikey: La clé APIK cryptée générée comme décrit ici.
- collectionId: ID de la collection créée dans l'instance de service App Configuration dans la section Collections.
- environmentId: ID de l'environnement créé dans l'instance de service App Configuration dans la section Environnements.
Utilisez toujours la clé APIK cryptée pour éviter d'exposer des informations sensibles.
Veillez à créer les informations d'identification du service avec le rôle " Client SDK, car il dispose des autorisations
d'accès minimales adaptées à une utilisation dans des applications basées sur un navigateur.
Exemples d'utilisation des API liées aux fonctions et aux propriétés
Consultez les exemples suivants pour utiliser les API liées aux fonctions.
Extraction d'une fonctionnalité
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()} `);
Extraction de toutes les fonctionnalités
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()} `);
}
Evaluation d'une fonction
Utilisez la méthode feature.getCurrentValue(entityId, entityAttributes) pour évaluer la valeur de l'indicateur de caractéristique. Cette méthode renvoie l'une des valeurs Activé / Désactivé / Remplace en fonction de l'évaluation.
Le type de données de la valeur renvoyée correspond à celui de l'indicateur de fonction.
const entityId = 'john_doe';
const entityAttributes = {
city: 'Bangalore',
country: 'India',
};
const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
entityId: ID de l'entité. Il s'agit d'un identificateur de chaîne lié à l'entité par rapport à laquelle la fonction est évaluée. Par exemple, une entité peut être une instance d'une application qui s'exécute sur un appareil mobile, ou un utilisateur qui accède à l'application web. Pour qu'une entité puisse interagir avec App Configuration, elle doit fournir un identifiant unique.entityAttributes: objet JSON composé du nom d'attribut et de ses valeurs qui définit l'entité spécifiée. Il s'agit d'un paramètre facultatif si l'indicateur de fonction n'est pas configuré avec une définition de ciblage. Si le ciblage est configuré, entityAttributes doit être fourni pour l'évaluation de la règle. Un attribut est un paramètre utilisé pour définir un segment. Le SDK utilise les valeurs d'attribut pour déterminer si l'entité spécifiée satisfait aux règles de ciblage et renvoie la valeur d'indicateur de fonction appropriée.
Envoyer des mesures personnalisées
Enregistrez des mesures personnalisées à utiliser dans le cadre d'expériences à l'aide de la fonction de suivi.
appConfigClient.track(eventKey, entityId)
où
eventKey: clé de l'événement pour la mesure associée à l'expérience en cours. La clé d'événement dans votre métrique et la clé d'événement dans votre code doivent correspondre exactement.
Extraction d'une propriété
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()} `);
Extraction de toutes les propriétés
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()} `);
}
Evaluer une propriété
Utilisez la méthode property.getCurrentValue(entityId, entityAttributes) pour évaluer la valeur du bien. Cette méthode renvoie la valeur de propriété par défaut ou sa valeur remplacée en fonction de l'évaluation. Le type de
données de la valeur renvoyée correspond à celui de la propriété.
const entityId = 'john_doe';
const entityAttributes = {
city: 'Bangalore',
country: 'India',
};
const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
entityId: ID de l'entité. Il s'agit d'un identificateur de chaîne lié à l'entité par rapport à laquelle la propriété est évaluée. Par exemple, une entité peut être une instance d'une application qui s'exécute sur un appareil mobile, ou un utilisateur qui accède à l'application web. Pour qu'une entité puisse interagir avec App Configuration, elle doit fournir un identifiant unique.entityAttributes: objet JSON composé du nom d'attribut et de ses valeurs qui définit l'entité spécifiée. Il s'agit d'un paramètre facultatif si la propriété n'est configurée avec aucune définition de ciblage. Si le ciblage est configuré, entityAttributes doit être fourni pour l'évaluation de la règle. Un attribut est un paramètre utilisé pour définir un segment. Le SDK utilise les valeurs d'attribut pour déterminer si l'entité spécifiée satisfait aux règles de ciblage et renvoie la valeur de propriété appropriée.
Journalisation
Définir le niveau de journalisation à l'un des niveaux suivants : 'debug' | 'info' | 'warning' | 'error'. Le niveau de journalisation par défaut est info.
appConfigClient.setLogLevel('debug');
Types de données pris en charge
Le service App Configuration permet de configurer l'indicateur de fonction et les propriétés dans les types de données suivants : Booléen, Numérique, Chaîne. Le type de données Chaîne peut être le format d'une chaîne de texte, JSON ou YAML. Le SDK traite chaque format en conséquence, comme indiqué dans le tableau suivant.
Voir la table
| Valeur de la fonction ou de la propriété | DataType | DataFormat | Type de données renvoyées par getCurrentValue() |
Exemple de sortie |
|---|---|---|---|---|
true |
BOOLEAN | non applicable | boolean |
true |
25 |
NUMERIQUE | non applicable | number |
25 |
| " Un texte de chaîne " | CHAÎNE | TEXTE | string |
a string text |
{ |
CHAÎNE | JSON | JSON object |
{"firefox":{"name":"Firefox","pref_url":"about:config"}} |
Hommes : |
CHAÎNE | YAML | string |
`"men:
|
Utilisation de l'indicateur de fonctionnalité Exemple
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)
Exemple d'utilisation de propriété
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)
Définir un récepteur pour les modifications des données relatives aux caractéristiques et aux propriétés
Le SDK fournit un mécanisme basé sur les événements pour vous informer en temps réel lorsque la configuration d'un indicateur ou d'une propriété change. Vous pouvez écouter l'événement " configurationUpdate en utilisant le
même 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);
});
Exemples
Essayez cet exemple d'application dans le dossier examples pour en savoir plus sur l'évaluation des caractéristiques et des propriétés.
Licence
Ce projet est publié sous la licence Apache 2.0 Le texte intégral de la licence se trouve dans LICENCE