SDK client App Configuration JavaScript

Per migliorare la sicurezza delle applicazioni che utilizzano il 'ibm-appconfiguration-js-client-sdk, si raccomanda vivamente di utilizzare una APIKey criptata al posto della APIKey semplice nel metodo init. Questa modifica è fondamentale per evitare l'esposizione di credenziali sensibili quando gli utenti ispezionano l'applicazione web. Se si utilizza già una APIKey semplice, aggiornare l'applicazione per generare e utilizzare la APIKey crittografata secondo i passaggi indicati qui.

Panoramica

IBM Cloud App Configuration L'SDK del client JavaScript viene utilizzato per eseguire la valutazione dei flag delle funzionalità e delle proprietà nelle applicazioni web e per tracciare metriche personalizzate per la sperimentazione in base alla configurazione del servizio IBM Cloud App Configuration.

IBM Cloud App Configuration è un servizio centralizzato per la gestione e la configurazione di funzionalità su IBM Cloud per l'uso con applicazioni web e mobili, microservizi e ambienti distribuiti ambienti distribuiti.

Strumentate le vostre applicazioni web con il App Configuration JavaScript Client SDK e utilizzare la dashboard, la CLI o l'API di App Configuration per definire i flag o le proprietà delle funzioni, organizzate in raccolte e mirate ai segmenti. Attivare gli stati dei flag delle funzioni nel per attivare o disattivare le funzioni nell'applicazione o nell'ambiente, quando necessario. Eseguite esperimenti e misurate l'effetto dei flag delle funzionalità sugli utenti finali tracciando metriche personalizzate. È anche possibile gestire le proprietà delle applicazioni distribuite in modo centralizzato.

Compatibilità con i browser: L'SDK è supportato da tutti i principali browser. Il browser deve supportare l'API 'fetch().

Integrazione di SDK client per JavaScript

Installazione

Installa l'SDK. Usare il seguente codice per installare come modulo dal gestore di pacchetti.

npm install ibm-appconfiguration-js-client-sdk

È possibile importare l'SDK nel tag script facendo riferimento a un sito ospitato sul backend o a un CDN, come segue:

Esempio:

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

Inizializza l'SDK

Inizializza l'sdk per connetterti con la tua istanza del servizio 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);
}

Nel frammento precedente, la funzione asincrona initialiseAppConfig() restituirà un oggetto Promise<void> che si risolve quando le configurazioni vengono recuperate correttamente. Altrimenti, lancia un errore se non ha successo.

Si prevede che l'inizializzazione venga effettuata una sola volta.

Dopo che l'SDK è stato inizializzato con successo, il flag e le proprietà della funzione possono essere recuperati utilizzando l' appConfigClient, come mostrato nel seguente frammento di codice.

Espandere per visualizzare lo snippet di esempio
// 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);

dove,

  • regione: Nome della regione in cui viene creata l'istanza del servizio App Configuration. Vedere l'elenco delle località supportate qui. Ad esempio: us-south, au-syd ecc.
  • guid: ID istanza del servizio App Configuration. Si ottiene dalla sezione credenziali di servizio della dashboard App Configuration.
  • apikey: la APIKey crittografata generata come descritto qui.
  • collectionId: ID della raccolta creata nell'istanza del servizio App Configuration nella sezione Collections.
  • environmentId: ID dell'ambiente creato nell'istanza del servizio App Configuration nella sezione Environments.

Utilizzare sempre l'APIKey crittografata per evitare di esporre informazioni sensibili.
Assicurarsi di creare le credenziali del servizio con il ruolo 'Client SDK, che ha le autorizzazioni di accesso minime adatte all'uso in applicazioni basate su browser.

Esempi per l'uso di API correlate a funzioni e proprietà

Vedi i seguenti esempi per l'utilizzo delle API correlate alla funzione.

Ottieni funzione singola

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

Ottieni tutte le funzioni

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

Valuta una funzione

Utilizzare il metodo 'feature.getCurrentValue(entityId, entityAttributes) per valutare il valore del flag della caratteristica. Questo metodo restituisce uno dei valori Abilitato / Disabilitato / Sovrascritto basato sulla valutazione. Il tipo di dati del valore restituito corrisponde a quello dell'indicatore funzione.

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

const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
  • entityId: ID dell'entità. Questo sarà un identificativo stringa relativo all'entità rispetto alla quale viene valutata la funzione. Ad esempio, un'entità può essere un'istanza di un'applicazione eseguita su un dispositivo mobile o un utente che accede all'applicazione web. Affinché qualsiasi entità interagisca con App Configuration, deve fornire un ID entità univoco.
  • entityAttributes: un oggetto JSON costituito dal nome attributo e dai relativi valori che definiscono l'entità specificata. Questo è un parametro facoltativo se l'indicatore della funzione non è configurato con alcuna definizione di destinazione. Se la destinazione è configurata, entityAttributes deve essere fornito per la valutazione della regola. Un attributo è un parametro utilizzato per definire un segmento. L'SDK utilizza i valori degli attributi per determinare se l'entità specificata soddisfa le regole di destinazione e restituisce il valore dell'indicatore della funzione appropriato.

Inviare metriche personalizzate

Registrate metriche personalizzate da utilizzare per la sperimentazione utilizzando la funzione di tracciamento.

appConfigClient.track(eventKey, entityId)

dove

  • eventKey: la chiave dell'evento per la metrica associata all'esperimento in corso. La chiave dell'evento nella metrica e la chiave dell'evento nel codice devono corrispondere esattamente.

Ottieni singola propriet ...

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

Ottieni tutte le proprietà

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

Valuta una proprietà

Utilizzare il metodo property.getCurrentValue(entityId, entityAttributes) per valutare il valore della proprietà. Questo metodo restituisce il valore della proprietà predefinito o il relativo valore sovrascritto in base alla valutazione. Il tipo di dati del valore restituito corrisponde a quello della proprietà.

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

const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
  • entityId: ID dell'entità. Questo sarà un identificativo stringa relativo all'entità rispetto alla quale viene valutata la proprietà. Ad esempio, un'entità può essere un'istanza di un'applicazione eseguita su un dispositivo mobile o un utente che accede all'applicazione web. Affinché qualsiasi entità interagisca con App Configuration, deve fornire un ID entità univoco.
  • entityAttributes: un oggetto JSON costituito dal nome attributo e dai relativi valori che definiscono l'entità specificata. Questo è un parametro facoltativo se la proprietà non è configurata con alcuna definizione di destinazione. Se la destinazione è configurata, entityAttributes deve essere fornito per la valutazione della regola. Un attributo è un parametro utilizzato per definire un segmento. L'SDK utilizza i valori degli attributi per stabilire se l'entità specificata soddisfa le regole di destinazione e restituisce il valore della proprietà appropriato.

Registrazione

Impostare il livello di registrazione su uno dei seguenti: "debug" | "info" | "warning" | "error". Il livello di registrazione predefinito è info.

appConfigClient.setLogLevel('debug');

Tipi di dati supportati

Il servizio App Configuration consente di configurare il flag della funzione e le proprietà nei seguenti tipi di dati: Booleano, Numerico, stringa. Il tipo di dati String può avere il formato di una stringa di testo, JSON o YAML. L'SDK elabora ogni formato di conseguenza, come mostrato nella tabella seguente.

Visualizza tabella
Valore della caratteristica o della proprietà DataType DataFormat Tipo di dati restituiti '
da 'getCurrentValue()
Output di esempio
true BOOLEAN non applicabile boolean true
25 NUMERIC non applicabile number 25
"una stringa di testo" STRINGA TESTO string a string text
{
"firefox": {
"name":Firefox",
"pref_url": "about:config"
}
}
STRINGA JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}}
uomini:
- John Smith
- Bill Jones
donne:
- Mary Smith
- Susan Williams
STRINGA YAML string

`"men:

  • John Smith
  • Bill Jones
    women:
  • Mary Smith
  • Susan Williams"`
Utilizzo del flag di funzionalità Esempio
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)
Esempio di utilizzo della proprietà
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)

Impostare un ascoltatore per le modifiche ai dati delle caratteristiche e delle proprietà

L'SDK fornisce un meccanismo basato sugli eventi per notificare in tempo reale le modifiche alla configurazione dei flag delle funzioni o delle proprietà. È possibile ascoltare l'evento 'configurationUpdate utilizzando lo stesso 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);
});

Esempi

Provate questa applicazione di esempio nella cartella esempi per saperne di più sulla valutazione delle caratteristiche e delle proprietà.

Licenza

Questo progetto è rilasciato sotto la licenza Apache 2.0. Il testo completo della licenza si trova in LICENZA