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-syd etc.
  • 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)

  • 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
{
"firefox": {
"name": "Firefox",
"pref_url": "about:config"
}
}
CHAÎNE JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}}
Hommes :
- John Smith
- Bill Jones
femmes :
- Mary Smith
- Susan Williams
CHAÎNE YAML string

`"men:

  • John Smith
  • Bill Jones
    women:
  • Mary Smith
  • Susan Williams"`
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