unleash proxy client js
v3.6.1
O cliente proxy JavaScript é um pequeno cliente Unleash escrito em JavaScript sem quaisquer dependências externas (exceto APIs do navegador). Este cliente armazena alternâncias relevantes para o usuário atual no localStorage e sincroniza com o Unleash (a API front-end do Unleash ou o proxy do Unleash) em segundo plano. Como as alternâncias são armazenadas no navegador do usuário, o cliente pode usá-las para inicializar na próxima vez que o usuário visitar a mesma página da web.
Este cliente espera que fetch esteja disponível. Se você precisar oferecer suporte a navegadores mais antigos, provavelmente deverá usar o fetch polyfill.
Este pacote não está vinculado a nenhum framework, mas pode ser usado em conjunto com os frameworks mais populares, exemplos:
npm install unleash - proxy - clientDICA : Como um SDK do lado do cliente, este SDK requer que você se conecte a um proxy Unleash ou à API front-end do Unleash. Consulte a seção de opções de conexão para obter mais informações.
Configure o cliente de acordo com suas necessidades. O exemplo a seguir fornece apenas as opções necessárias. Consulte a seção sobre opções disponíveis para obter a lista completa.
import { UnleashClient } from 'unleash-proxy-client' ;
const unleash = new UnleashClient ( {
url : 'https://<your-unleash-instance>/api/frontend' ,
clientKey : '<your-client-side-token>' ,
appName : 'my-webapp' ,
} ) ;
// Start the background polling
unleash . start ( ) ; Para conectar este SDK à API front-end da sua instância Unleash, use o URL da API front-end da sua instância Unleash ( <unleash-url>/api/frontend ) como parâmetro url . Para o parâmetro clientKey , use um token FRONTEND gerado a partir de sua instância do Unleash. Consulte o guia como criar tokens de API para obter as etapas necessárias.
Para conectar este SDK ao proxy Unleash, use a URL do proxy e uma chave do cliente proxy. A seção de configuração da documentação do proxy Unleash contém mais informações sobre como configurar chaves de cliente para seu proxy.
Você deve aguardar os eventos ready ou initialized do cliente antes de começar a trabalhar com ele. Antes de estar pronto, o cliente pode não informar o estado correto dos seus recursos.
unleash . on ( 'ready' , ( ) => {
if ( unleash . isEnabled ( 'proxy.demo' ) ) {
console . log ( 'proxy.demo is enabled' ) ;
} else {
console . log ( 'proxy.demo is disabled' ) ;
}
} ) ;A diferença entre os eventos está descrita na seção de eventos disponíveis.
Quando o cliente estiver pronto, você poderá começar a verificar os recursos do seu aplicativo. Use o método isEnabled para verificar o estado de qualquer recurso desejado:
unleash . isEnabled ( 'proxy.demo' ) ; Você pode usar o método getVariant para obter a variante de um recurso habilitado que possui variantes . Se o recurso estiver desativado ou não tiver variantes, você receberá de volta a variante desativada
const variant = unleash . getVariant ( 'proxy.demo' ) ;
if ( variant . name === 'blue' ) {
// something with variant blue...
} O contexto Unleash é usado para avaliar recursos em relação aos atributos do usuário atual. Para atualizar e configurar o contexto Unleash neste SDK, use os métodos updateContext , setContextField e removeContextField .
O contexto que você definir em seu aplicativo será repassado ao proxy Unleash ou à API front-end como parâmetros de consulta para avaliação de recursos.
O método updateContext substituirá todo o contexto Unleash (parte mutável) pelos dados que você passa.
O método setContextField atua apenas na propriedade que você escolher. Isso não afeta nenhuma outra propriedade do contexto Unleash.
unleash . updateContext ( { userId : '1233' } ) ;
unleash . setContextField ( 'userId' , '4141' ) ; O método removeContextField atua apenas na propriedade que você escolher. Isso não afeta nenhuma outra propriedade do contexto Unleash.
unleash . updateContext ( { userId : '1233' , sessionId : 'sessionNotAffected' } ) ;
unleash . removeContextField ( 'userId' ) ;O Unleash SDK aceita as seguintes opções:
| opção | obrigatório | padrão | descrição |
|---|---|---|---|
| url | sim | n / D | O URL do Unleash Proxy ao qual se conectar. Por exemplo: https://examples.com/proxy |
| chave do cliente | sim | n / D | O segredo do Unleash Proxy a ser usado |
| nome do aplicativo | sim | n / D | O nome do aplicativo que usa esse SDK. Será usado como parte das métricas enviadas ao Unleash Proxy. Também fará parte do Contexto Unleash. |
| contexto | não | {} | O contexto inicial do Unleash. Isso será usado como contexto inicial para todas as avaliações de alternância de recursos. As opções appName e environment serão preenchidas automaticamente com os valores que você passar para essas opções. |
| atualizarInterval | não | 30 | Com que frequência, em segundos, o SDK deve verificar a configuração de alternância atualizada. Se definido como 0 desativará a verificação de atualizações |
| desabilitarAtualizar | não | false | Se definido como verdadeiro, o cliente não verificará a configuração de alternância atualizada |
| métricasIntervalo | não | 60 | Com que frequência, em segundos, o SDK deve enviar métricas de uso de volta ao Unleash Proxy. Será iniciado após o relatório de métricas inicial, que é enviado após o metricsIntervalInitial configurado |
| métricasIntervalInitial | não | 2 | Quanto tempo o SDK deve esperar pelo primeiro relatório de métricas para a API Unleash. Se quiser desabilitar a chamada de métricas inicial, você pode defini-la como 0. |
| desativar Métricas | não | false | Defina esta opção como true se desejar desativar as métricas de uso |
| provedor de armazenamento | não | LocalStorageProvider no navegador, InMemoryStorageProvider caso contrário | Permite que você injete um storeProvider personalizado |
| buscar | não | window.fetch ou fetch global | Permite substituir a implementação de busca a ser usada. Útil em ambientes Node.js onde você pode injetar node-fetch |
| createAbortController | não | () => new AbortController() | Permite substituir a criação padrão AbortController . Usado para cancelar solicitações com contexto desatualizado. Defina-o como () => null se você não quiser lidar com isso. |
| inicialização | não | [] | Permite inicializar a configuração de alternância do recurso em cache. |
| bootstrapOverride | não | true | O bootstrap deve substituir automaticamente os dados armazenados em cache no armazenamento local. Só será usado se o bootstrap não for um array vazio. |
| cabeçalhoNome | não | Authorization | Qual cabeçalho o SDK deve usar para autorizar com Unleash/Unleash Proxy. O cabeçalho receberá clientKey como seu valor. |
| cabeçalhos personalizados | não | {} | Cabeçalhos adicionais para usar ao fazer solicitações HTTP ao proxy Unleash. Em caso de colisão de nomes com os cabeçalhos padrão, o valor customHeaders será usado se não for null ou undefined . Os valores customHeaders null ou undefined serão ignorados. |
| impressãoDataAll | não | false | Permite acionar eventos de "impressão" para todas as invocações getToggle e getVariant . Isso é particularmente útil para alternâncias de recursos "desativadas" que não são visíveis para SDKs de front-end. |
| ambiente | não | default | Define a opção environment do contexto Unleash. Isso não afeta o ambiente Unleash do SDK. |
| usarPOSTrequests | não | false | Configura o cliente para usar solicitações POST em vez de GET ao solicitar recursos habilitados. Isso é útil quando informações confidenciais (como email do usuário, quando usado como ID do usuário) são passadas no contexto para evitar vazamento na URL. NOTA: Solicitações de postagem não são suportadas pela API de front-end integrada ao Unleash. |
| experimental | não | {} | Habilitando experimentação opcional. togglesStorageTTL : Quanto tempo (Time To Live), em segundos, as alternâncias no armazenamento são consideradas válidas e não devem ser buscadas na inicialização. Se definido como 0 desabilitará a verificação de expiração e será considerado sempre expirado. |
O cliente também é um emissor de eventos. Isso significa que seu código pode assinar atualizações do cliente. Esta é uma maneira interessante de atualizar um aplicativo de página única ao alternar as atualizações de estado.
unleash . on ( 'update' , ( ) => {
const myToggle = unleash . isEnabled ( 'proxy.demo' ) ;
//do something useful
} ) ; PS! Lembre-se de que você deve sempre registrar seus ouvintes de eventos antes de sua chamada
unleash.start(). Se você registrá-los depois de iniciar o SDK, você corre o risco de perder eventos importantes.
Você pode fornecer um ID de sessão personalizado através do "contexto". Se você não fornecer um sessionId, este SDK criará um ID de sessão aleatório, que também será armazenado no armazenamento fornecido (armazenamento local). Ter sempre um sessionId consistente disponível garante que mesmo usuários "anônimos" terão uma experiência consistente quando a alternância de recursos for avaliada, em combinação com uma implementação gradual (baseada em porcentagem).
Você pode parar o cliente Unleash chamando o método stop . Depois que o cliente for interrompido, ele não verificará mais atualizações nem enviará métricas ao servidor.
Um cliente parado pode ser reiniciado.
unleash . stop ( )Este SDK pode funcionar com armazenamento React Native @react-native-async-storage/async-storage ou react-native-shared-preferences e muito mais para alternar recursos de backup localmente. Isso é útil para inicializar o SDK na próxima vez que o usuário retornar ao seu aplicativo.
Você pode fornecer sua própria implementação de armazenamento.
Exemplos:
import SharedPreferences from 'react-native-shared-preferences' ;
import { UnleashClient } from 'unleash-proxy-client' ;
const unleash = new UnleashClient ( {
url : 'https://eu.unleash-hosted.com/hosted/proxy' ,
clientKey : 'your-proxy-key' ,
appName : 'my-webapp' ,
storageProvider : {
save : ( name : string , data : any ) => SharedPreferences . setItem ( name , data ) ,
get : ( name : string ) => SharedPreferences . getItem ( name , ( val ) => val )
} ,
} ) ; import AsyncStorage from '@react-native-async-storage/async-storage' ;
import { UnleashClient } from 'unleash-proxy-client' ;
const PREFIX = 'unleash:repository' ;
const unleash = new UnleashClient ( {
url : 'https://eu.unleash-hosted.com/hosted/proxy' ,
clientKey : 'your-proxy-key' ,
appName : 'my-webapp' ,
storageProvider : {
save : ( name : string , data : any ) => {
const repo = JSON . stringify ( data ) ;
const key = ` ${ PREFIX } : ${ name } ` ;
return AsyncStorage . setItem ( key , repo ) ;
} ,
get : ( name : string ) => {
const key = ` ${ PREFIX } : ${ name } ` ;
const data = await AsyncStorage . getItem ( key ) ;
return data ? JSON . parse ( data ) : undefined ;
}
} ,
} ) ; Este SDK também pode ser usado em aplicativos node.js (a partir da v1.4.0). Observe que você precisará fornecer uma implementação de "busca" válida. Apenas módulos ECMAScript são exportados deste pacote.
import fetch from 'node-fetch' ;
import { UnleashClient , InMemoryStorageProvider } from 'unleash-proxy-client' ;
const unleash = new UnleashClient ( {
url : 'https://app.unleash-hosted.com/demo/proxy' ,
clientKey : 'proxy-123' ,
appName : 'nodejs-proxy' ,
storageProvider : new InMemoryStorageProvider ( ) ,
fetch ,
} ) ;
await unleash . start ( ) ;
const isEnabled = unleash . isEnabled ( 'proxy.demo' ) ;
console . log ( isEnabled ) ;índice.mjs
< html >
< head >
< script src =" https://unpkg.com/unleash-proxy-client@latest/build/main.min.js " type =" text/javascript " > </ script >
< script type =" text/javascript " >
var config = { url : 'https://app.unleash-hosted.com/demo/proxy' , clientKey : 'proxy-123' , appName : 'web' } ;
var client = new unleash . UnleashClient ( config ) ;
client . updateContext ( { userId : '1233' } )
client . on ( 'update' , ( ) => {
console . log ( client . isEnabled ( 'proxy.demo' ) ) ;
} ) ;
client . start ( ) ;
</ script >
</ head >
</ html > Agora é possível inicializar o SDK com sua própria configuração de alternância de recursos quando você não quiser fazer uma chamada de API.
Isso também é útil se você precisar que as alternâncias estejam em um determinado estado imediatamente após a inicialização do SDK.
Adicione um atributo bootstrap ao criar um novo UnleashClient .
Há também um atributo bootstrapOverride que por padrão é true .
import { UnleashClient } from 'unleash-proxy-client' ;
const unleash = new UnleashClient ( {
url : 'https://app.unleash-hosted.com/demo/proxy' ,
clientKey : 'proxy-123' ,
appName : 'nodejs-proxy' ,
bootstrap : [ {
"enabled" : true ,
"name" : "demoApp.step4" ,
"variant" : {
"enabled" : true ,
"name" : "blue" ,
"feature_enabled" : true ,
}
} ] ,
bootstrapOverride : false
} ) ; NOTAS:bootstrapOverride for true (por padrão), quaisquer dados locais em cache serão substituídos pelo bootstrap especificado.
Se bootstrapOverride for false quaisquer dados locais em cache não serão substituídos, a menos que o cache local esteja vazio.
Você pode cancelar o mecanismo de atualização automática do sinalizador de recurso Unleash e a atualização de métricas definindo as opções refreshInterval e/ou metricsInterval como 0 . Nesse caso, é sua responsabilidade chamar os métodos updateToggles e/ou sendMetrics . Essa abordagem é útil em ambientes que não suportam a API setInterval , como service workers.
