FeatBit 客户端- Side SDK 用于 ReactJS
导言
这是功能管理平台的 React 客户端 SDK 费特比特。 。 。 .
要注意,这是客户端SDK,它打算用于单用户上下文,可以是移动,桌面或嵌入式应用程序. 此 SDK 只能在浏览器环境中运行, 不适合 React Industrial 项目 . 如果你要找回原生SDK 请检查这个 反应原生 SDK。 。 。 .
反应 SDK 基于 JavaScript SDK
React SDK基于FeatBit的JavaScript SDK,为React应用提供更好的集成. 因此,JavaScript SDK的大部分功能也可供React SDK使用.
SDK 版本兼容性
React SDK与16.3.0和更高版本的React兼容. 反应SDK提供两个自定义钩. 如果想要使用这些,则必须使用16.8.0或更高版本的React. 要学得更多,读一下这个 使用钩子。 。 。 .
与 Next.js 一起使用 如果您使用 Next.js 的 SDK 工程, 请注意 SDK 与服务器侧面渲染不兼容 。 你应该只用客户端的SDK. 如果您想在服务器侧使用 SDK, 请使用 @ featbit/ node-server-sdk (英语)。 。 。 .
开始
安装
npm install @featbit/react-client-sdk
先决条件
在使用SDK之前,需要获得环境秘密和SDK URL.
遵循以下文档获取这些值
快速启动
以下代码显示:
- 初始化 SDK
- 用用户 Flags 钩子评估旗帜
import { createRoot } from 'react-dom/client';
import { asyncWithFbProvider, useFlags, FbProvider } from '@featbit/react-client-sdk';
function Game() {
return (
<div>
This is a game
</div>
);
}
function APP() {
const flags = useFlags();
const gameEnabled = flags['game-enabled'];
return (
<div>
<div>{ gameEnabled ? <Game /> : <div>The game is not enabled</div>}</div>
</div>
);
}
(async () => {
const configWithAnonymousUser = {
options: {
user: {
name: 'the user name',
keyId: 'fb-demo-user-key',
customizedProperties: []
},
sdkKey: 'YOUR ENVIRONMENT SECRET',
streamingUri: 'THE STREAMING URL',
eventsUri: 'THE EVENTS URL'
}
};
const root = createRoot(document.getElementById('root'));
const Provider = await asyncWithFbProvider(configWithAnonymousUser);
root.render(
<Provider>
<Game />,
</Provider>
);
// Use the following code in React < 18.0.0
// ReactDOM.render(
// <FbProvider>
// <APP/>
// </FbProvider>,
// document.getElementById('root')
// );
})();
实例
SDK 软件
初始化 SDK
安装依赖后,初始化反应SDK. 你可以通过两种方式之一做到这一点:
- 使用
asyncWithFbProvider函数 - 使用
withFbProvider函数
两者都依赖于 React 的上下文 API , 它允许您从组件等级的任意级别访问您的旗帜 .
使用 asyncWithFb 提供初始化
这个 asyncWithFbProvider 函数初始化 React SDK 并返回作为 React 组件的提供者。 这是一种主动函数。 它接受一个 ProviderConfig 对象.
asyncWithFbProvider 不能推迟。 你必须初始化 asyncWithFbProvider 在渲染前的应用程序入口处,以确保旗子和客户端在应用程序开始时就绪.
import { createRoot } from 'react-dom/client';
import { asyncWithFbProvider } from '@featbit/react-client-sdk';
(async () => {
const config = {
options: {
sdkKey: 'YOUR ENVIRONMENT SECRET',
streamingUri: 'THE STREAMING URL',
eventsUri: 'THE EVENTS URL',
user: {
name: 'USER NAME',
keyId: 'USER ID',
customizedProperties: [
{
"name": "age",
"value": '18'
}
]
}
}
}
const root = createRoot(document.getElementById('root'));
const FbProvider = await asyncWithFbProvider(config);
root.render(
<FbProvider>
<YourApp />,
</FbProvider>
);
})();
在初始化完成后, 您的旗帜和客户端可以在您的 React app 生命周期开始时使用 。 这将确保您的应用程序不会因为启动时的旗帜更改而闪烁 .
渲染可能会被延迟
由于 AsyncWithFb Provider 函数是同步的,您的 React app 的渲染被延后到初始化完成. 这最多需要100毫秒,但往往更早完成. 或者,如果您喜欢先制作您的应用程序,然后在渲染完成后处理旗帜更新,您也可以使用带有FbProvider功能.
此函数需要回放 16. 8.0 或稍后
ASyncWithFbProvider功能使用Hooks API,它需要回放16.8.0版本或更后.
以 Fb 创建初始化
这个 withFbProvider 函数初始化 React SDK ,并将根组件包入 2. 背景情况。 提供者它接受 ProviderConfig 用于配置 React SDK 的对象.
import { withFbProvider } from '@featbit/react-client-sdk';
const config = {
options: {
sdkKey: 'YOUR ENVIRONMENT SECRET',
streamingUri: 'THE STREAMING URL',
eventsUri: 'THE EVENTS URL',
user: {
name: 'USER NAME',
keyId: 'USER ID',
customizedProperties: [
{
"name": "age",
"value": '18'
}
]
}
}
};
export default withFbProvider(config)(YourApp);
订阅标记更改
React SDK 自动订阅国旗更改事件. 这与JavaScript SDK不同,客户需要选择参与事件监听.
配置反应 SDK
这个 ProviderConfig 对象为两者提供配置 withFbProvider 财务报告和审定财务报表 asyncWithFbProvider 函数.
唯一的强制性财产是 选项,这是初始化 @featbit/js-client-sdk。了解更多关于 选项请参考 @ featbit/js-客户端-sdk。所有其他属性都与 SDK 相关.
现有属性的完整列表 :
-
选项: 初始化配置
@featbit/js-client-sdk。 。 。 . 强制你可以用这个 选项 选项以默认值填充 SDK.
-
反应选项: 您可以使用此选项, 在使用 React SDK 时启用旗下键的自动骆驼外壳 。 默认值为虚假 非强制性
-
推迟: 此属性允许 SDK 初始化被推迟, 直到您定义 fbClient 属性 。 默认值为虚假 非强制性
asyncWithFb 提供器不支持延迟初始化 。 在渲染前, 您必须在应用程序入口处初始化 asyncWithFb 提供 , 以确保您的应用程序开始时客户端准备好 .
通过推迟SDK初始化,您会推迟作为SDK初始化的一部分而进行的所有步骤,包括从本地存储中读取旗帜值并发送SDK的已准备好事件.
这个规则的一个例外是,只要将被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖住的被拖走的被拖住的被拖住的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走的被拖走. 如果您表示SDK应该从本地存储中拖出拖曳旗,则在SDK初始化前不会发生.
以下是包含上述每个属性的提供方对象:
{
options: {
sdkKey: 'YOUR ENVIRONMENT SECRET',
streamingUri: 'THE STREAMING URL',
eventsUri: 'THE EVENTS URL',
user: {
name: 'USER NAME',
keyId: 'USER ID',
customizedProperties: [
{
"name": "age",
"value": '18'
}
]
}
...
},
reactOptions: {
useCamelCaseFlagKeys: false
},
deferInitialization: false
}
正在使用旗子
在类组中悬挂旗帜
有两种方法可以消耗旗帜.
使用上下文Type属性
import { context } from '@featbit/react-client-sdk';
class MyComponent extends React.Component {
static contextType = context;
constructor(props) {
super(props);
}
render() {
const { flags } = this.context;
return (
<div>{ flags['dev-test-flag'] ? 'Flag on' : 'Flag off' }</div>
)
}
}
export default MyComponent;
使用 Fb 客户端
与 FbConcumer 的还原值是一个将您组件取回并返回以旗帜和 fbClient 作为道具注入的 React 组件的折叠函数 .
import { withFbConsumer } from '@featbit/react-client-sdk';
class MyComponent extends React.Component {
render() {
const { flags } = this.props;
return (
<div>
<div>{flags.flag1}</div>
</div>
);
}
}
export default withFbConsumer()(Board)
在函数组件中使用标记
有两种方法可以消耗旗帜.
使用 Fb 客户端
与 FbConcumer 的还原值是一个将您组件取回并返回以旗帜和 fbClient 作为道具注入的 React 组件的折叠函数 .
import { withFbConsumer } from '@featbit/react-client-sdk';
const Home = ({ flags, fbClient /*, ...otherProps */ }) => {
// You can call any of the methods from the JavaScript SDK
// fbClient.identify({...})
return flags['dev-test-flag'] ? <div>Flag on</div> : <div>Flag off</div>;
};
export default withFbConsumer()(Home);
使用钩子
React SDK 提供了两个自定义的钩子,您可以用来替代 withFbConsumer数字 :
useFlagsuseFbClient
这些功能需要回放 16.8.0 或稍后
使用Flags并使用FbClient使用Hooks API,需要16.8.0或更晚的回放版本.
使用 Flags 是自定义的钩子, 它返回所有特征旗 。 它使用Context原始来访问由AsyncWithFbProvider或与FbProvider所设置的FeatBit上下文. 您仍然必须在您的应用程序根部使用 asyncWithFb Provider 或 与 Fb 提供更高排序组件来初始化 React SDK 并用 fbClient 和您的旗帜来填充上下文 .
使用FbClient 是返回 FeatBit 基本 JavaScript SDK 客户端对象的第二个自定义钩头 。 和使用Flags自定义钩一样,使用FbClient也使用使用Context原始来访问由AsyncWithFbProvider或与FbProvider所设置的上下文. 您仍必须使用 AsyncWithFb Provider 或用 Fb 提供更高顺序的组件来初始化 React SDK 才能使用此自定义钩子 .
以下是如何使用这两个钩子的例子:
import { useFlags, useFbClient } from '@featbit/react-client-sdk';
const MyComponent = props => {
const fbClient = useFbClient();
const { flag1, flag2 } = useFlags();
// or use
const flags = useFlags();
// then use flags.flag1 or flags['flag1'] to reference the flag1 feature flag
return (
<div>
<div>1: {flag1}</div>
<div>2: {flag2}</div>
</div>
);
};
export default MyComponent;
初始化后切换用户
如果用户在初始化期间不可用,您可以拨打 身份( ) 方法打开 fb 密度 设置初始化后的用户.
在类组件中切换用户
import { withFbConsumer, useFbClient } from '@featbit/react-client-sdk';
class LoginComponent extends React.Component {
handleLogin = async () => {
const { fbClient } = this.props;
const user = {}; // use your user object
await fbClient.identify(user);
}
render() {
return (
<div>
<button onClick={this.handleLogin}>Login</button>
</div>
);
}
}
export default withFbConsumer()(LoginComponent)
在函数组件中切换用户
import { useFbClient } from '@featbit/react-client-sdk';
const LoginComponent = () => {
const fbClient = useFbClient();
handleLogin = async () => {
const user = {}; // use your user object
await fbClient.identify(user);
}
return (
<div>
<button onClick={handleLogin}>Login</button>
</div>
);
}
SDK 以倒挂旗标值填充
如上所述,你可以使用 选项 选项以默认值填充 SDK 。 如果您想要在 SDK 初始化前为您的旗帜提供默认值, 此选项是有用的 . 如果无法从 SDK 中获取一面旗帜, SDK 将使用您在靴子夹对象中提供的默认值 .
options: {
bootstrap: [
{
"id": "my-flag",
"variation": "on"
},
{
"id": "second-flag",
"variation": "AlphaGo"
}
]
}
旗下密钥
费特 Bit主要用密钥识别特征标记, 密钥必须只包含字母字符, 点 (.), 下划线 ( ), 和分线 (-) 。 这些密钥被用于我们所有API以及SDK识别旗帜.
然而, JavaScript 和 React 无法使用点标记访问密钥, 因此 React SDK 可以将所有旗下密钥更改为骆驼大小写( 您需要用 反应可选. useCamelCaseFlagKeys 参数). 有密钥的旗帜 dev-flag-test 以 flags.devFlagTest。此标记 旗帜 ['dev-flag-test'] 如果禁用CamelCaseFlagKeys,则应当使用,默认禁用.
请注意,通过激活使用CamelCaseFlagKeys,你会看到以下问题:
- 如果有多个标记键决定同一个骆驼箱键,则可能诱发密钥相撞。 譬如说,
dev-flag-test财务报告和审定财务报表dev.flag.test是独一无二的密钥, 但是反应 SDK 把它们修改为相同的驼峰大小写密钥 . - 如果一行中有3个或更多个大写字母,SDK会自动将第一个和最后一个大写字母之间的所有字母转换为小写. 例如, SDK 转换带有密钥的旗帜
devQAFlagTest改为devQaFlagTest。如果使用devQAFlag Test with the use Flags () hook,则SDK找不到旗帜. - 因为骆驼案的功能是在React SDK中而不是在基础的JavaScript SDK中被执行的,所以由JavaScript SDK提供的基础客户对象和功能会以原始格式反映旗帜密钥. 只有像您注射道具这样的特定反应环境使用骆驼箱.
如果您启用了 CamelCaseFlagKeys 选项, 尝试使用其原始密钥访问一面旗帜将会在控制台触发警告信息 : 你试图用它的原始键盘访问一面旗帜:xxx,尽管使用CamelCaseFlagKeys是设定为真实的.
导入类型
除了自己的捆绑类型外,React SDK还使用来自 @featbit/js-client-sdk,这些类型由React SDK再出口. 您可以直接从 React SDK 导入这些类型