App Configuration JavaScript 클라이언트 SDK
' ibm-appconfiguration-js-client-sdk'을 사용하는 애플리케이션의 보안을 강화하려면 init 메서드에서 일반 APIKey 대신 암호화된 APIKey를 사용할 것을 강력히 권장합니다. 이 변경은 사용자가 웹 애플리케이션을 검사할 때 민감한 자격 증명이 노출되는 것을 방지하는 데 필수적입니다. 이미 일반 APIKey를 사용하고 있는 경우, 여기에 언급된 단계에 따라 암호화된 APIKey를 생성하고 사용하도록 애플리케이션을 업데이트하세요.
개요
IBM Cloud App Configuration JavaScript 클라이언트 SDK는 웹 애플리케이션에서 기능 플래그 및 속성 평가를 수행하고 IBM Cloud 서비스의 구성을 기반으로 실험을 위한 사용자 지정 지표를 추적하는 데 사용됩니다 { App Configuration 서비스.
IBM Cloud App Configuration 는 중앙 집중식 기능 관리 및 구성 서비스입니다 의 IBM Cloud 웹 및 모바일 애플리케이션, 마이크로서비스, 분산 환경에서 사용하기 위한 환경에서 사용할 수 있습니다.
App Configuration 웹 애플리케이션을 계측하세요 JavaScript 클라이언트 SDK로 웹 애플리케이션을 계측하고 App Configuration 대시보드, CLI 또는 API를 사용하여 컬렉션으로 구성되고 세그먼트에 타겟팅된 기능 플래그 또는 속성을 정의하세요. 클라우드에서 기능 플래그 상태 전환 의 기능 플래그 상태를 토글하여 필요한 경우 애플리케이션 또는 환경에서 기능을 활성화 또는 비활성화할 수 있습니다. 사용자 지정 지표를 추적하여 실험을 실행하고 기능 플래그가 최종 사용자에게 미치는 영향을 측정하세요. 분산 애플리케이션에서 중앙집중식으로 특성을 관리할 수도 있습니다.
브라우저 호환성: SDK는 모든 주요 브라우저에서 지원됩니다. 브라우저는 ' fetch() API를 지원해야 합니다.
JavaScript 용 클라이언트 SDK 통합
설치
SDK를 설치합니다. 패키지 관리자에서 모듈로 설치하려면 다음 코드를 사용하세요.
npm install ibm-appconfiguration-js-client-sdk
다음과 같이 백엔드의 호스팅된 사이트 또는 CDN에서 참조하여 스크립트 태그에 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);
}
이전 코드 조각에서 비동기 함수 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);
여기서,
- region: 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입니다. 예를 들어 엔티티는 모바일 디바이스에서 실행되는 앱의 인스턴스이거나 웹 애플리케이션에 액세스하는 사용자일 수 있습니다. 모든 엔티티가 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입니다. 예를 들어 엔티티는 모바일 디바이스에서 실행되는 앱의 인스턴스이거나 웹 애플리케이션에 액세스하는 사용자일 수 있습니다. 모든 엔티티가 App Configuration 와 상호 작용하려면 고유한 엔티티 ID를 제공해야 합니다.entityAttributes: 지정된 엔티티를 정의하는 속성 이름 및 해당 값으로 구성되는 JSON 오브젝트입니다. 특성이 대상 정의로 구성되지 않은 경우 이는 선택적 매개변수입니다. 대상이 구성된 경우 규칙 평가를 위해 entityAttributes 를 제공해야 합니다. 속성은 세그먼트를 정의하는 데 사용되는 매개변수입니다. SDK는 속성 값을 사용하여 지정된 엔티티가 대상 규칙을 충족하는지 여부를 판별하고 적절한 특성 값을 리턴합니다.
로깅
로깅 수준을 '디버그' | '정보' | '경고' | '오류' 중 하나로 설정합니다. 기본 로깅 수준은 info 입니다.
appConfigClient.setLogLevel('debug');
지원되는 데이터 유형
App Configuration 서비스를 사용하면 부울, 숫자, 문자열 데이터 유형에서 기능 플래그 및 특성을 구성할 수 있습니다. 문자열 데이터 유형은 텍스트 문자열, JSON 또는 YAML 형식이 될 수 있습니다. SDK는 각 형식을 다음 표와 같이 처리합니다.
테이블 보기
| 기능 또는 특성 값 | DataType | DataFormat | getCurrentValue()에 의해 리턴되는 데이터의 유형 |
출력 예 |
|---|---|---|---|---|
true |
BOOLEAN | 해당 사항 없음 | boolean |
true |
25 |
숫자 | 해당 사항 없음 | number |
25 |
| "문자열 텍스트" | 문자열 | 텍스트 | string |
a string text |
{ |
문자열 | JSON | JSON object |
{"firefox":{"name":"Firefox","pref_url":"about:config"}} |
men: |
문자열 | YAML | string |
`"men:
|
기능 플래그 사용 예
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 라이선스에 따라 배포됩니다. 라이선스 전문은 라이선스