unleash proxy client js
v3.6.1
JavaScript プロキシ クライアントは、外部依存関係 (ブラウザ API を除く) を持たない JavaScript で書かれた小さな Unleash クライアントです。このクライアントは、現在のユーザーに関連するトグルをlocalStorageに保存し、バックグラウンドで Unleash (Unleash フロントエンド APIまたはUnleash プロキシ) と同期します。トグルはユーザーのブラウザに保存されるため、次回ユーザーが同じ Web ページにアクセスしたときに、クライアントはトグルを使用して自身をブートストラップできます。
このクライアントはfetchが利用可能であることを期待しています。古いブラウザをサポートする必要がある場合は、おそらくフェッチ ポリフィルを使用する必要があります。
このパッケージはどのフレームワークにも関連付けられていませんが、最も一般的なフレームワークと併用できます。例:
npm install unleash - proxy - clientヒント: この SDK はクライアント側 SDK として、Unleash プロキシまたは Unleash フロントエンド API に接続する必要があります。詳細については、接続オプションのセクションを参照してください。
ニーズに応じてクライアントを構成します。次の例では、必要なオプションのみを提供します。完全なリストについては、利用可能なオプションに関するセクションを参照してください。
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 ( ) ; この SDK を Unleash インスタンスのフロントエンド API に接続するには、Unleash インスタンスのフロントエンド API への URL ( <unleash-url>/api/frontend ) をurlパラメーターとして使用します。 clientKeyパラメーターには、Unleash インスタンスから生成されたFRONTENDトークンを使用します。必要な手順については、 API トークンの作成方法ガイドを参照してください。
この SDK を Unleash プロキシに接続するには、プロキシの URL とプロキシ クライアント キーを使用します。 Unleash プロキシ ドキュメントの構成セクションには、プロキシのクライアント キーを構成する方法の詳細が含まれています。
クライアントの操作を開始する前に、クライアントのreadyイベントまたはinitializedイベントを待つ必要があります。準備が完了する前に、クライアントは機能の正しい状態を報告しない可能性があります。
unleash . on ( 'ready' , ( ) => {
if ( unleash . isEnabled ( 'proxy.demo' ) ) {
console . log ( 'proxy.demo is enabled' ) ;
} else {
console . log ( 'proxy.demo is disabled' ) ;
}
} ) ;イベント間の違いについては、利用可能なイベントのセクションで説明します。
クライアントの準備ができたら、アプリケーションの機能のチェックを開始できます。 isEnabledメソッドを使用して、必要な機能の状態を確認します。
unleash . isEnabled ( 'proxy.demo' ) ; getVariantメソッドを使用すると、バリアントを持つ有効な機能のバリアントを取得できます。機能が無効になっている場合、またはバリアントがない場合は、無効になっているバリアントが返されます。
const variant = unleash . getVariant ( 'proxy.demo' ) ;
if ( variant . name === 'blue' ) {
// something with variant blue...
} Unleash コンテキストは、現在のユーザーの属性に対して機能を評価するために使用されます。この SDK で Unleash コンテキストを更新および構成するには、 updateContext 、 setContextField 、およびremoveContextFieldメソッドを使用します。
アプリに設定したコンテキストは、機能評価のためのクエリ パラメーターとして Unleash プロキシまたはフロントエンド API に渡されます。
updateContextメソッドは、Unleash コンテキスト全体 (可変部分) を、渡されたデータで置き換えます。
setContextFieldメソッドは、選択したプロパティに対してのみ機能します。 Unleash コンテキストの他のプロパティには影響しません。
unleash . updateContext ( { userId : '1233' } ) ;
unleash . setContextField ( 'userId' , '4141' ) ; removeContextFieldメソッドは、選択したプロパティに対してのみ機能します。 Unleash コンテキストの他のプロパティには影響しません。
unleash . updateContext ( { userId : '1233' , sessionId : 'sessionNotAffected' } ) ;
unleash . removeContextField ( 'userId' ) ;Unleash SDK には次のオプションがあります。
| オプション | 必須 | デフォルト | 説明 |
|---|---|---|---|
| URL | はい | 該当なし | 接続先の Unleash プロキシ URL。例: https://examples.com/proxy |
| クライアントキー | はい | 該当なし | 使用する Unleash プロキシ シークレット |
| アプリ名 | はい | 該当なし | この SDK を使用するアプリケーションの名前。 Unleash プロキシに送信されるメトリクスの一部として使用されます。 Unleash Context の一部にもなります。 |
| コンテクスト | いいえ | {} | 初期の Unleash コンテキスト。これは、すべての機能切り替え評価の初期コンテキストとして使用されます。 appNameおよびenvironmentオプションには、これらのオプションに渡した値が自動的に入力されます。 |
| リフレッシュ間隔 | いいえ | 30 | SDK が更新されたトグル構成を確認する頻度 (秒単位)。 0 に設定すると、アップデートのチェックが無効になります。 |
| 無効にするリフレッシュ | いいえ | false | true に設定すると、クライアントは更新されたトグル構成をチェックしません。 |
| メトリクス間隔 | いいえ | 60 | SDK が使用状況メトリクスを Unleash Proxy に送信する頻度 (秒単位)。これは、設定されたmetricsIntervalInitialの後に送信される最初のメトリクス レポートの後に開始されます。 |
| メトリクス間隔初期 | いいえ | 2 | Unleash API に最初のメトリクス レポートが返されるまで SDK が待機する時間。最初のメトリクス呼び出しを無効にしたい場合は、それを 0 に設定できます。 |
| メトリクスを無効にする | いいえ | false | 使用状況メトリックを無効にする場合は、このオプションをtrueに設定します。 |
| ストレージプロバイダー | いいえ | ブラウザーではLocalStorageProvider 、それ以外の場合はInMemoryStorageProvider | カスタムstoreProviderを挿入できるようにします |
| フェッチ | いいえ | window.fetchまたはグローバルfetch | 使用するフェッチ実装をオーバーライドできます。 node-fetchを挿入できる Node.js 環境で便利です |
| 作成中止コントローラ | いいえ | () => new AbortController() | デフォルトのAbortController作成をオーバーライドできます。古いコンテキストを持つリクエストをキャンセルするために使用されます。処理したくない場合は、 () => nullに設定します。 |
| ブートストラップ | いいえ | [] | キャッシュされた機能の切り替え設定をブートストラップできるようにします。 |
| ブートストラップオーバーライド | いいえ | true | ブートストラップは、ローカル ストレージ内のキャッシュされたデータを自動的にオーバーライドする必要があります。ブートストラップが空の配列でない場合にのみ使用されます。 |
| ヘッダー名 | いいえ | Authorization | Unleash / Unleash Proxy での認証に SDK が使用する必要があるヘッダー。ヘッダーには値としてclientKey与えられます。 |
| カスタムヘッダー | いいえ | {} | Unleash プロキシに HTTP リクエストを行うときに使用する追加のヘッダー。デフォルトのヘッダーと名前が衝突する場合、 nullまたはundefinedでなければ、 customHeaders値が使用されます。 nullまたはundefinedのcustomHeaders値は無視されます。 |
| 印象データすべて | いいえ | false | すべてのgetToggleおよびgetVariant呼び出しに対して「インプレッション」イベントをトリガーできるようにします。これは、フロントエンド SDK に表示されない「無効」機能の切り替えに特に役立ちます。 |
| 環境 | いいえ | default | Unleash コンテキストのenvironmentオプションを設定します。これは SDK の Unleash 環境には影響しません。 |
| usePOSTリクエスト | いいえ | false | 有効な機能をリクエストするときに、GET ではなく POST リクエストを使用するようにクライアントを構成します。これは、機密情報 (ユーザー ID として使用される場合のユーザーの電子メールなど) が URL に漏洩することを避けるためにコンテキストで渡される場合に役立ちます。注: 投稿リクエストは、Unleash に組み込まれているフロントエンド API ではサポートされていません。 |
| 実験的な | いいえ | {} | オプションの実験を有効にします。 togglesStorageTTL : ストレージ内のトグルが有効であると見なされ、開始時にフェッチすべきではない長さ (Time To Live) (秒単位)。 0 に設定すると有効期限チェックが無効になり、常に期限切れとみなされます。 |
クライアントはイベント エミッターでもあります。これは、コードがクライアントからの更新をサブスクライブできることを意味します。これは、状態の更新を切り替えるときに単一ページ アプリを更新する優れた方法です。
unleash . on ( 'update' , ( ) => {
const myToggle = unleash . isEnabled ( 'proxy.demo' ) ;
//do something useful
} ) ; PS!
unleash.start()を呼び出す前に、必ずイベント リスナーを登録する必要があることに注意してください。 SDK を開始した後に登録すると、重要なイベントが失われる危険があります。
「コンテキスト」を介してカスタム セッション ID を指定できます。 sessionId を指定しない場合、この SDK はランダムなセッション ID を作成し、提供されたストレージ (ローカル ストレージ) にも保存されます。一貫した sessionId を常に使用できるようにすることで、段階的な (パーセンテージ ベースの) ロールアウトと組み合わせて、「匿名」ユーザーでも機能の切り替えが評価されるときに一貫したエクスペリエンスを得ることができます。
stopメソッドを呼び出して Unleash クライアントを停止できます。クライアントが停止されると、更新の確認やサーバーへのメトリクスの送信は行われなくなります。
停止したクライアントは再起動できます。
unleash . stop ( )この SDK は、React Native storage @react-native-async-storage/async-storage や、react-native-shared-preferences などと連携して、機能の切り替えをローカルにバックアップできます。これは、次回ユーザーがアプリケーションに戻ったときに SDK をブートストラップするのに役立ちます。
独自のストレージ実装を提供できます。
例:
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 ;
}
} ,
} ) ; この SDK は、node.js アプリケーションでも使用できます (v1.4.0 以降)。有効な「フェッチ」実装を提供する必要があることに注意してください。このパッケージからは ECMAScript モジュールのみがエクスポートされます。
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 ) ;インデックス.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 > API 呼び出しをしたくない場合に、独自の機能切り替え構成を使用して SDK をブートストラップできるようになりました。
これは、SDK の初期化直後にトグルを特定の状態にする必要がある場合にも役立ちます。
新しいUnleashClient作成するときにbootstrap属性を追加します。
bootstrapOverride属性もあります。デフォルトでは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
} ) ;注:bootstrapOverrideがtrue (デフォルト) の場合、ローカルにキャッシュされたデータは指定されたブートストラップで上書きされます。
bootstrapOverrideがfalseの場合、ローカル キャッシュが空でない限り、ローカル キャッシュされたデータは上書きされません。
refreshIntervalおよび/またはmetricsIntervalオプションを0に設定することで、Unleash 機能フラグの自動更新メカニズムとメトリクスの更新をオプトアウトできます。この場合、 updateTogglesやsendMetricsメソッドを呼び出すのはユーザーの責任になります。このアプローチは、Service Worker など、 setInterval API をサポートしていない環境で役立ちます。
