App Configuration JavaScript client SDK

App Configuration service provides SDK to integrate with your browser applications.

Integrating client SDK for JavaScript

App Configuration JavaScript client SDK can be used with all the major browsers. You can evaluate the values of your feature flag and property by integrating the App Configuration SDK.

Install the SDK. Use the following code to install the SDK as a module from package manager.
```
npm install ibm-appconfiguration-js-client-sdk
```

You can import the SDK into the script tag either by referencing it from a hosted site on your backend or from a CDN as follows:

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

Initialize the sdk to connect with your App Configuration service instance.
```
const region = AppConfiguration.REGION_US_SOUTH;
const guid = '<guid>';
const apikey = '<apikey>';
const collectionId = '<collectionId>';
const environmentId = '<environmentId>';

const client = AppConfiguration.getInstance();
client.init(region, guid, apikey);
await client.setContext(collectionId, environmentId);
```
The init() and setContext() are the initialisation methods and should be invoked only once using appConfigClient. The appConfigClient, once initialised, can be obtained across modules using AppConfiguration.getInstance().

Where:
- region: Region where the service instance is created. Use AppConfiguration.REGION_US_SOUTH for Dallas, AppConfiguration.REGION_US_EAST for Washington DC, AppConfiguration.REGION_EU_GB for London, AppConfiguration.REGION_EU_DE for Frankfurt and AppConfiguration.REGION_AU_SYD for Sydney.
- guid: Instance ID of the App Configuration service. Get it from the service credentials section of the App Configuration service dashboard.
- apikey: API key of the App Configuration service. Get it from the service credentials section of the App Configuration service dashboard.
- collectionId: ID of the collection created in App Configuration service instance under the Collections section.
- environmentId: ID of the environment created in App Configuration service instance under the Environments section.

Ensure to create the service credentials of the role Client SDK for using with the JavaScript SDK. API key of the Client SDK role has minimal access permissions that are suitable to use in browser based applications.

Examples for using feature and property-related APIs

See the following examples for using the feature-related APIs.

Get single feature

const feature = client.getFeature('feature_id')

if(feature) {

   console.log('data', feature);
   console.log(`Feature Name ${feature.getFeatureName()} `);
   console.log(`Feature Id ${feature.getFeatureId()} `);
   console.log(`Feature Type ${feature.getFeatureDataType()} `);
   console.log(`Feature is enabled ${feature.isEnabled()} `);
}

Get all features

const features = client.getFeatures();

const feature = features["feature_id"];

if(feature) {
   console.log(`Feature Name ${feature.getFeatureName()}`);
   console.log(`Feature Id ${feature.getFeatureId()}`);
   console.log(`Feature Type ${feature.getFeatureDataType()}`);
   console.log(`Feature is enabled ${feature.isEnabled()}`);
}

Evaluate a feature

You can use the feature.getCurrentValue(entityId, entityAttributes) method to evaluate the value of the feature flag. This method returns one of the Enabled/Disabled/Overridden value based on the evaluation. The data type of returned value matches that of feature flag. Pass a unique entityId as the parameter to perform the feature flag evaluation.

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

const featureValue = feature.getCurrentValue(entityId, entityAttributes);

Where:

entityId: Id of the Entity. This will be a string identifier related to the Entity against which the feature is evaluated. For any entity to interact with App Configuration, it must provide a unique entity ID.
entityAttributes: A JSON object consisting of the attribute name and their values that defines the specified entity. This is an optional parameter if the feature flag is not configured with any targeting definition. If the targeting is configured, then entityAttributes should be provided for the rule evaluation. An attribute is a parameter that is used to define a segment. The SDK uses the attribute values to determine if the specified entity satisfies the targeting rules, and returns the appropriate feature flag value.

Get single property

const property = client.getProperty('property_id')

if(property) {
   console.log('data', property);
   console.log(`Property Name ${property.getPropertyName()}`);
   console.log(`Property Id ${property.getPropertyId()}`);
   console.log(`Property Type ${property.getPropertyDataType()}`);
}

Get all properties

const properties = client.getProperties();

const property = properties["property_id"];

if(property) {
   console.log(`Property Name ${property.getPropertyName()}`);
   console.log(`Property Id ${property.getPropertyId()}`);
   console.log(`Property Type ${property.getPropertyDataType()}`);
}

Evaluate a property

Use the property.getCurrentValue(entityId, entityAttributes) method to evaluate the value of the property. This method returns the default property value or its overridden value based on the evaluation. The data type of returned value matches that of property.

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

const propertyValue = property.getCurrentValue(entityId, entityAttributes);

Where:

entityId: Id of the Entity. This will be a string identifier related to the Entity against which the property is evaluated. For any entity to interact with App Configuration, it must provide a unique entity ID.
entityAttributes: A JSON object consisting of the attribute name and their values that defines the specified entity. This is an optional parameter if the property is not configured with any targeting definition. If the targeting is configured, then entityAttributes should be provided for the rule evaluation. An attribute is a parameter that is used to define a segment. The SDK uses the attribute values to determine if the specified entity satisfies the targeting rules, and returns the appropriate property value.

Supported data types

You can configure feature flags and properties with App Configuration, supporting the following data types: Boolean, Numeric, and String. The String data type can be in the format of a text string, JSON, or YAML. The SDK processes each format as shown in the table.

Table 1. Example outputs
Feature or Property value	Data type	Data format	Type of data returned by `getCurrentValue()`	Example output
`true`	BOOLEAN	not applicable	`boolean`	`true`
`25`	NUMERIC	not applicable	`number`	`25`
"a string text"	STRING	TEXT	`string`	`a string text`
`{"firefox": {` `"name": "Firefox",` `"pref_url": "about:config"` }}	STRING	JSON	`org.json.JSONObject`	`{"firefox":{"name":"Firefox","pref_url":"about:config"}}`
`men:` `- John Smith` `- Bill Jones` `women:` `- Mary Smith` `- Susan Williams`	STRING	YAML	`java.lang.String`	`"men: John Smith Bill Jones\women: Mary Smith Susan Williams"`

Feature flag usage example

const feature = client.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 = client.getFeature('yaml-feature');
feature.getFeatureDataType(); // STRING
feature.getFeatureDataFormat(); // YAML
feature.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check above table)

Property usage example

const property = client.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 = client.getProperty('yaml-property');
property.getPropertyDataType(); // STRING
property.getPropertyDataFormat(); // YAML
property.getCurrentValue(entityId, entityAttributes); // returns the stringified yaml (check above table)

Listen to the feature or property changes

To listen to the data changes, add the following code in your application:

client.emitter.on('configurationUpdate', () => {
    // add your code
})