unleash proxy client js
v3.6.1
Le client proxy JavaScript est un petit client Unleash écrit en JavaScript sans aucune dépendance externe (sauf celle des API du navigateur). Ce client stocke les bascules pertinentes pour l'utilisateur actuel dans localStorage et se synchronise avec Unleash (l'API frontale Unleash ou le proxy Unleash) en arrière-plan. Étant donné que les bascules sont stockées dans le navigateur de l'utilisateur, le client peut les utiliser pour s'amorcer la prochaine fois que l'utilisateur visitera la même page Web.
Ce client s'attend à ce que fetch soit disponible. Si vous devez prendre en charge des navigateurs plus anciens, vous devriez probablement utiliser le polyfill fetch.
Ce package n'est lié à aucun framework, mais peut être utilisé avec les frameworks les plus populaires, exemples :
npm install unleash - proxy - clientCONSEIL : en tant que SDK côté client, ce SDK nécessite que vous vous connectiez soit à un proxy Unleash, soit à l'API frontale Unleash. Reportez-vous à la section Options de connexion pour plus d'informations.
Configurez le client selon vos besoins. L'exemple suivant fournit uniquement les options requises. Reportez-vous à la section sur les options disponibles pour la liste complète.
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 ( ) ; Pour connecter ce SDK à l'API frontale de votre instance Unleash, utilisez l'URL de l'API frontale de votre instance Unleash ( <unleash-url>/api/frontend ) comme paramètre url . Pour le paramètre clientKey , utilisez un jeton FRONTEND généré à partir de votre instance Unleash. Reportez-vous au guide sur la façon de créer des jetons API pour connaître les étapes nécessaires.
Pour connecter ce SDK au proxy Unleash, utilisez l'URL du proxy et une clé client proxy. La section de configuration de la documentation du proxy Unleash contient plus d'informations sur la façon de configurer les clés client pour votre proxy.
Vous devez attendre les événements ready ou initialized du client avant de commencer à travailler avec lui. Avant qu'il ne soit prêt, le client peut ne pas signaler l'état correct de vos fonctionnalités.
unleash . on ( 'ready' , ( ) => {
if ( unleash . isEnabled ( 'proxy.demo' ) ) {
console . log ( 'proxy.demo is enabled' ) ;
} else {
console . log ( 'proxy.demo is disabled' ) ;
}
} ) ;La différence entre les événements est décrite dans la section sur les événements disponibles.
Une fois le client prêt, vous pouvez commencer à vérifier les fonctionnalités de votre application. Utilisez la méthode isEnabled pour vérifier l’état de n’importe quelle fonctionnalité souhaitée :
unleash . isEnabled ( 'proxy.demo' ) ; Vous pouvez utiliser la méthode getVariant pour obtenir la variante d'une fonctionnalité activée qui possède des variantes . Si la fonctionnalité est désactivée ou si elle n'a pas de variante, vous récupérerez la variante désactivée
const variant = unleash . getVariant ( 'proxy.demo' ) ;
if ( variant . name === 'blue' ) {
// something with variant blue...
} Le contexte Unleash est utilisé pour évaluer les fonctionnalités par rapport aux attributs de l'utilisateur actuel. Pour mettre à jour et configurer le contexte Unleash dans ce SDK, utilisez les méthodes updateContext , setContextField et removeContextField .
Le contexte que vous définissez dans votre application sera transmis au proxy Unleash ou à l'API frontale en tant que paramètres de requête pour l'évaluation des fonctionnalités.
La méthode updateContext remplacera la totalité (partie mutable) du contexte Unleash par les données que vous transmettez.
La méthode setContextField agit uniquement sur la propriété que vous choisissez. Cela n’affecte aucune autre propriété du contexte Unleash.
unleash . updateContext ( { userId : '1233' } ) ;
unleash . setContextField ( 'userId' , '4141' ) ; La méthode removeContextField agit uniquement sur la propriété que vous choisissez. Cela n’affecte aucune autre propriété du contexte Unleash.
unleash . updateContext ( { userId : '1233' , sessionId : 'sessionNotAffected' } ) ;
unleash . removeContextField ( 'userId' ) ;Le SDK Unleash prend les options suivantes :
| option | requis | défaut | description |
|---|---|---|---|
| URL | Oui | n / A | L’URL du proxy Unleash à laquelle se connecter. Par exemple : https://examples.com/proxy |
| CléClient | Oui | n / A | Le secret proxy Unleash à utiliser |
| Nom de l'application | Oui | n / A | Le nom de l'application utilisant ce SDK. Sera utilisé dans le cadre des métriques envoyées à Unleash Proxy. Fera également partie du Unleash Context. |
| contexte | Non | {} | Le contexte initial de Unleash. Ceci sera utilisé comme contexte initial pour toutes les évaluations de basculement de fonctionnalités. Les options appName et environment seront automatiquement renseignées avec les valeurs que vous transmettez pour ces options. |
| actualiserIntervalle | Non | 30 | À quelle fréquence, en secondes, le SDK doit vérifier la configuration des bascules mise à jour. S'il est défini sur 0, la vérification des mises à jour sera désactivée. |
| désactiverActualiser | Non | false | S'il est défini sur true, le client ne vérifiera pas la configuration de bascule mise à jour |
| metricsInterval | Non | 60 | À quelle fréquence, en secondes, le SDK doit renvoyer les métriques d'utilisation à Unleash Proxy. Il sera démarré après le rapport de métriques initial, qui est envoyé après le metricsIntervalInitial configuré. |
| metricsIntervalInitial | Non | 2 | Combien de temps le SDK doit attendre le premier rapport de métriques à l'API Unleash. Si vous souhaitez désactiver l'appel initial des métriques, vous pouvez le définir sur 0. |
| désactiverMetrics | Non | false | Définissez cette option sur true si vous souhaitez désactiver les métriques d'utilisation |
| Fournisseur de stockage | Non | LocalStorageProvider dans le navigateur, InMemoryStorageProvider sinon | Vous permet d'injecter un storeProvider personnalisé |
| aller chercher | Non | window.fetch ou fetch globale | Vous permet de remplacer l'implémentation de récupération à utiliser. Utile dans les environnements Node.js où vous pouvez injecter node-fetch |
| createAbortController | Non | () => new AbortController() | Vous permet de remplacer la création AbortController par défaut. Utilisé pour annuler les demandes avec un contexte obsolète. Réglez-le sur () => null si vous ne souhaitez pas le gérer. |
| bootstrap | Non | [] | Vous permet d’amorcer la configuration de basculement des fonctionnalités mises en cache. |
| bootstrapOverride | Non | true | Le bootstrap devrait-il automatiquement remplacer les données mises en cache dans le stockage local. Ne sera utilisé que si bootstrap n'est pas un tableau vide. |
| nom d'en-tête | Non | Authorization | Quel en-tête le SDK doit utiliser pour autoriser avec Unleash / Unleash Proxy. L'en-tête recevra la clientKey comme valeur. |
| En-têtes personnalisés | Non | {} | En-têtes supplémentaires à utiliser lors des requêtes HTTP vers le proxy Unleash. En cas de collision de noms avec les en-têtes par défaut, la valeur customHeaders sera utilisée si elle n'est pas null ou undefined . Les valeurs customHeaders null ou undefined seront ignorées. |
| impressionDataAll | Non | false | Vous permet de déclencher des événements « impression » pour toutes les invocations getToggle et getVariant . Ceci est particulièrement utile pour les fonctionnalités « désactivées » qui ne sont pas visibles pour les SDK frontaux. |
| environnement | Non | default | Définit l'option environment du contexte Unleash. Cela n’affecte pas l’environnement Unleash du SDK. |
| utiliser les requêtes POST | Non | false | Configure le client pour utiliser les requêtes POST au lieu de GET lors de la demande de fonctionnalités activées. Ceci est utile lorsque des informations sensibles (comme l'e-mail de l'utilisateur, lorsqu'il est utilisé comme identifiant utilisateur) sont transmises dans le contexte pour éviter leur fuite dans l'URL. REMARQUE : Les demandes de publication ne sont pas prises en charge par l'API frontale intégrée à Unleash. |
| expérimental | Non | {} | Activation de l'expérimentation facultative. togglesStorageTTL : combien de temps (Time To Live), en secondes, les bascules en stockage sont considérées comme valides et ne doivent pas être récupérées au démarrage. S'il est défini sur 0, il désactivera la vérification de l'expiration et sera considéré comme toujours expiré. |
Le client est également un émetteur d'événements. Cela signifie que votre code peut s'abonner aux mises à jour du client. Il s'agit d'un moyen intéressant de mettre à jour une application d'une seule page lorsque vous activez les mises à jour d'état.
unleash . on ( 'update' , ( ) => {
const myToggle = unleash . isEnabled ( 'proxy.demo' ) ;
//do something useful
} ) ; PS ! N'oubliez pas que vous devez toujours enregistrer vos écouteurs d'événement avant votre appel
unleash.start(). Si vous les enregistrez après avoir démarré le SDK, vous risquez de perdre des événements importants.
Vous pouvez fournir un identifiant de session personnalisé via le "contexte". Si vous ne fournissez pas de sessionId, ce SDK créera un identifiant de session aléatoire, qui sera également stocké dans le stockage fourni (stockage local). En ayant toujours un identifiant de session cohérent disponible, vous garantissez que même les utilisateurs « anonymes » bénéficieront d'une expérience cohérente lors de l'évaluation des bascules de fonctionnalités, en combinaison avec un déploiement progressif (basé sur un pourcentage).
Vous pouvez arrêter le client Unleash en appelant la méthode stop . Une fois le client arrêté, il ne vérifiera plus les mises à jour ni n'enverra de métriques au serveur.
Un client arrêté peut être redémarré.
unleash . stop ( )Ce SDK peut fonctionner avec le stockage React Native @react-native-async-storage/async-storage ou React-native-shared-preferences et bien d'autres pour sauvegarder les fonctionnalités de sauvegarde localement. Ceci est utile pour amorcer le SDK la prochaine fois que l'utilisateur reviendra à votre application.
Vous pouvez fournir votre propre implémentation de stockage.
Exemples :
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 ;
}
} ,
} ) ; Ce SDK peut également être utilisé dans les applications node.js (à partir de la v1.4.0). Veuillez noter que vous devrez fournir une implémentation « fetch » valide. Seuls les modules ECMAScript sont exportés à partir de ce package.
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 ) ;index.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 > Il est désormais possible d'amorcer le SDK avec votre propre configuration de basculement de fonctionnalités lorsque vous ne souhaitez pas effectuer d'appel API.
Ceci est également utile si vous souhaitez que les bascules soient dans un certain état immédiatement après l'initialisation du SDK.
Ajoutez un attribut bootstrap lors de la création d'un nouveau UnleashClient .
Il existe également un attribut bootstrapOverride qui est par défaut 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
} ) ; REMARQUES :bootstrapOverride est true (par défaut), toutes les données locales mises en cache seront remplacées par le bootstrap spécifié.
Si bootstrapOverride est false toutes les données locales mises en cache ne seront pas remplacées à moins que le cache local ne soit vide.
Vous pouvez désactiver le mécanisme d'actualisation automatique de l'indicateur de fonctionnalité Unleash et la mise à jour des métriques en définissant les options refreshInterval et/ou metricsInterval sur 0 . Dans ce cas, il devient de votre responsabilité d’appeler les méthodes updateToggles et/ou sendMetrics . Cette approche est utile dans les environnements qui ne prennent pas en charge l'API setInterval , tels que les service Workers.
