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-syd etc.
  • 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
{
"firefox": {
"name": "Firefox",
"pref_url": "about:config"
}
}
STRING JSON JSON object {"firefox":{"name":"Firefox","pref_url":"about:config"}}
homens:
-John Smith
-Bill Jones
mulheres:
-Mary Smith
-Susan Williams
STRING YAML string

`"men:

  • John Smith
  • Bill Jones
    women:
  • Mary Smith
  • Susan Williams"`
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