unleash proxy client js
v3.6.1
عميل وكيل JavaScript هو عميل Unleash صغير الحجم مكتوب بلغة JavaScript دون أي تبعيات خارجية (باستثناء واجهات برمجة تطبيقات المتصفح). يقوم هذا العميل بتخزين التبديلات ذات الصلة بالمستخدم الحالي في localStorage ويتزامن مع Unleash (واجهة برمجة تطبيقات الواجهة الأمامية لـ Unleash أو وكيل Unleash) في الخلفية. نظرًا لأنه يتم تخزين مفاتيح التبديل في متصفح المستخدم، يمكن للعميل استخدامها لتمهيد نفسه في المرة التالية التي يزور فيها المستخدم نفس صفحة الويب.
يتوقع هذا العميل أن يكون fetch متاحًا. إذا كنت بحاجة إلى دعم المتصفحات القديمة، فمن المحتمل أن تستخدم ملف الجلب polyfill.
هذه الحزمة ليست مرتبطة بأي إطار عمل، ولكن يمكن استخدامها معًا مع أطر العمل الأكثر شيوعًا، على سبيل المثال:
npm install unleash - proxy - clientتلميح : باعتبارها حزمة SDK من جانب العميل، تتطلب منك حزمة SDK هذه الاتصال إما بوكيل Unleash أو بواجهة برمجة التطبيقات الأمامية لـ Unleash. راجع قسم خيارات الاتصال لمزيد من المعلومات.
تكوين العميل وفقا لاحتياجاتك. يوفر المثال التالي الخيارات المطلوبة فقط. راجع القسم الخاص بالخيارات المتاحة للحصول على القائمة الكاملة.
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، استخدم عنوان URL لواجهة برمجة التطبيقات الأمامية لمثيل Unleash ( <unleash-url>/api/frontend ) كمعلمة url . بالنسبة لمعلمة clientKey ، استخدم رمز FRONTEND الذي تم إنشاؤه من مثيل Unleash الخاص بك. راجع كيفية إنشاء دليل الرموز المميزة لواجهة برمجة التطبيقات للتعرف على الخطوات الضرورية.
لتوصيل SDK هذا بوكيل Unleash، استخدم عنوان URL للوكيل ومفتاح عميل الوكيل. يحتوي قسم التكوين في مستندات Unleash proxy على مزيد من المعلومات حول كيفية تكوين مفاتيح العميل للوكيل الخاص بك.
يجب عليك انتظار الأحداث 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 لتقييم الميزات مقابل سمات المستخدم الحالي. لتحديث سياق Unleash وتكوينه في SDK هذا، استخدم أساليب updateContext و setContextField و removeContextField .
سيتم تمرير السياق الذي قمت بتعيينه في تطبيقك إلى وكيل Unleash أو واجهة برمجة التطبيقات للواجهة الأمامية كمعلمات استعلام لتقييم الميزات.
ستستبدل طريقة 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 | نعم | غير متوفر | عنوان URL الخاص بـ Unleash Proxy للاتصال به. على سبيل المثال: https://examples.com/proxy |
| ClientKey | نعم | غير متوفر | إطلاق العنان للوكيل السري ليتم استخدامه |
| اسم التطبيق | نعم | غير متوفر | اسم التطبيق الذي يستخدم SDK هذا. سيتم استخدامها كجزء من المقاييس المرسلة إلى Unleash Proxy. سيكون أيضًا جزءًا من سياق إطلاق العنان. |
| سياق | لا | {} | سياق إطلاق العنان الأولي. سيتم استخدام هذا كسياق أولي لجميع تقييمات تبديل الميزات. سيتم تعبئة خيارات appName environment تلقائيًا بالقيم التي تمررها لهذه الخيارات. |
| refreshInterval | لا | 30 | عدد المرات، بالثواني، التي يجب أن يتحقق فيها SDK من تكوين التبديل المحدث. إذا تم التعيين على 0 فسيتم تعطيل البحث عن التحديثات |
| DisableRefresh | لا | false | إذا تم التعيين على "صحيح"، فلن يتحقق العميل من تكوين التبديل المحدث |
| metricsInterval | لا | 60 | كم مرة، بالثواني، يجب على SDK إرسال مقاييس الاستخدام مرة أخرى إلى Unleash Proxy. سيتم البدء بعد تقرير المقاييس الأولية، والذي يتم إرساله بعد metricsIntervalInitial الذي تم تكوينه |
| metricsIntervalInitial | لا | 2 | المدة التي يجب أن تنتظرها SDK حتى يعود تقرير المقاييس الأول إلى Unleash API. إذا كنت تريد تعطيل استدعاء المقاييس الأولية، فيمكنك ضبطه على 0. |
| this.disableMetrics | لا | false | اضبط هذا الخيار على true إذا كنت تريد تعطيل مقاييس الاستخدام |
| StorageProvider | لا | LocalStorageProvider في المتصفح، InMemoryStorageProvider بخلاف ذلك | يسمح لك بإدخال storeProvider مخصص |
| أحضر | لا | window.fetch أو fetch الشامل | يسمح لك بتجاوز تنفيذ الجلب للاستخدام. مفيد في بيئات Node.js حيث يمكنك إدخال node-fetch |
| createAbortController | لا | () => new AbortController() | يسمح لك بتجاوز إنشاء AbortController الافتراضي. يستخدم لإلغاء الطلبات ذات السياق القديم. اضبطه على () => null إذا كنت لا تريد التعامل معه. |
| bootstrap | لا | [] | يسمح لك بتمهيد تكوين تبديل الميزة المخزنة مؤقتًا. |
| bootstrapOverride | لا | true | هل يجب أن يتجاوز التمهيد تلقائيًا البيانات المخزنة مؤقتًا في وحدة التخزين المحلية. لن يتم استخدامه إلا إذا لم يكن bootstrap مصفوفة فارغة. |
| headerName | لا | Authorization | ما هو الرأس الذي يجب أن يستخدمه SDK للتفويض باستخدام Unleash / Unleash Proxy. سيتم إعطاء الرأس مفتاح clientKey كقيمة له. |
| customHeaders | لا | {} | رؤوس إضافية لاستخدامها عند تقديم طلبات HTTP إلى وكيل Unleash. في حالة تضارب الأسماء مع الرؤوس الافتراضية، سيتم استخدام قيمة customHeaders إذا لم تكن null أو undefined . سيتم تجاهل قيم customHeaders null أو undefined . |
| ImpressionDataAll | لا | false | يسمح لك بتشغيل أحداث "الظهور" لجميع استدعاءات getToggle و getVariant . يعد هذا مفيدًا بشكل خاص لتبديل الميزات "المعطلة" غير المرئية لمجموعات SDK للواجهة الأمامية. |
| بيئة | لا | default | يضبط خيار environment لسياق Unleash. لا يؤثر هذا على بيئة Unleash الخاصة بـ SDK. |
| usePOSTrequests | لا | false | تكوين العميل لاستخدام طلبات POST بدلاً من GET عند طلب الميزات الممكّنة. يكون هذا مفيدًا عند تمرير معلومات حساسة (مثل البريد الإلكتروني للمستخدم، عند استخدامه كمعرف مستخدم) في السياق لتجنب تسربها في عنوان URL. ملاحظة: طلبات النشر غير مدعومة من خلال واجهة برمجة تطبيقات الواجهة الأمامية المضمنة في Unleash. |
| تجريبي | لا | {} | تمكين التجريب الاختياري. togglesStorageTTL : المدة (مدة البقاء)، بالثواني، تعتبر عمليات التبديل في التخزين صالحة ويجب عدم جلبها عند البداية. إذا تم التعيين على 0، فسيتم تعطيل التحقق من انتهاء الصلاحية وسيتم اعتباره منتهي الصلاحية دائمًا. |
العميل هو أيضًا باعث للحدث. هذا يعني أن الكود الخاص بك يمكنه الاشتراك في التحديثات من العميل. هذه طريقة رائعة لتحديث تطبيق من صفحة واحدة عند تبديل تحديثات الحالة.
unleash . on ( 'update' , ( ) => {
const myToggle = unleash . isEnabled ( 'proxy.demo' ) ;
//do something useful
} ) ; ملاحظة! يرجى تذكر أنه يجب عليك دائمًا تسجيل مستمعي الأحداث قبل مكالمتك
unleash.start(). إذا قمت بتسجيلها بعد بدء تشغيل SDK، فإنك تخاطر بفقدان الأحداث المهمة.
يمكنك تقديم معرف جلسة مخصص عبر "السياق". إذا لم تقم بتوفير معرف الجلسة، فسيقوم SDK هذا بإنشاء معرف جلسة عشوائي، والذي سيتم تخزينه أيضًا في وحدة التخزين المتوفرة (التخزين المحلي). من خلال توفر معرف جلسة متسق دائمًا، يضمن أنه حتى المستخدمين "المجهولين" سيحصلون على تجربة متسقة عند تقييم تبديل الميزات، بالإضافة إلى الطرح التدريجي (المعتمد على النسبة المئوية).
يمكنك إيقاف عميل Unleash عن طريق استدعاء طريقة stop . بمجرد إيقاف العميل، لن يقوم بعد ذلك بالبحث عن التحديثات أو إرسال المقاييس إلى الخادم.
يمكن إعادة تشغيل العميل المتوقف.
unleash . stop ( )يمكن أن يعمل SDK هذا مع تخزين React Native @react-native-async-storage/async-storage أو تفضيلات رد الفعل الأصلية المشتركة وغيرها الكثير لتبديل ميزات النسخ الاحتياطي محليًا. يعد هذا مفيدًا لبدء تشغيل 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 (من الإصدار 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 ) ;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 > أصبح من الممكن الآن تشغيل حزمة 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 ، مثل العاملين في مجال الخدمة.
