unleash proxy client js

ปล่อย Proxy Client สำหรับเบราว์เซอร์ (JS)

ไคลเอนต์พร็อกซี JavaScript เป็นไคลเอนต์ Unleash ขนาดเล็กที่เขียนด้วย JavaScript โดยไม่มีการพึ่งพาภายนอกใด ๆ (ยกเว้นจาก API ของเบราว์เซอร์) ไคลเอนต์นี้จะจัดเก็บการสลับที่เกี่ยวข้องกับผู้ใช้ปัจจุบันใน localStorage และซิงโครไนซ์กับ Unleash (API ส่วนหน้าของ Unleash หรือ พร็อกซี Unleash) ในเบื้องหลัง เนื่องจากการสลับถูกจัดเก็บไว้ในเบราว์เซอร์ของผู้ใช้ ลูกค้าจึงสามารถใช้เพื่อบูตตัวเองในครั้งถัดไปที่ผู้ใช้เยี่ยมชมหน้าเว็บเดียวกัน

ไคลเอนต์รายนี้คาดหวังว่า fetch จะพร้อมใช้งาน หากคุณต้องการรองรับเบราว์เซอร์รุ่นเก่า คุณควรใช้ fetch polyfill

รองรับกรอบงาน

แพ็คเกจนี้ไม่เชื่อมโยงกับเฟรมเวิร์กใด ๆ แต่สามารถใช้ร่วมกันกับเฟรมเวิร์กยอดนิยมได้ ตัวอย่าง:

• ปลดปล่อย React SDK
• ตอบสนอง
• ตอบสนองพื้นเมือง
• JS เชิงมุม
• Vue.js
• ...และอาจเป็นของโปรดของคุณ!

วิธีการใช้งานไคลเอนต์

ขั้นตอนที่ 1: การติดตั้ง

 npm install unleash - proxy - client

ขั้นตอนที่ 2: เริ่มต้น SDK

---

เคล็ดลับ : ในฐานะ SDK ฝั่งไคลเอ็นต์ SDK นี้ต้องการให้คุณเชื่อมต่อกับพร็อกซี Unleash หรือกับ Unleash front-end 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 นี้กับ API ส่วนหน้าของอินสแตนซ์ Unleash ให้ใช้ URL ไปยัง API ส่วนหน้าของอินสแตนซ์ Unleash ( <unleash-url>/api/frontend ) เป็นพารามิเตอร์ url สำหรับพารามิเตอร์ clientKey ให้ใช้โทเค็น FRONTEND ที่สร้างจากอินสแตนซ์ Unleash ของคุณ โปรดดู วิธีสร้างคู่มือโทเค็น API สำหรับขั้นตอนที่จำเป็น

หากต้องการเชื่อมต่อ SDK นี้กับพร็อกซี Unleash ให้ใช้ URL ของพร็อกซีและคีย์ไคลเอ็นต์ของพร็อกซี ส่วน การกำหนดค่า ของเอกสารพร็อกซี Unleash มีข้อมูลเพิ่มเติมเกี่ยวกับวิธีกำหนดค่าคีย์ไคลเอ็นต์สำหรับพร็อกซีของคุณ

ขั้นตอนที่ 3: ปล่อยให้ไคลเอนต์ซิงโครไนซ์

คุณควรรอเหตุการณ์ ready หรือ initialized ของลูกค้าก่อนที่จะเริ่มทำงาน ก่อนที่จะพร้อม ลูกค้าอาจไม่รายงานสถานะที่ถูกต้องสำหรับคุณลักษณะของคุณ

 unleash . on ( 'ready' , ( ) => {
    if ( unleash . isEnabled ( 'proxy.demo' ) ) {
        console . log ( 'proxy.demo is enabled' ) ;
    } else {
        console . log ( 'proxy.demo is disabled' ) ;
    }
} ) ;

ความแตกต่างระหว่างเหตุการณ์ต่างๆ ได้อธิบายไว้ในส่วนของเหตุการณ์ที่มีอยู่

ขั้นตอนที่ 4: ตรวจสอบสถานะการสลับคุณสมบัติ

เมื่อไคลเอนต์พร้อม คุณสามารถเริ่มตรวจสอบคุณสมบัติในแอปพลิเคชันของคุณได้ ใช้เมธอด isEnabled เพื่อตรวจสอบสถานะของฟีเจอร์ที่คุณต้องการ:

 unleash . isEnabled ( 'proxy.demo' ) ;

คุณสามารถใช้เมธอด getVariant เพื่อรับตัวแปรของ ฟีเจอร์ที่เปิดใช้งานซึ่งมีตัวแปร หากคุณสมบัตินี้ถูกปิดใช้งานหรือหากไม่มีตัวเลือกสินค้า คุณจะได้รับ คุณสมบัติที่ปิดใช้งาน กลับคืนมา

 const variant = unleash . getVariant ( 'proxy.demo' ) ;
if ( variant . name === 'blue' ) {
    // something with variant blue...
} 

กำลังอัปเดตบริบท Unleash

บริบท Unleash ใช้เพื่อประเมินคุณสมบัติเทียบกับคุณลักษณะของผู้ใช้ปัจจุบัน หากต้องการอัปเดตและกำหนดค่าบริบท Unleash ใน SDK นี้ ให้ใช้เมธอด 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 Proxy URL ที่จะเชื่อมต่อ เช่น https://examples.com/proxy
ลูกค้าคีย์	ใช่	ไม่มี	ข้อมูลลับ Unleash Proxy ที่จะใช้
ชื่อแอป	ใช่	ไม่มี	ชื่อของแอปพลิเคชันที่ใช้ SDK นี้ จะถูกใช้เป็นส่วนหนึ่งของตัวชี้วัดที่ส่งไปยัง Unleash Proxy จะเป็นส่วนหนึ่งของ Unleash Context ด้วย
บริบท	เลขที่	{}	บริบท Unleash เริ่มต้น สิ่งนี้จะถูกใช้เป็นบริบทเริ่มต้นสำหรับการประเมินการสลับคุณลักษณะทั้งหมด ตัวเลือก appName และ environment จะถูกเติมด้วยค่าที่คุณส่งสำหรับตัวเลือกเหล่านั้นโดยอัตโนมัติ
รีเฟรชช่วงเวลา	เลขที่	30	SDK ควรตรวจสอบการกำหนดค่าการสลับที่อัปเดตบ่อยแค่ไหนในหน่วยวินาที หากตั้งค่าเป็น 0 จะปิดการตรวจสอบการอัปเดต
ปิดการใช้งานรีเฟรช	เลขที่	false	หากตั้งค่าเป็นจริง ไคลเอนต์จะไม่ตรวจสอบการกำหนดค่าการสลับที่อัปเดต
เมตริกช่วงเวลา	เลขที่	60	SDK ควรส่งตัววัดการใช้งานกลับไปที่ Unleash Proxy บ่อยแค่ไหนในหน่วยวินาที โดยจะเริ่มต้นหลังจากรายงานเมทริกเริ่มต้น ซึ่งจะถูกส่งหลังจาก metricsIntervalInitial ที่กำหนดค่าไว้
เมตริกช่วงเริ่มต้น	เลขที่	2	SDK ควรรอนานแค่ไหนสำหรับรายงานตัววัดแรกกลับไปยัง Unleash API หากคุณต้องการปิดใช้งานการเรียกตัววัดเริ่มต้น คุณสามารถตั้งค่าเป็น 0 ได้
ปิดการใช้งานเมตริก	เลขที่	false	ตั้งค่าตัวเลือกนี้เป็น true หากคุณต้องการปิดใช้งานการวัดการใช้งาน
ผู้ให้บริการจัดเก็บข้อมูล	เลขที่	LocalStorageProvider ในเบราว์เซอร์ InMemoryStorageProvider เป็นอย่างอื่น	ช่วยให้คุณสามารถฉีด storeProvider แบบกำหนดเองได้
ดึง	เลขที่	window.fetch หรือ fetch ทั่วโลก	อนุญาตให้คุณแทนที่การใช้งานการดึงข้อมูลที่จะใช้ มีประโยชน์ในสภาพแวดล้อม Node.js ที่คุณสามารถฉีดการดึง node-fetch
createAbortController	เลขที่	() => new AbortController()	ช่วยให้คุณสามารถแทนที่การสร้าง AbortController เริ่มต้นได้ ใช้เพื่อยกเลิกคำขอที่มีบริบทที่ล้าสมัย ตั้งค่าเป็น () => null หากคุณไม่ต้องการจัดการ
บูตสแตรป	เลขที่	[]	ช่วยให้คุณสามารถบู๊ตสแตรปการกำหนดค่าการสลับคุณสมบัติแคช
bootstrapOverride	เลขที่	true	หากบูตสแตรปจะแทนที่ข้อมูลที่แคชไว้ในที่จัดเก็บในตัวเครื่องโดยอัตโนมัติ จะใช้เฉพาะในกรณีที่ bootstrap ไม่ใช่อาร์เรย์ว่าง
ชื่อส่วนหัว	เลขที่	Authorization	ส่วนหัวใดที่ SDK ควรใช้ในการอนุญาตด้วย Unleash / Unleash Proxy ส่วนหัวจะได้รับ clientKey เป็นค่าของมัน
ส่วนหัวแบบกำหนดเอง	เลขที่	{}	ส่วนหัวเพิ่มเติมที่จะใช้เมื่อส่งคำขอ HTTP ไปยังพร็อกซี Unleash ในกรณีที่ชื่อขัดแย้งกับส่วนหัวเริ่มต้น ค่า customHeaders จะถูกนำมาใช้หากไม่เป็น null หรือ undefined ค่า customHeaders ที่เป็น null หรือ undefined จะถูกละเว้น
ข้อมูลความประทับใจทั้งหมด	เลขที่	false	ช่วยให้คุณทริกเกอร์เหตุการณ์ "การแสดงผล" สำหรับการเรียกใช้ getToggle และ getVariant ทั้งหมด สิ่งนี้มีประโยชน์อย่างยิ่งสำหรับการสลับฟีเจอร์ "ปิดใช้งาน" ที่ไม่สามารถมองเห็นได้ใน Frontend SDK
สิ่งแวดล้อม	เลขที่	default	ตั้งค่าตัวเลือก environment ของบริบท Unleash สิ่งนี้ ไม่ ส่งผลกระทบต่อสภาพแวดล้อม Unleash ของ SDK
ใช้คำขอ POST	เลขที่	false	กำหนดค่าไคลเอ็นต์ให้ใช้คำขอ POST แทน GET เมื่อร้องขอคุณลักษณะที่เปิดใช้งาน ซึ่งจะมีประโยชน์เมื่อมีการส่งข้อมูลละเอียดอ่อน (เช่น อีเมลของผู้ใช้ เมื่อใช้เป็น ID ผู้ใช้) ถูกส่งไปในบริบทเพื่อหลีกเลี่ยงไม่ให้ข้อมูลรั่วไหลใน URL หมายเหตุ: API ส่วนหน้าที่สร้างไว้ใน Unleash ไม่รองรับคำขอโพสต์
ทดลอง	เลขที่	{}	การเปิดใช้งานการทดลองเสริม togglesStorageTTL : ระยะเวลา (Time To Live) มีหน่วยเป็นวินาที การสลับในที่เก็บข้อมูลถือว่าใช้ได้และไม่ควรดึงข้อมูลเมื่อเริ่มต้น หากตั้งค่าเป็น 0 จะปิดใช้งานการตรวจสอบการหมดอายุ และจะถือว่าหมดอายุเสมอไป

ฟังการอัปเดตผ่าน EventEmitter

ลูกค้ายังเป็นผู้ปล่อยเหตุการณ์อีกด้วย ซึ่งหมายความว่าโค้ดของคุณสามารถสมัครรับการอัปเดตจากไคลเอ็นต์ได้ นี่เป็นวิธีที่เรียบร้อยในการอัปเดตแอปหน้าเดียวเมื่อสลับการอัปเดตสถานะ

 unleash . on ( 'update' , ( ) => {
    const myToggle = unleash . isEnabled ( 'proxy.demo' ) ;
    //do something useful
} ) ; 

กิจกรรมที่มีอยู่:

• error - เกิดขึ้นเมื่อเกิดข้อผิดพลาดใน init หรือเมื่อฟังก์ชันการดึงข้อมูลล้มเหลว หรือเมื่อการดึงข้อมูลได้รับออบเจ็กต์การตอบสนองที่ไม่โอเค ออบเจ็กต์ข้อผิดพลาดถูกส่งเป็นเพย์โหลด
• เริ่มต้น - ปล่อยออกมาหลังจากที่ SDK อ่านข้อมูลแคชในเครื่องใน storageProvider
• พร้อม - ปล่อยออกมาหลังจากที่ SDK เริ่มต้นได้สำเร็จและดำเนินการดึงข้อมูลแฟล็กเริ่มต้นผ่านเครือข่าย (Edge, พร็อกซี หรือ API ส่วนหน้า) เมื่อบูตสแตรป ไคลเอ็นต์สามารถปล่อยเหตุการณ์นี้สองครั้ง: หนึ่งครั้งเมื่อมีการโหลดแฟล็กบูตสแตรป และหนึ่งครั้งในการเชื่อมต่อที่สำเร็จครั้งแรกกับ Unleash
• อัปเดต - ปล่อยออกมาทุกครั้งที่ Unleash Proxy ส่งคืนการกำหนดค่าสลับคุณสมบัติใหม่ SDK จะส่งเหตุการณ์นี้โดยเป็นส่วนหนึ่งของการดึงข้อมูลครั้งแรกจาก SDK
• กู้คืนแล้ว - ปล่อยออกมาเมื่อ SDK กู้คืนจากข้อผิดพลาด เหตุการณ์นี้จะถูกส่งออกมาหาก SDK ได้ส่งข้อผิดพลาดก่อนหน้านี้เท่านั้น
• ส่ง - ปล่อยออกมาเมื่อ SDK ส่งการวัดไปยัง Unleash สำเร็จ

ปล.! โปรดจำไว้ว่าคุณควรลงทะเบียน event Listeners ของคุณก่อนที่จะโทรไปที่ unleash.start() หากคุณลงทะเบียนหลังจากที่คุณเริ่ม SDK แล้ว คุณจะเสี่ยงต่อการสูญเสียเหตุการณ์สำคัญ

SessionId - หมายเหตุสำคัญ!

คุณสามารถระบุรหัสเซสชันที่กำหนดเองผ่าน "บริบท" หากคุณไม่ได้ระบุรหัสเซสชัน SDK นี้จะสร้างรหัสเซสชันแบบสุ่ม ซึ่งจะถูกจัดเก็บไว้ในที่เก็บข้อมูลที่ให้มาด้วย (ที่เก็บข้อมูลในตัวเครื่อง) การมี sessionId ที่สอดคล้องกันอยู่เสมอทำให้มั่นใจได้ว่าแม้กระทั่งผู้ใช้ที่ "ไม่ระบุชื่อ" จะได้รับประสบการณ์ที่สอดคล้องกันเมื่อมีการประเมินการสลับคุณลักษณะ ร่วมกับการเปิดตัวแบบค่อยเป็นค่อยไป (ตามเปอร์เซ็นต์)

หยุด SDK

คุณสามารถหยุดไคลเอนต์ Unleash ได้โดยการเรียกเมธอด stop เมื่อไคลเอ็นต์หยุดทำงานแล้ว ไคลเอ็นต์จะไม่ตรวจสอบการอัปเดตหรือส่งการวัดไปยังเซิร์ฟเวอร์อีกต่อไป

ไคลเอนต์ที่หยุด สามารถ เริ่มต้นใหม่ได้

 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 ;
      }
    } ,
} ) ; 

วิธีการใช้งาน node.js

SDK นี้ยังใช้ในแอปพลิเคชัน node.js ได้ (ตั้งแต่เวอร์ชัน 1.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

วิธีการใช้งานไคลเอนต์ผ่าน CDN

 < 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 > 

บูทสแตรป

ตอนนี้คุณสามารถบูต SDK ด้วยการกำหนดค่าสลับคุณสมบัติของคุณเองได้ เมื่อคุณไม่ต้องการทำการเรียก API

นอกจากนี้ยังมีประโยชน์หากคุณต้องการให้ปุ่มสลับอยู่ในสถานะใดสถานะหนึ่งทันทีหลังจากเริ่มต้น SDK

วิธีการใช้งาน?

เพิ่มแอตทริบิวต์ bootstrap เมื่อสร้าง UnleashClient ใหม่
นอกจากนี้ยังมีแอตทริบิวต์ 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 (ตามค่าเริ่มต้น) ข้อมูลแคชในเครื่องจะถูกเขียนทับด้วย Bootstrap ที่ระบุ
หาก bootstrapOverride เป็น false ข้อมูลแคชในเครื่องจะไม่ถูกแทนที่ เว้นแต่ว่าแคชในเครื่องจะว่างเปล่า

จัดการกลไกการรีเฟรชของคุณเอง

คุณสามารถเลือกไม่ใช้กลไกการรีเฟรชอัตโนมัติและการอัปเดตตัววัดคุณลักษณะ Unleash ได้โดยตั้งค่าตัวเลือก refreshInterval และ/หรือ metricsInterval เป็น 0 ในกรณีนี้ ถือเป็นความรับผิดชอบของคุณในการเรียกเมธอด updateToggles และ/หรือ sendMetrics วิธีการนี้มีประโยชน์ในสภาพแวดล้อมที่ไม่รองรับ setInterval API เช่น พนักงานบริการ