App Configuration JavaScript 用戶端 SDK

為了增強使用 ibm-appconfiguration-js-client-sdk 應用程式的安全性，強烈建議在 init 方法中使用加密的 APIKey 而不是普通的 APIKey。 此變更對於防止使用者檢查您的 Web 應用程式時敏感憑證暴露至關重要。 如果您已經在使用普通 APIKey，請更新您的應用程式以按照 此處 提到的步驟產生並使用加密的 APIKey。

概觀

IBM Cloud App Configuration JavaScript客戶端 SDK 用於在 Web 應用程式中執行功能標記和屬性評估，並根據IBM Cloud App Configuration服務上的配置追蹤實驗的自訂指標。

IBM Cloud App Configuration是 IBM Cloud 上的集中式功能管理和設定服務，用於網路和行動應用程序，微服務和分散式環境。

使用App Configuration JavaScript客戶端 SDK 檢測您的 Web 應用程序，並使用App Configuration儀表板、CLI 或API 定義功能標誌或屬性，將其組織成集合和針對細分市場。 在雲端切換功能標誌狀態 需要時，在雲端啟動或停用應用程式或環境中的功能。 運行實驗並透過追蹤自訂指標來衡量功能標記對最終用戶的影響。 您也可以集中管理分散式應用程式的屬性。

瀏覽器相容性：所有主要瀏覽器都支援該 SDK。 瀏覽器應具有 fetch() API 支援。

整合 Client SDK for JavaScript

安裝

安裝 SDK。 使用以下程式碼從套件管理器安裝為模組。

npm install ibm-appconfiguration-js-client-sdk

您可以透過從後端託管網站或 CDN 引用 SDK 將 SDK 匯入到腳本標記中，如下所示：

範例：

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

起始設定 SDK

起始設定 sdk 以使用 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);
}

在之前的片段中，當成功取得配置時，async 函式 initialiseAppConfig() 將傳回解譯的 Promise<void>。 否則，如果不成功則拋出錯誤。

預計初始化只進行一次。

SDK 成功初始化後，可使用 appConfigClient 擷取特徵旗標與屬性，如以下程式碼片段所示。

展開以查看範例片段 
// 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);

其中，

  • 區域：建立 App Configuration 服務實體的區域名稱。 請參閱 此處 的支援地點清單。 例如：- us-south, au-syd 等。
  • guid：App Configuration服務的實例 ID。 從App Configuration儀表板的服務憑證部分取得它。
  • apikey：按照 此處 所述產生的加密 APIKey。
  • collectionId：在 「集合」 部分下的App Configuration服務實例中建立的集合的 ID。
  • environmentId：在 「環境」 部分下的App Configuration服務實例中建立的環境的 ID。

始終使用加密的 APIKey 以避免洩漏敏感資訊。
確保使用 Client SDK 角色建立服務憑證，因為它具有適合在基於瀏覽器的應用程式中使用的最小存取權限。

使用特性及內容相關 API 的範例

請參閱下列範例，以瞭解如何使用特性相關 API。

取得單一特性

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

取得所有特性

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.getCurrentValue(entityId, entityAttributes) 方法來評估功能標誌的值。 此方法會根據評估傳回其中一個「已啟用/已停用/已置換」值。 回覆值的資料類型符合特性旗標的資料類型。

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

const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
  • entityId: 實體的 ID。 這將是與評估特性所依據的實體相關的字串 ID。 例如，實體可能是在行動裝置上執行的應用程式的實例，或是存取 Web 應用程式的使用者。 若要讓任何實體與 App Configuration互動，它必須提供唯一實體 ID。
  • entityAttributes: JSON 物件，由定義指定實體的屬性名稱及其值組成。 如果特性旗標未配置任何目標定義，則這是選用參數。 如果已配置目標，則應該提供 entityAttributes 以進行規則評估。 屬性是用來定義區段的參數。 SDK 使用屬性值來判斷指定的實體是否滿足目標規則，並傳回適當的特性旗標值。

發送自訂指標

使用追蹤功能記錄要在實驗中使用的自訂指標。

appConfigClient.track(eventKey, entityId)

其中

  • eventKey：與正在運行的實驗關聯的指標的事件鍵。 指標中的事件鍵和程式碼中的事件鍵必須完全相符。

取得單一內容

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

取得所有內容

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

評估內容

使用 property.getCurrentValue(entityId, entityAttributes) 方法來評估內容的值。 此方法會根據評估傳回預設內容值或其置換值。 回覆值的資料類型符合內容的資料類型。

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

const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
  • entityId: 實體的 ID。 這將是與評估內容所依據的實體相關的字串 ID。 例如，實體可能是在行動裝置上執行的應用程式的實例，或是存取 Web 應用程式的使用者。 若要讓任何實體與 App Configuration互動，它必須提供唯一實體 ID。
  • entityAttributes: JSON 物件，由定義指定實體的屬性名稱及其值組成。 如果內容未配置任何目標定義，則這是選用參數。 如果已配置目標，則應該提供 entityAttributes 以進行規則評估。 屬性是用來定義區段的參數。 SDK 會使用屬性值來判斷指定的實體是否滿足目標規則，並傳回適當的內容值。

記載

將日誌記錄等級設定為“調試”| 之一'信息' | '警告' | '錯誤'。 預設記錄層級為 info。

appConfigClient.setLogLevel('debug');

支援的資料類型

App Configuration服務允許配置下列資料類型的功能標誌和屬性：布林值、數字、字串。 String 資料型別可以是文字字串、JSON 或 YAML 格式。 SDK 會依據下表所示的 格式進行相應處理，如下表所示。

檢視表格
特徵或屬性值 DataType DataFormat getCurrentValue() 傳回
的資料類型		 輸出範例
true BOOLEAN 不適用 boolean true
25 數字 不適用 number 25
“字串文字” 字串 TEXT string a string text 
{ 
 "firefox": { 
 "名稱": " Firefox ", 
 "pref_url": "about:config" 
 } 
 }
 字串 JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}} 
男士：
 - John Smith 
 - Bill Jones 
女士：
 - Mary Smith 
 - Susan Williams
 字串 YAML string

`"men:

  • John Smith
  • Bill Jones
    women:
  • Mary Smith
  • Susan Williams"`
功能標誌使用範例 
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)
內容用法範例 
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)

設定要素和屬性資料變更的偵聽器

SDK 提供了基於事件的機制，可在功能標誌或屬性的配置發生變更時即時通知您。 您可以使用相同的appConfigClient監聽 configurationUpdate 事件。

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

範例

嘗試範例資料夾中的 範例 應用程序，以了解有關功能和屬性評估的更多資訊。

授權

該項目是在Apache 2.0許可證下發布的。 許可證的全文可以在 LICENSE 中找到