@optimizely/react-sdk
v3.2.2
Published
React SDK for Optimizely Feature Experimentation, Optimizely Full Stack (legacy), and Optimizely Rollouts
Downloads
449,920
Readme
Optimizely React SDK
This repository houses the React SDK for use with Optimizely Feature Experimentation and Optimizely Full Stack (legacy).
Optimizely Feature Experimentation is an A/B testing and feature management tool for product development teams that enables you to experiment at every step. Using Optimizely Feature Experimentation allows for every feature on your roadmap to be an opportunity to discover hidden insights. Learn more at Optimizely.com, or see the developer documentation.
Optimizely Rollouts is free feature flags for development teams. You can easily roll out and roll back features in any application without code deploys, mitigating risk for every feature on your roadmap.
Get Started
Refer to the React SDK's developer documentation for detailed instructions on getting started with using the SDK.
For React Native, review the React Native developer documentation for installation and implementation detail.
Features
- Automatic datafile downloading
- User ID + attributes memoization
- Render blocking until datafile is ready via a React API
- Optimizely timeout (only block rendering up to the number of milliseconds you specify)
- Library of React components and hooks to use with feature flags
Compatibility
The React SDK is compatible with React 16.8.0 +
Example
import {
createInstance,
OptimizelyProvider,
useDecision,
} from '@optimizely/react-sdk';
const optimizelyClient = createInstance({
sdkKey: 'your-optimizely-sdk-key',
});
function MyComponent() {
const [decision] = useDecision('sort-algorithm');
return (
<React.Fragment>
<SearchComponent algorithm={decision.variables.algorithm} />
{ decision.variationKey === 'relevant_first' && <RelevantFirstList /> }
{ decision.variationKey === 'recent_first' && <RecentFirstList /> }
</React.Fragment>
);
}
class App extends React.Component {
render() {
return (
<OptimizelyProvider
optimizely={optimizelyClient}
timeout={500}
user={{ id: window.userId, attributes: { plan_type: 'bronze' } }}
>
<MyComponent />
</OptimizelyProvider>
);
}
}
Install the SDK
npm install @optimizely/react-sdk
Use the React SDK
Initialization
createInstance
The ReactSDKClient
client created via createInstance
is the programmatic API to evaluating features and experiments and tracking events. The ReactSDKClient
is what powers the rest of the ReactSDK internally.
arguments
config : object
Object with SDK configuration parameters. This has the same format as the object passed to thecreateInstance
method of the core@optimizely/javascript-sdk
module. For details on this object, see the following pages from the developer docs:
returns
- A
ReactSDKClient
instance.
import { OptimizelyProvider, createInstance } from '@optimizely/react-sdk';
const optimizely = createInstance({
datafile: window.optimizelyDatafile,
});
<OptimizelyProvider>
Required at the root level. Leverages React’s Context
API to allow access to the ReactSDKClient
to the useDecision
hook.
props
optimizely : ReactSDKClient
created fromcreateInstance
user: { id: string; attributes?: { [key: string]: any } } | Promise
User info object -id
andattributes
will be passed to the SDK for every feature flag, A/B test, ortrack
call, or aPromise
for the same kind of objecttimeout : Number
(optional) The amount of time foruseDecision
to returnnull
flag Decision while waiting for the SDK instance to become ready, before resolving.isServerSide : Boolean
(optional) must passtrue
here for server side renderinguserId : String
(optional) Deprecated, prefer usinguser
instead. Another way to provide user id. Theuser
object prop takes precedence when both are provided.userAttributes : Object
: (optional) Deprecated, prefer usinguser
instead. Another way to provide user attributes. Theuser
object prop takes precedence when both are provided.
Readiness
Before rendering real content, both the datafile and the user must be available to the SDK.
Load the datafile synchronously
Synchronous loading is the preferred method to ensure that Optimizely is always ready and doesn't add any delay or asynchronous complexity to your application. When initializing with both the SDK key and datafile, the SDK will use the given datafile to start, then download the latest version of the datafile in the background.
import { OptimizelyProvider, createInstance } from '@optimizely/react-sdk';
const optimizelyClient = createInstance({
datafile: window.optimizelyDatafile,
sdkKey: 'your-optimizely-sdk-key', // Optimizely environment key
});
class AppWrapper extends React.Component {
render() {
return (
<OptimizelyProvider optimizely={optimizelyClient} user={{ id: window.userId }}>
<App />
</OptimizelyProvider>
);
}
}
Load the datafile asynchronously
If you don't have the datafile downloaded, the ReactSDKClient
can fetch the datafile for you. However, instead of waiting for the datafile to fetch before you render your app, you can immediately render your app and provide a timeout
option to <OptimizelyProvider optimizely={optimizely} timeout={200}>
. The useDecision
hook returns isClientReady
and didTimeout
. You can use these to block rendering of component until the datafile loads or the timeout is over.
import { OptimizelyProvider, createInstance, useDecision } from '@optimizely/react-sdk';
const optimizelyClient = createInstance({
sdkKey: 'your-optimizely-sdk-key', // Optimizely environment key
});
function MyComponent() {
const [decision, isClientReady, didTimeout] = useDecision('the-flag');
return (
<React.Fragment>
{ isClientReady && <div>The Component</div> }
{ didTimeout && <div>Default Component</div>}
{ /* If client is not ready and time out has not occured yet, do not render anything */ }
</React.Fragment>
);
}
class App extends React.Component {
render() {
return (
<OptimizelyProvider
optimizely={optimizelyClient}
timeout={500}
user={{ id: window.userId, attributes: { plan_type: 'bronze' } }}
>
<MyComponent />
</OptimizelyProvider>
);
}
}
Set user asynchronously
If user information is synchronously available, it can be provided as the user
object prop, as in prior examples. But, if user information must be fetched asynchronously, the user
prop can be a Promise
for a user
object with the same properties (id
and attributes
):
import { OptimizelyProvider, createInstance } from '@optimizely/react-sdk';
import { fetchUser } from './user';
const optimizely = createInstance({
datafile: window.optimizelyDatafile,
});
const userPromise = fetchUser(); // fetchUser returns a Promise for an object with { id, attributes }
class AppWrapper extends React.Component {
render() {
return (
<OptimizelyProvider optimizely={optimizely} user={userPromise}>
<App />
</OptimizelyProvider>
);
}
}
useDecision
Hook
A React Hook to retrieve the decision result for a flag key, optionally auto updating that decision based on underlying user or datafile changes.
arguments
flagKey : string
The key of the feature flag.options : Object
autoUpdate : boolean
(optional) If true, this hook will update the flag decision in response to datafile or user changes. Default:false
.timeout : number
(optional) Client timeout as described in theOptimizelyProvider
section. Overrides any timeout set on the ancestorOptimizelyProvider
.decideOption: OptimizelyDecideOption[]
(optional) Array of OptimizelyDecideOption enums.
overrides : Object
overrideUserId : string
(optional) Override the userId to be used to obtain the decision result for this hook.overrideAttributes : optimizely.UserAttributes
(optional) Override the user attributes to be used to obtain the decision result for this hook.
returns
Array
of:decision : OptimizelyDecision
- Decision result for the flag key.clientReady : boolean
- Whether or not the underlyingReactSDKClient
instance is ready or not.didTimeout : boolean
- Whether or not the underlyingReactSDKClient
became ready within the allowedtimeout
range.
Note:
clientReady
can be true even ifdidTimeout
is also true. This indicates that the client became ready after the timeout period.
Render something if flag is enabled
import { useEffect } from 'react';
import { useDecision } from '@optimizely/react-sdk';
function LoginComponent() {
const [decision, clientReady] = useDecision(
'login-flag',
{ autoUpdate: true },
{
/* (Optional) User overrides */
}
);
useEffect(() => {
document.title = decision.enabled ? 'login-new' : 'login-default';
}, [decision.enabled]);
return (
<p>
<a href={decision.enabled ? '/login-new' : '/login-default'}>Click to login</a>
</p>
);
}
withOptimizely
Any component under the <OptimizelyProvider>
can access the Optimizely ReactSDKClient
via the higher-order component (HoC) withOptimizely
.
arguments
Component : React.Component
Component which will be enhanced with the following props:optimizely : ReactSDKClient
The client object which was passed to theOptimizelyProvider
optimizelyReadyTimeout : number | undefined
The timeout which was passed to theOptimizelyProvider
isServerSide : boolean
Value that was passed to theOptimizelyProvider
returns
- A wrapped component with additional props as described above
Example
import { withOptimizely } from '@optimizely/react-sdk';
class MyComp extends React.Component {
constructor(props) {
super(props);
const { optimizely } = this.props;
const decision = optimizely.decide('feat1');
this.state = {
decision.enabled,
decision.variables,
};
}
render() {}
}
const WrappedMyComponent = withOptimizely(MyComp);
Note: The optimizely
client object provided via withOptimizely
is automatically associated with the user
prop passed to the ancestor OptimizelyProvider
- the id
and attributes
from that user
object will be automatically forwarded to all appropriate SDK method calls. So, there is no need to pass the userId
or attributes
arguments when calling methods of the optimizely
client object, unless you wish to use different userId
or attributes
than those given to OptimizelyProvider
.
useContext
Any component under the <OptimizelyProvider>
can access the Optimizely ReactSDKClient
via the OptimizelyContext
with useContext
.
arguments
OptimizelyContext : React.Context<OptimizelyContextInterface>
The Optimizely context initialized in a parent component (or App).
returns
- Wrapped object:
optimizely : ReactSDKClient
The client object which was passed to theOptimizelyProvider
isServerSide : boolean
Value that was passed to theOptimizelyProvider
timeout : number | undefined
The timeout which was passed to theOptimizelyProvider
Example
import React, { useContext } from 'react';
import { OptimizelyContext } from '@optimizely/react-sdk';
function MyComponent() {
const { optimizely, isServerSide, timeout } = useContext(OptimizelyContext);
const decision = optimizely.decide('my-feature');
const onClick = () => {
optimizely.track('signup-clicked');
// rest of your click handling code
};
return (
<>
{ decision.enabled && <p>My feature is enabled</p> }
{ !decision.enabled && <p>My feature is disabled</p> }
{ decision.variationKey === 'control-variation' && <p>Current Variation</p> }
{ decision.variationKey === 'experimental-variation' && <p>Better Variation</p> }
<button onClick={onClick}>Sign Up!</button>
</>
);
}
Tracking
Use the built-in useTrackEvent
hook to access the track
method of optimizely instance
import { useTrackEvent } from '@optimizely/react-sdk';
function SignupButton() {
const [track, clientReady, didTimeout] = useTrackEvent()
const handleClick = () => {
if(clientReady) {
track('signup-clicked')
}
}
return (
<button onClick={handleClick}>Signup</button>
)
}
Or you can use the withOptimizely
HoC.
import { withOptimizely } from '@optimizely/react-sdk';
class SignupButton extends React.Component {
onClick = () => {
const { optimizely } = this.props;
optimizely.track('signup-clicked');
// rest of click handler
};
render() {
<button onClick={this.onClick}>Signup</button>;
}
}
const WrappedSignupButton = withOptimizely(SignupButton);
Note: As mentioned above, the optimizely
client object provided via withOptimizely
is automatically associated with the user
prop passed to the ancestor OptimizelyProvider.
There is no need to pass userId
or attributes
arguments when calling track
, unless you wish to use different userId
or attributes
than those given to OptimizelyProvider
.
ReactSDKClient
The following type definitions are used in the ReactSDKClient
interface:
UserAttributes : { [name: string]: any }
User : { id: string | null, attributes: userAttributes }
VariableValuesObject : { [key: string]: any }
EventTags : { [key: string]: string | number | boolean; }
ReactSDKClient
instances have the methods/properties listed below. Note that in general, the API largely matches that of the core @optimizely/optimizely-sdk
client instance, which is documented on the Optimizely Feature Experimentation developer docs site. The major exception is that, for most methods, user id & attributes are optional arguments. ReactSDKClient
has a current user. This user's id & attributes are automatically applied to all method calls, and overrides can be provided as arguments to these method calls if desired.
onReady(opts?: { timeout?: number }): Promise<onReadyResult>
Returns a Promise that fulfills with anonReadyResult
object representing the initialization process. The instance is ready when it has fetched a datafile and a user is available (viasetUser
being called with an object, or a Promise passed tosetUser
becoming fulfilled). If thetimeout
period happens before the client instance is ready, theonReadyResult
object will contain an additional key,dataReadyPromise
, which can be used to determine when, if ever, the instance does become ready.user: User
The current user associated with this client instancesetUser(userInfo: User | Promise<User>): void
Call this to update the current useronUserUpdate(handler: (userInfo: User) => void): () => void
Subscribe a callback to be called when this instance's current user changes. Returns a function that will unsubscribe the callback.decide(key: string, options?: optimizely.OptimizelyDecideOption[], overrideUserId?: string, overrideAttributes?: optimizely.UserAttributes): OptimizelyDecision
Returns a decision result for a flag key for a user. The decision result is returned in an OptimizelyDecision object, and contains all data required to deliver the flag rule.decideAll(options?: optimizely.OptimizelyDecideOption[], overrideUserId?: string, overrideAttributes?: optimizely.UserAttributes): { [key: string]: OptimizelyDecision }
Returns decisions for all active (unarchived) flags for a user.decideForKeys(keys: string[], options?: optimizely.OptimizelyDecideOption[], overrideUserId?: string, overrideAttributes?: optimizely.UserAttributes): { [key: string]: OptimizelyDecision }
Returns an object of decision results mapped by flag keys.activate(experimentKey: string, overrideUserId?: string, overrideAttributes?: UserAttributes): string | null
Activate an experiment, and return the variation for the given user.getVariation(experimentKey: string, overrideUserId?: string, overrideAttributes?: UserAttributes): string | null
Return the variation for the given experiment and user.getFeatureVariables(featureKey: string, overrideUserId?: string, overrideAttributes?: UserAttributes): VariableValuesObject
: Decide and return variable values for the given feature and user Warning: Deprecated since 2.1.0getAllFeatureVariables
is added in JavaScript SDK which is similarly returning all the feature variables, but it sends only single notification of typeall-feature-variables
instead of sending for each variable. AsgetFeatureVariables
was added when this functionality wasn't provided byJavaScript SDK
, so there is no need of it now and it would be removed in next major releasegetFeatureVariableString(featureKey: string, variableKey: string, overrideUserId?: string, overrideAttributes?: optimizely.UserAttributes): string | null
: Decide and return the variable value for the given feature, variable, and usergetFeatureVariableInteger(featureKey: string, variableKey: string, overrideUserId?: string, overrideAttributes?: UserAttributes): number | null
Decide and return the variable value for the given feature, variable, and usergetFeatureVariableBoolean(featureKey: string, variableKey: string, overrideUserId?: string, overrideAttributes?: UserAttributes): boolean | null
Decide and return the variable value for the given feature, variable, and usergetFeatureVariableDouble(featureKey: string, variableKey: string, overrideUserId?: string, overrideAttributes?: UserAttributes): number | null
Decide and return the variable value for the given feature, variable, and userisFeatureEnabled(featureKey: string, overrideUserId?: string, overrideAttributes?: UserAttributes): boolean
Return the enabled status for the given feature and usergetEnabledFeatures(overrideUserId?: string, overrideAttributes?: UserAttributes): Array<string>
: Return the keys of all features enabled for the given usertrack(eventKey: string, overrideUserId?: string | EventTags, overrideAttributes?: UserAttributes, eventTags?: EventTags): void
Track an event to the Optimizely results backendsetForcedVariation(experiment: string, overrideUserIdOrVariationKey: string, variationKey?: string | null): boolean
Set a forced variation for the given experiment, variation, and user. Note: callingsetForcedVariation
on a given client will trigger a re-render of alluseExperiment
hooks andOptimizelyExperiment
components that are using that client.getForcedVariation(experiment: string, overrideUserId?: string): string | null
Get the forced variation for the given experiment, variation, and user
Rollout or experiment a feature user-by-user
To rollout or experiment on a feature by user rather than by random percentage, you will use Attributes and Audiences. To do this, follow the documentation on how to run a beta using the React code samples.
Server Side Rendering
Right now server side rendering is possible with a few caveats.
Caveats
You must download the datafile manually and pass in via the
datafile
option. Can not usesdkKey
to automatically download.Rendering of components must be completely synchronous (this is true for all server side rendering), thus the Optimizely SDK assumes that the optimizely client has been instantiated and fired it's
onReady
event already.
Setting up <OptimizelyProvider>
Similar to browser side rendering you will need to wrap your app (or portion of the app using Optimizely) in the <OptimizelyProvider>
component. A new prop
isServerSide
must be equal to true.
<OptimizelyProvider optimizely={optimizely} user={{ id: 'user1' }} isServerSide={true}>
<App />
</OptimizelyProvider>
All other Optimizely components, such as <OptimizelyFeature>
and <OptimizelyExperiment>
can remain the same.
Full example
import * as React from 'react';
import * as ReactDOMServer from 'react-dom/server';
import {
createInstance,
OptimizelyProvider,
useDecision,
} from '@optimizely/react-sdk';
const fetch = require('node-fetch');
function MyComponent() {
const [decision] = useDecision('flag1');
return (
<React.Fragment>
{ decision.enabled && <p>The feature is enabled</p> }
{ !decision.enabled && <p>The feature is not enabled</p> }
{ decision.variationKey === 'variation1' && <p>Variation 1</p> }
{ decision.variationKey === 'variation2' && <p>Variation 2</p> }
</React.Fragment>
);
}
async function main() {
const resp = await fetch('https://cdn.optimizely.com/datafiles/<Your-SDK-Key>.json');
const datafile = await resp.json();
const optimizelyClient = createInstance({
datafile,
});
const output = ReactDOMServer.renderToString(
<OptimizelyProvider optimizely={optimizelyClient} user={{ id: 'user1' }} isServerSide={true}>
<MyComponent />
</OptimizelyProvider>
);
console.log('output', output);
}
main();
Disabled event dispatcher
To disable sending all events to Optimizely's results backend, use the logOnlyEventDispatcher
when creating a client:
import { createInstance, logOnlyEventDispatcher } from '@optimizely/react-sdk';
const optimizely = createInstance({
datafile: window.optimizelyDatafile,
eventDispatcher: logOnlyEventDispatcher,
});
Additional code
This repository includes the following third party open source code:
hoist-non-react-statics Copyright © 2015 Yahoo!, Inc. License: BSD
js-tokens Copyright © 2014, 2015, 2016, 2017, 2018, 2019 Simon Lydell License: MIT
json-schema Copyright © 2005-2015, The Dojo Foundation License: BSD
lodash Copyright © JS Foundation and other contributors License: MIT
loose-envify Copyright © 2015 Andres Suarez [email protected] License: MIT
node-murmurhash Copyright © 2012 Gary Court, Derek Perez License: MIT
object-assign Copyright © Sindre Sorhus (sindresorhus.com) License: MIT
promise-polyfill Copyright © 2014 Taylor Hakes Copyright © 2014 Forbes Lindesay License: MIT
prop-types Copyright © 2013-present, Facebook, Inc. License: MIT
react-is Copyright © Facebook, Inc. and its affiliates. License: MIT
react Copyright © Facebook, Inc. and its affiliates. License: MIT
scheduler Copyright © Facebook, Inc. and its affiliates. License: MIT
utility-types Copyright © 2016 Piotr Witek [email protected] License: MIT
node-uuid Copyright © 2010-2016 Robert Kieffer and other contributors License: MIT
To regenerate the dependencies use by this package, run the following command:
npx license-checker --production --json | jq 'map_values({ licenses, publisher, repository }) | del(.[][] | nulls)'
Contributing
Please see CONTRIBUTING for more information.
Credits
First-party code subject to copyrights held by Optimizely, Inc. and its contributors and licensed to you under the terms of the Apache 2.0 license.
Other Optimizely SDKs
Agent - https://github.com/optimizely/agent
Android - https://github.com/optimizely/android-sdk
C# - https://github.com/optimizely/csharp-sdk
Flutter - https://github.com/optimizely/optimizely-flutter-sdk
Go - https://github.com/optimizely/go-sdk
Java - https://github.com/optimizely/java-sdk
JavaScript - https://github.com/optimizely/javascript-sdk
PHP - https://github.com/optimizely/php-sdk
Python - https://github.com/optimizely/python-sdk
Ruby - https://github.com/optimizely/ruby-sdk
Swift - https://github.com/optimizely/swift-sdk