README.md in eeny-meeny-2.0.0 vs README.md in eeny-meeny-2.1.0
- old
+ new
@@ -22,10 +22,11 @@
The following configurations are available:
* `cookies` Defaults to `{ http_only: true, path: '/', same_site: :strict }`. Sets the eeny-meeny cookie attributes. The valid attributes are listed in the section below.
* `secure` Defaults to `true`. Determines if eeny-meeny cookies should be encrypted or not.
* `secret` Sets the secret used for encrypting experiment cookies.
+* `query_parameters` Defaults to `{ experiment: true, smoke_test: true }`. Controls whether experiments variations and smoke tests can be triggered through query parameters.
* `experiments` Defaults to `{}`. It is easiest to load this from a `.yml` file with `YAML.load_file(File.join('config','experiments.yml'))`. The YAML file should have a structure matching the following example:
```
:experiment_1:
:name: Awesome Experiment
@@ -34,17 +35,15 @@
:end_at: '2026-08-11T11:55:40Z'
:variations:
:a:
:name: Variation A
:weight: 0.8
- :options:
- :message: A rocks, B sucks
+ :custom_attribute: A rocks, B sucks
:b:
:name: Variation B
:weight: 0.2
- :options:
- :message: B is an all-star!
+ :custom_attribute: B is an all-star!
```
Valid cookie attributes:
* `domain` Sets the domain scope for the eeny-meeny cookies.
@@ -98,29 +97,41 @@
Rake tasks
-------------
`eeny-meeny` adds the following rake tasks to your project.
-* `eeny_meeny:cookies:experiment[experiment_id]`. Creates and outputs a valid cookie for the given experiment id.
-* `eeny_meeny:cookies:experiment_variation[experiment_id,variation_id]` creates and outputs a valid cookie for the given variation of the experiment with the given experiment_id.
-* `eeny_meeny:cookies:smoke_test[smoke_test_id,version]` Creates and outputs a valid smoke test cookie for a smoke test with the given id and version. `version` will default to `1` if not given.
+* `eeny_meeny:cookie:experiment[experiment_id]`. Creates and outputs a valid cookie for the given experiment id.
+* `eeny_meeny:cookie:experiment_variation[experiment_id,variation_id]` creates and outputs a valid cookie for the given variation of the experiment with the given experiment_id.
+* `eeny_meeny:cookie:smoke_test[smoke_test_id,version]` Creates and outputs a valid smoke test cookie for a smoke test with the given id and version. `version` will default to `1` if not given.
You can execute the rake tasks like this:
-* `rake eeny_meeny:cookies:experimet[experiment_id]`
-* `rake eeny_meeny:cookies:experimet_variation[experiment_id, a]`
-* `rake eeny_meeny:cookies:smoke_test[shadow]`
-* `rake eeny_meeny:cookies:smoke_test[shadow,2]`
+* `rake eeny_meeny:cookie:experimet[experiment_id]`
+* `rake eeny_meeny:cookie:experimet_variation[experiment_id, a]`
+* `rake eeny_meeny:cookie:smoke_test[shadow]`
+* `rake eeny_meeny:cookie:smoke_test[shadow,2]`
You can add the resulting cookie to your browser by copying the cookie string and use the following command in the JS console of your browser.
```
document.cookie = '<cookie string excluding httponly>';
```
Please note that the `HttpOnly` attribute will prevent you from adding the cookie to your browser through JS. You will therefor have to remove the `HttpOnly` part of the cookie string before adding the cookie to your browser.
+Query parameters
+-------------
+By default it is possible to trigger smoke tests and experiment variations through query parameters.
+
+Executing a request to `/?smoke_test_id=my_secret` will trigger the `my_secret` smoke test.
+
+Executing a request to `/?eeny_meeny_my_page_v1=old` will trigger the `old` varition of the `my_page` experiment.
+
+For experiments the parameter needs to match the pattern `eeny_meeny_<experiment_id>_v<experiment_version>=<variation_id>`
+
+Please note that this behavior can be disabled through the `query_parameters` configuration.
+
Setting up Experiments
-------------
It is easiest to define your experiments in YAML files and load them with as shown in the **Configuration** section.
When setting up a new experiment you need to provide the following information:
@@ -135,10 +146,11 @@
A variation needs the following information:
* `variation_id` This is the key that encapsulates the rest of your variation configuration in the YAML file (see `:a:` the **Configuration** section).
* `name` The name/title of your varition.
* `weight` The weight of the variation. Defaults to `1`. This can be a floating or integer number. The final weight of the variation will be `weight / sum_of_variation_weights`.
-* `options` (optional) a hash with variation specific information that you want stored want to use in your experiment. Notice that this information will be stored in the experiment cookie so avoid putting sensitive data in there - especially if you choose to disable the cookie encryption.
+
+You can define additional variation attributes as part of the experiment configuration. These attributes will be accessible as a `Hash` returned from the `options` method on variation objects.
If you want to force all your users to get their experiment cookie updated, then you can change the `version` option on your experiment. This might for instance be useful if you want to remove an under-performing variation from your experiment. Or when gradually rolling a feature out to the public.
Split testing
-------------