You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Added the ```parametrize``` function that takes in experiment information and a component and parametrizes the component with the experiment parameters as props.
3
+
- Added the requirement to pass in an array of experiment parameters as props to the Parametrize component and removed the experimentName prop.
Copy file name to clipboardExpand all lines: README.md
+65-33Lines changed: 65 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,49 +11,43 @@ npm install react-experiments
11
11
12
12
# Usage
13
13
14
-
react-experiments was built to work with [PlanOut.js](https://www.github.com/HubSpot/PlanOut.js) and most of its constructs are inspired by the structure of PlanOut.js. This library will work out of the box if you pass it an instantiated PlanOut Namespace or Experiment class, but if you want to use your own methods of assigning experiment parameters and logging exposure then you can extend the base [experiment class](https://github.com/HubSpot/react-experiments/blob/master/src/experimentClass.js) and pass that as the experiment prop to the Experiment class components.
14
+
react-experiments was built to work with [PlanOut.js](https://www.github.com/HubSpot/PlanOut.js) and most of its constructs are inspired by the structure of PlanOut.js. This library will work out of the box if you pass it an instantiated PlanOut Namespace or Experiment class, but if you want to use your own methods of assigning experiment parameters and logging exposure then you can extend the base [experiment class](https://github.com/HubSpot/react-experiments/blob/master/src/experimentClass.js) and pass that as the experiment class prop.
15
15
16
16
17
-
## Implementing an experiment
17
+
## Implementing a simple experiment
18
18
19
19
This library serves as a way to declaratively implement UI experiments that are defined via PlanOut. The standard usage of this library is as follows:
20
20
21
-
1) Define experiment via PlanOut script / API. The PlanOut parameters that you set should map to the props on which you want to run an experiment. Let's use the [sample PlanOut.js experiment](https://github.com/HubSpot/PlanOut.js/blob/master/examples/sample_planout_es5.js#L41) as an example, which is effectively:
21
+
1) Define experiment via PlanOut script / API. The PlanOut parameters that you set should map to the props on which you want to run an experiment. Let's use the [sample PlanOut.js experiment](https://github.com/HubSpot/PlanOut.js/blob/master/examples/sample_planout_es5.js#L41) as an example, which is effectively:
2) Wrap the component where you want to implement your UI experiment with the Parametrize component provided by the library. As an example,
27
+
2) Wrap the component where you want to implement your UI experiment with the parametrize function provided by the library along with an instantiated experiment class and the specific parameter names that you want to parametrize the component with. As an example,
Now, you can just use the ```WithExperimentParams``` component provided by the library and wrap the Signup component with it.
47
-
```
48
-
Signup = withExperimentParams(Signup);
38
+
}
39
+
}));
49
40
```
50
41
51
42
Now you should be all set to run the sample experiment. The Signup component will render 'Sign up' or 'Join now' based on the randomized parameter assigned by PlanOut.js.
The following are the props for the Parametrize component:
69
+
## Base Parametrize Component
70
+
71
+
The implementation of all the components provided by this library are wrappers around a base ```Parametrize``` component. The ```Parametrize``` component allows for parametrizing a given component with experiment parameters. The following are the props that the ```Parametrize``` component takes:
82
72
83
73
**experiment**: This is an instance of a PlanOut.js experiment / namespace class or the base experimentClass. [REQUIRED]
84
74
85
-
**experimentName**: This is the name of the experiment. It is particularly important if you're using a PlanOut.js namespace, since this corresponds to the name of the experiment WITHIN the namespace, not the name of the namespace itself. This is required so that exposure gets logged correctly. [REQUIRED]
75
+
76
+
**params**: This is the list of experiment parameters that you want to use to parametrize the component. They should correspond to the parameter names defined in your PlanOut script / experiment definition. [REQUIRED]
86
77
87
78
[any arbitrary prop]: You can pass arbitrary props to the Parametrize component and they will be available via context.experimentProps in all descendants of the Parametrize component.
88
79
80
+
### Higher-order Parametrization Components
81
+
82
+
There are two primary higher-order components to use for parametrization.
83
+
84
+
**parametrize**: The ```parametrize``` function takes an instantiated experiment class, either an experiment name or a list of params, and a React component. It takes the given component and sets the deterministically and randomly assigned experiment parameters of the experiment class as props.
**withExperimentParams**: The ```withExperimentParams``` function is used in combination with the base ```Parametrize``` component. It is useful when running an experiment with nested components, but generally the ```parametrize``` function should be preferred.
There are two common types of experimental parameters:
93
128
94
129
1) Parameters that correspond to parametrizations of existing variables and components. For instance, if one is running an experiment to test which shade of blue optimizes the click rate of the button, then the values to which your experiment parameters map would correspond to something such as the different hex codes for the different shades of blue.
95
130
96
131
2) "Branching" parameters where the parameter values correspond to different "variations" of the experiment. For instance, if one is testing two completely different user interfaces then it wouldn't make sense to parametrize every aspect that has changed, but rather to bin users into either 'Variation A' or 'Variation B'.
97
132
98
-
While the core component of this library focuses on the first type of parameter, it also includes some convenience components built around the Parametrize component for running "branching" experiments.
133
+
While the core component of this library focuses on the first type of parameter, it also includes some convenience components built around the Parametrize component for running "branching" experiments using the ```ABTest``` component.
@@ -122,8 +157,6 @@ The ABTest component takes the following as props:
122
157
123
158
**on** - the parameter name to "branch" off [REQUIRED]
124
159
125
-
**experimentName** - the name of the experiment with which the component corresponds. This is particularly important if you are passing in a namespace class. If you are passing in a namespace class then experimentName should correspond to the name of the experiment within the namespace that this component should handle. Use this if you want your component to deal with any arbitrary number of parameters. [REQUIRED]
126
-
127
160
**shouldEnroll** - this determines whether or not the user should be enrolled in the experiment or not. It defaults to true. If false is passed, nothing is returned and no exposure is logged. [OPTIONAL]
128
161
129
162
## Customized Experiment Components
@@ -132,7 +165,7 @@ If you want to create your own experiment component you can extend the base Para
132
165
133
166
## Logging
134
167
135
-
react-experiments logs an exposure event when it determines that a user should be enrolled in an experiment (i.e. the shouldEnroll prop is not false).
168
+
react-experiments deals with logging experiment exposure. Using the base ```Parametrize``` component always triggers an exposure log when the component is mounted. The ```ABTest``` component also does the same thing unless the ```shouldEnroll``` prop is false.
136
169
137
170
## Development
138
171
@@ -141,4 +174,3 @@ This project is written using ES6 and all build steps / transpilation are done b
141
174
To test API changes locally, open the examples/index.html file locally after building with your most recent changes. The index.html file contains a simple example of using this library paired with the [PlanOut.js sample experiment](https://github.com/HubSpot/PlanOut.js/blob/master/examples/sample_planout_es5.js).
142
175
143
176
Please be sure to add tests to this project when making changes. This project uses [Jest](https://facebook.github.io/jest/) for running tests. Tests can be run either by building the project using build.sh or by using ```npm test```.
0 commit comments