App Configuration JavaScript sDK do cliente
Para aumentar a segurança de seus aplicativos que usam o ' ibm-appconfiguration-js-client-sdk, é altamente recomendável usar uma APIKey criptografada em vez da APIKey simples no método init. Essa alteração é vital
para evitar a exposição de credenciais confidenciais quando os usuários inspecionam seu aplicativo da Web. Se você já estiver usando uma APIKey simples, atualize seu aplicativo para gerar e usar a APIKey criptografada de acordo com as etapas
mencionadas aqui.
Visão geral
IBM Cloud App Configuration O JavaScript Client SDK é usado para executar a avaliação de propriedades e sinalizadores de recursos em aplicativos da Web e rastrear métricas personalizadas para experimentação com base na configuração em IBM Cloud serviço App Configuration.
IBM Cloud App Configuration é um serviço centralizado de gerenciamento e configuração de recursos em IBM Cloud para uso com aplicativos da Web e móveis, microsserviços e ambientes distribuídos e ambientes distribuídos.
Instrumente seus aplicativos da Web com o App Configuration JavaScript Client SDK e use o painel App Configuration, a CLI ou a API para definir sinalizadores ou propriedades de recursos, organizados em coleções e direcionados a segmentos. Alterne os estados do sinalizador de recursos na na nuvem para ativar ou desativar recursos em seu aplicativo ou ambiente, quando necessário. Execute experimentos e meça o efeito dos sinalizadores de recursos nos usuários finais, rastreando métricas personalizadas. Também é possível gerenciar as propriedades para aplicativos distribuídos centralmente.
Compatibilidade com o navegador: O SDK é compatível com todos os principais navegadores. O navegador deve ter suporte à API " fetch().
Integrando SDK do cliente para JavaScript
Instalação
Instalar o SDK. Use o código a seguir para instalar como um módulo do gerenciador de pacotes.
npm install ibm-appconfiguration-js-client-sdk
Você pode importar o SDK para a tag de script fazendo referência a ele a partir de um site hospedado em seu back-end ou de uma CDN, como segue:
Exemplo:
<script type="text/javascript" src="https://unpkg.com/ibm-appconfiguration-js-client-sdk/dist/appconfiguration.js"></script>
Inicializar o SDK
Inicialize o SDK para se conectar à sua instância de serviço do 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);
}
No snippet anterior, a função assíncrona initialiseAppConfig() retornará um Promise<void> que é resolvido quando as configurações são obtidas com êxito. Caso contrário, gera um erro se não for bem-sucedido.
Espera-se que a inicialização seja feita apenas uma vez.
Depois que o SDK for inicializado com êxito, o sinalizador e as propriedades do recurso poderão ser recuperados usando o site appConfigClient, conforme mostrado no seguinte trecho de código.
Expanda para exibir o snippet de exemplo
// 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);
em que,
- region: Nome da região em que a instância do serviço App Configuration é criada. Veja a lista de locais com suporte aqui. Por exemplo: -
us-south,au-sydetc. - guid: ID da instância do serviço App Configuration. Obtenha-a na seção de credenciais de serviço do painel App Configuration.
- apikey: A APIKey criptografada gerada conforme descrito aqui.
- collectionId: ID da coleção criada na instância de serviço App Configuration na seção Collections (Coleções ).
- environmentId: ID do ambiente criado na instância de serviço App Configuration na seção Environments (Ambientes ).
Sempre use a APIKey criptografada para evitar a exposição de informações confidenciais.
Certifique-se de criar as credenciais de serviço com a função " Client SDK, pois ela tem as permissões de acesso
mínimas adequadas para uso em aplicativos baseados em navegador.
Exemplos para uso de APIs relacionadas a recurso e propriedade
Consulte os exemplos a seguir para usar as APIs relacionadas ao recurso
Obter recurso único
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()} `);
Obter todos os recursos
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()} `);
}
Avaliar um recurso
Use o método feature.getCurrentValue(entityId, entityAttributes) para avaliar o valor do sinalizador de recurso. Este método retorna um valor Ativado / Desativado / Substituído com base na avaliação. O tipo de dados do valor
retornado corresponde ao sinalizador do recurso.
const entityId = 'john_doe';
const entityAttributes = {
city: 'Bangalore',
country: 'India',
};
const feature = appConfigClient.getFeature('featureId');
const featureValue = feature.getCurrentValue(entityId, entityAttributes);
entityId: ID da Entidade. Será um identificador de sequência relacionado à Entidade com relação à qual o recurso é avaliado. Por exemplo, uma entidade pode ser uma instância de um aplicativo que é executado em um dispositivo móvel ou um usuário que acessa o aplicativo da Web. Para que qualquer entidade interaja com App Configuration, ela deve fornecer um ID de entidade exclusivo.entityAttributes: um objeto JSON que consiste no nome do atributo e seus valores que definem a entidade especificada. Este é um parâmetro opcional se o sinalizador de recurso não estiver configurado com nenhuma definição de destino Se o destino estiver configurado, então entityAttributes deverá ser fornecido para a avaliação de regra Um atributo é um parâmetro que é usado para definir um segmento. O SDK usa os valores de atributo para determinar se a entidade especificada satisfaz as regras de destino e retorna o valor da sinalização de recurso apropriado.
Enviar métricas personalizadas
Registre métricas personalizadas para usar em experimentos usando a função de rastreamento.
appConfigClient.track(eventKey, entityId)
em que
eventKey: A chave do evento para a métrica associada ao experimento em execução. A chave do evento em sua métrica e a chave do evento em seu código devem corresponder exatamente.
Obter propriedade única
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()} `);
Obter todas as propriedades
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()} `);
}
Avaliar uma propriedade
Use o método property.getCurrentValue(entityId, entityAttributes) para avaliar o valor da propriedade. Esse método retorna o valor da propriedade padrão ou seu valor substituído, com base na avaliação. O tipo de dados do valor
retornado corresponde àquele da propriedade..
const entityId = 'john_doe';
const entityAttributes = {
city: 'Bangalore',
country: 'India',
};
const property = appConfigClient.getProperty('propertyId');
const propertyValue = property.getCurrentValue(entityId, entityAttributes);
entityId: ID da Entidade. Este será um identificador de sequência relacionado à Entidade na qual a propriedade é avaliada. Por exemplo, uma entidade pode ser uma instância de um aplicativo que é executado em um dispositivo móvel ou um usuário que acessa o aplicativo da Web. Para que qualquer entidade interaja com App Configuration, ela deve fornecer um ID de entidade exclusivo.entityAttributes: um objeto JSON que consiste no nome do atributo e seus valores que definem a entidade especificada. Este é um parâmetro opcional se a propriedade não estiver configurada com nenhuma definição de destino Se o destino estiver configurado, então entityAttributes deverá ser fornecido para a avaliação de regra Um atributo é um parâmetro que é usado para definir um segmento. O SDK usa os valores de atributo para determinar se a entidade especificada satisfaz as regras de destino e retorna o valor da propriedade apropriado..
Criação de log
Defina o nível de registro como um dos seguintes: 'debug' | 'info' | 'warning' | 'error'. O nível de registro padrão é info.
appConfigClient.setLogLevel('debug');
Tipos de dados suportados
O serviço App Configuration permite configurar sinalizadores e propriedades de recursos com os tipos de dados a seguir: Booleano, Numérico, Sequência. O tipo de dados de sequência pode estar no formato de uma sequência de texto, JSON ou YAML. O SDK processa cada formato formato adequadamente, conforme mostrado na tabela a seguir.
Visualizar tabela
| Valor do recurso ou propriedade | DataType | DataFormat | Tipo de dados retornado por getCurrentValue() |
Saída de exemplo |
|---|---|---|---|---|
true |
BOOLEAN | não aplicável | boolean |
true |
25 |
NUMÉRICO | não aplicável | number |
25 |
| "um texto de sequência" | STRING | TEXT | string |
a string text |
{ |
STRING | JSON | JSON object |
{"firefox":{"name":"Firefox","pref_url":"about:config"}} |
homens: |
STRING | YAML | string |
`"men:
|
Exemplo de uso do sinalizador de recurso
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)
Exemplo de uso de propriedade:
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)
Definir ouvinte para alterações de dados de recursos e propriedades
O SDK fornece um mecanismo baseado em eventos para notificá-lo em tempo real quando a configuração do sinalizador de recurso ou da propriedade for alterada. Você pode ouvir o evento ' configurationUpdate usando o mesmo 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);
});
Exemplos
Experimente este aplicativo de amostra na pasta Examples para saber mais sobre a avaliação de recursos e propriedades.
Licença
Este projeto é lançado sob a licença Apache 2.0. O texto completo da licença pode ser encontrado em LICENÇA