App Configuration JavaScript-Client-SDK

Um die Sicherheit Ihrer Anwendungen, die den " ibm-appconfiguration-js-client-sdk verwenden, zu erhöhen, wird dringend empfohlen, einen verschlüsselten APIKey anstelle des einfachen APIKey in der init-Methode zu verwenden. Diese Änderung ist wichtig, um zu verhindern, dass vertrauliche Anmeldeinformationen preisgegeben werden, wenn Benutzer Ihre Webanwendung inspizieren. Wenn Sie bereits einen einfachen APIKey verwenden, aktualisieren Sie bitte Ihre Anwendung, um den verschlüsselten APIKey zu generieren und zu verwenden, wie in den hier genannten Schritten beschrieben.

Übersicht

IBM Cloud App Configuration JavaScript Client SDK wird verwendet, um Feature-Flags und Eigenschaftsauswertungen in Webanwendungen durchzuführen und benutzerdefinierte Metriken für Experimente zu verfolgen, die auf der Konfiguration des IBM Cloud App Configuration Dienst.

IBM Cloud App Configuration ist ein zentraler Dienst zur Verwaltung und Konfiguration von Funktionen auf IBM Cloud für den Einsatz mit Web- und mobilen Anwendungen, Microservices und verteilten umgebungen.

Instrumentieren Sie Ihre Webanwendungen mit App Configuration JavaScript Client SDK, und verwenden Sie das App Configuration Dashboard, CLI oder API, um Feature-Flags oder Eigenschaften zu definieren, die in Sammlungen organisiert und auf Segmente ausgerichtet sind. Schalten Sie den Status der Funktionskennzeichen in in der Cloud, um Funktionen in Ihrer Anwendung oder Umgebung bei Bedarf zu aktivieren oder zu deaktivieren. Führen Sie Experimente durch und messen Sie die Wirkung von Feature Flags auf Endbenutzer, indem Sie benutzerdefinierte Metriken verfolgen. Sie können die Eigenschaften für verteilte Anwendungen auch zentral verwalten.

Browser-Kompatibilität: Das SDK wird von allen gängigen Browsern unterstützt. Der Browser sollte ' fetch() API Unterstützung haben.

Client-SDK für JavaScript integrieren

Installation

Installieren Sie das SDK. Verwenden Sie den folgenden Code, um ein Modul über den Paketmanager zu installieren.

npm install ibm-appconfiguration-js-client-sdk

Sie können das SDK in das Skript-Tag importieren, indem Sie es entweder von einer gehosteten Site in Ihrem Backend oder von einem CDN wie folgt referenzieren:

Beispiel:

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

SDK initialisieren

Initialisieren Sie das SDK, um eine Verbindung zu Ihrer App Configuration-Serviceinstanz herzustellen.

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);
}

Im vorherigen Ausschnitt gibt die asynchrone Funktion initialiseAppConfig() eine Promise<void> zurück, die aufgelöst wird, wenn die Konfigurationen erfolgreich abgerufen wurden. Andernfalls wird ein Fehler ausgegeben, wenn die Suche nicht erfolgreich war.

Es wird erwartet, dass die Initialisierung nur einmal durchgeführt werden muss.

Nach erfolgreicher Initialisierung des SDK können die Merkmalskennzeichnung und die Eigenschaften mithilfe von appConfigClient abgerufen werden, wie im folgenden Codeausschnitt dargestellt.

Erweitern, um das Beispiel-Snippet zu sehen
// 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);

Dabei gilt Folgendes:

  • region: Name der Region, in der die App Configuration Dienstinstanz erstellt wird. Eine Liste der unterstützten Standorte finden Sie hier. Zum Beispiel: us-south, au-syd usw.
  • guid: Instanz-ID des Dienstes App Configuration. Diese erhalten Sie im Abschnitt "Dienstanmeldeinformationen" des Dashboards App Configuration.
  • apikey: Der verschlüsselte APIKey, der wie hier beschrieben erzeugt wurde.
  • collectionId: ID der Sammlung, die in der Dienstinstanz App Configuration unter dem Abschnitt Sammlungen erstellt wurde.
  • environmentId: ID der Umgebung, die in der Dienstinstanz App Configuration unter dem Abschnitt Umgebungen erstellt wurde.

Verwenden Sie immer den verschlüsselten APIKey, um die Preisgabe sensibler Informationen zu vermeiden.
Stellen Sie sicher, dass Sie die Dienstanmeldeinformationen mit der Rolle " Client SDK erstellen, da diese die minimalen Zugriffsrechte hat, die für die Verwendung in browserbasierten Anwendungen geeignet sind.

Beispiele für die Verwendung von Funktionen und eigenschaftsbezogenen APIs

Sehen Sie sich die folgenden Beispiele für die Verwendung der funktionsbezogenen APIs an.

Einzelnes Feature abrufen

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()} `);

Alle Features abrufen

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()} `);
}

Feature bewerten

Verwenden Sie die Methode feature.getCurrentValue(entityId, entityAttributes), um den Wert des Merkmals auszuwerten. Diese Methode gibt basierend auf der Auswertung einen der Werte "Aktiviert/Inaktiviert/Überschrieben" zurück. Der Datentyp des zurückgegebenen Werts stimmt mit dem des Feature-Flags überein.

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

const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
  • entityId: ID der Entität. Dies ist eine Zeichenfolgekennung, die sich auf die Entität bezieht, für die das Feature ausgewertet wird. Eine Entität kann zum Beispiel eine Instanz einer Anwendung sein, die auf einem mobilen Gerät läuft, oder ein Benutzer, der auf die Webanwendung zugreift. Damit eine Entität mit App Configuration interagieren kann, muss sie eine eindeutige Entitäts-ID angeben.
  • entityAttributes: Ein JSON-Objekt, das aus dem Attributnamen und ihren Werten besteht, die die angegebene Entität definieren. Dies ist ein optionaler Parameter, wenn das Feature-Flag nicht mit einer Zieldefinition konfiguriert ist. Wenn das Ziel konfiguriert ist, muss entityAttributes für die Regelauswertung angegeben werden. Ein Attribut ist ein Parameter, der zum Definieren eines Segments verwendet wird. Das SDK verwendet die Attributwerte, um festzustellen, ob die angegebene Entität die Zielregeln erfüllt, und gibt den entsprechenden Feature-Flag-Wert zurück.

Benutzerdefinierte Metriken senden

Zeichnen Sie mit der Tracking-Funktion benutzerdefinierte Metriken auf, um sie für Experimente zu verwenden.

appConfigClient.track(eventKey, entityId)

wo

  • eventKey: Der Ereignisschlüssel für die mit dem laufenden Experiment verbundene Metrik. Der Ereignisschlüssel in Ihrer Metrik und der Ereignisschlüssel in Ihrem Code müssen genau übereinstimmen.

Einzeleigenschaft abrufen

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()} `);

Alle Eigenschaften abrufen

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()} `);
}

Eigenschaft auswerten

Verwenden Sie die Methode property.getCurrentValue(entityId, entityAttributes), um den Wert der Immobilie zu ermitteln. Diese Methode gibt den Standardeigenschaftswert oder den überschriebenen Wert basierend auf der Auswertung zurück. Der Datentyp des zurückgegebenen Werts entspricht dem des Merkmals.

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

const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
  • entityId: ID der Entität. Dies ist eine Zeichenfolgekennung, die sich auf die Entität bezieht, für die die Eigenschaft ausgewertet wird. Eine Entität kann zum Beispiel eine Instanz einer Anwendung sein, die auf einem mobilen Gerät läuft, oder ein Benutzer, der auf die Webanwendung zugreift. Damit eine Entität mit App Configuration interagieren kann, muss sie eine eindeutige Entitäts-ID angeben.
  • entityAttributes: Ein JSON-Objekt, das aus dem Attributnamen und ihren Werten besteht, die die angegebene Entität definieren. Dies ist ein optionaler Parameter, wenn die Eigenschaft nicht mit einer Zieldefinition konfiguriert ist. Wenn das Ziel konfiguriert ist, muss entityAttributes für die Regelauswertung angegeben werden. Ein Attribut ist ein Parameter, der zum Definieren eines Segments verwendet wird. Das SDK verwendet die Attributwerte, um zu bestimmen, ob die angegebene Entität die Zielregeln erfüllt, und gibt den entsprechenden Eigenschaftswert zurück.

Protokollierung

Setzen Sie die Protokollierungsstufe auf einen der Werte 'debug' | 'info' | 'warning' | 'error'. Die Standardprotokollierungsstufe ist info.

appConfigClient.setLogLevel('debug');

Unterstützte Datentypen

Der App Configuration-Service ermöglicht die Konfiguration des Feature-Flags und der Eigenschaften in den folgenden Datentypen: Boolesch, Numerisch, Zeichenfolge. Der Zeichenfolgedatentyp kann das Format einer Textzeichenfolge, JSON oder YAML haben. Das SDK verarbeitet jedes format entsprechend, wie in der folgenden Tabelle dargestellt.

Tabelle anzeigen
Feature oder Eigenschaftswert DataType DataFormat Typ der Daten, die
von getCurrentValue() zurückgegeben werden
Beispielausgabe
true BOOLEAN nicht zutreffend boolean true
25 NUMERISCH nicht zutreffend number 25
„ein Zeichenfolgetext“ ZEICHENFOLGE TEXT string a string text
{
„Firefox“: {
„name“: „Firefox“,
„pref_url“: „about:config“
}
}
ZEICHENFOLGE JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}}
Männer:
– John Smith
– Bill Jones
Frauen:
– Mary Smith
– Susan Williams
ZEICHENFOLGE YAML string

`"men:

  • John Smith
  • Bill Jones
    women:
  • Mary Smith
  • Susan Williams"`
Verwendung des Merkmals Beispiel
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)
Verwendungsbeispiel für Eigenschaften
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)

Listener für Änderungen von Merkmalen und Eigenschaftsdaten festlegen

Das SDK bietet einen ereignisbasierten Mechanismus, um Sie in Echtzeit zu benachrichtigen, wenn sich die Konfiguration eines Feature-Flags oder einer Eigenschaft ändert. Sie können das Ereignis " configurationUpdate mit demselben appConfigClient abhören.

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);
});

Beispiele

Probieren Sie diese Beispielanwendung im Ordner examples um mehr über die Bewertung von Merkmalen und Eigenschaften zu erfahren.

Lizenz

Dieses Projekt wird unter der Apache 2.0 Lizenz veröffentlicht. Der vollständige Text der Lizenz ist zu finden unter LICENSE