govuk_frontend_toolkit 3.3.1 → 3.4.0

data/app/assets/.gitignore

@@ -1,4 +1,4 @@
 node_modules/
 .sass-cache
-
+npm-debug.log
 /spec/stylesheets/test-out.css.map

data/app/assets/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 3.4.0
+
+- multivariate-test.js: add support for using Google Content Experiments as the reporting
+backend for multivariate tests
+
 # 3.3.1
 
 - Fix: Make the error colour a darker red for greater contrast and to meet WCAG 2.0 AAAA 

data/app/assets/VERSION.txt

@@ -1 +1 @@
-3.3.1
+3.4.0

data/app/assets/docs/javascript.md

@@ -36,7 +36,6 @@ A simple content replacement test can be done by defining a set of cohorts with
 var test = new GOVUK.MultivariateTest({
   el: '.car-tax-button',
   name: 'car_tax_button_text',
-  customVarIndex: 555,
   cohorts: {
     pay_your_car_tax: {html: "Pay Your Car Tax"},
     give_us_money: {html: "Give Us Money Or We Will Crush Your Car"}
@@ -50,7 +49,6 @@ when a user is in each cohort:
 ```javascript
 var test = new GOVUK.MultivariateTest({
   name: 'car_tax_button_text',
-  customVarIndex: 555,
   cohorts: {
     pay_your_car_tax: {callback: function() { ... }},
     give_us_money: {callback: function() { ... }}
@@ -64,7 +62,6 @@ that cohort:
 ```javascript
 var test = new GOVUK.MultivariateTest({
   name: 'car_tax_button_text',
-  customVarIndex: 555,
   cohorts: {
     pay_your_car_tax: {weight: 25, callback: function() { ... }}, // 25%
     give_us_money:    {weight: 75, callback: function() { ... }}  // 75%
@@ -78,8 +75,7 @@ on the current object.
 
 Takes these options:
  - `el`: Element to run this test on (optional)
- - `name`: The name of the text (alphanumeric and underscores)
- - `customVarIndex`: The index of the custom variable in Google Analytics. GA only gives 50 integer slots to each account, and it is important that a unique integer is assigned to each test. Current contact for assigning a custom var slot for GOV.UK is: Ashraf Chohan <ashraf.chohan@digital.cabinet-office.gov.uk>
+ - `name`: The name of the text (alphanumeric and underscores), which will be part of the cookie.
  - `defaultWeight`: Number of times each cohorts should appear in an array the random cohort is picked from, to be used in conjunction with weights on individual cohorts.
  - `cohorts`: An object that maps cohort name to an object that defines the cohort. Name must be same format as test name. Object contains keys (all optional):
    - `html`: HTML to fill element with when this cohort is picked.
@@ -88,6 +84,56 @@ Takes these options:
 
 Full documentation on how to design multivariate tests, use the data in GA and construct hypothesis tests is on its way soon.
 
+### Reporting to Google Content Experiments
+The toolkit includes a library for multivariate testing that is capable of reporting data into [Google Content Experiments](https://developers.google.com/analytics/devguides/platform/experiments-overview).
+
+#### To create a new experiment
+
+1. Log in to Google Universal Analytics, select "UA - Preview environment".
+2. In the left column, click on Behaviour, then Experiments and follow [these instructions](https://support.google.com/analytics/answer/1745152?hl=en-GB) to set up your experiment; you will need to have edit permissions on the Universal Analytics profile. If you cannot see a "Create experiment" button, this means you don't have these permissions; you can ask someone from the Performance Analyst team to set the experiment up for you.
+3. In step number 2, in our case the address of the web pages will purely be used as descriptions in reports, so we recommend you pick the addresses accordingly, ie: "www.gov.uk" and "www.gov.uk/?=variation1".
+4. In step number 3, "Setting up your experiment code", select "Manually insert the code" and make a note of the Experiment ID number located under the script window.
+5. Add the below code to the page you want to test.
+    - the contentExperimentId is the Experiment ID you retrieved in step 3
+    - the variantId is 0 for the original variant, 1 for the first modified variant, 2 for the second modified variant, etc.
+    - see section above for other elements
+This code requires analytics to be loaded in order to run; static is the app that would load the analytics by default, which automatically happens before experiments are run.
+6. Check that it works: launch the app, open the page of your app, and check that there is a cookie with the name you had picked in your experiment. You can delete the cookie and refresh the page to check whether you can be assigned to another cohort.
+
+```js
+var test = new GOVUK.MultivariateTest({
+  name: 'car_tax_button_text',
+  contentExperimentId: "Your_Experiment_ID",
+  cohorts: {
+    pay_your_car_tax: {weight: 25, variantId: 0},
+    give_us_money: {weight: 25, variantId: 1}
+  }
+});
+
+```
+
+### Using Google custom dimensions with your own statistical model
+
+It is possible to use Google custom dimensions for determining the results of
+the multivariate test (as an alternative to Google Content Experiments). This
+may be appropriate if you wish to build the statistical model yourself or you
+aren't able to use Content Experiments for some reason.
+
+This requires setting the optional `customDimensionIndex` variable:
+
+```js
+var test = new GOVUK.MultivariateTest({
+  name: 'car_tax_button_text',
+  customDimensionIndex: 555,
+  cohorts: {
+    pay_your_car_tax: {weight: 25},
+    give_us_money: {weight: 50}
+  }
+});
+```
+
+`customDimensionIndex` is the index of the custom variable in Google Analytics. GA only gives 50 integer slots to each account, and it is important that a unique integer is assigned to each test. Current contact for assigning a custom var slot for GOV.UK is: Ashraf Chohan <ashraf.chohan@digital.cabinet-office.gov.uk>
+
 ## Primary Links
 
 `GOVUK.PrimaryList` hides elements in a list which don't have a supplied

data/app/assets/javascripts/govuk/multivariate-test.js

@@ -12,10 +12,11 @@
   function MultivariateTest(options) {
     this.$el = $(options.el);
     this._loadOption(options, 'name');
-    this._loadOption(options, 'customVarIndex');
+    this._loadOption(options, 'customDimensionIndex', null);
     this._loadOption(options, 'cohorts');
     this._loadOption(options, 'runImmediately', true);
     this._loadOption(options, 'defaultWeight', 1);
+    this._loadOption(options, 'contentExperimentId', null);
 
     if (this.runImmediately) {
       this.run();
@@ -39,8 +40,10 @@
   MultivariateTest.prototype.run = function() {
     var cohort = this.getCohort();
     if (cohort) {
+      this.setUpContentExperiment(cohort);
       this.setCustomVar(cohort);
       this.executeCohort(cohort);
+      this.createDummyEvent(cohort);
     }
   };
 
@@ -71,18 +74,30 @@
   };
 
   MultivariateTest.prototype.setCustomVar = function(cohort) {
-    window._gaq = window._gaq || [];
-    window._gaq.push([
-      '_setCustomVar',
-      this.customVarIndex,
-      this.cookieName(),
-      cohort,
-      2 // session level
-    ]);
-    // Fire off a dummy event to set the custom var on the page.
+    if (this.customDimensionIndex) {
+      GOVUK.analytics.setDimension(
+        this.customDimensionIndex,
+        this.cookieName(),
+        cohort,
+        2 // session level
+      );
+    }
+  };
+
+  MultivariateTest.prototype.setUpContentExperiment = function(cohort) {
+    var contentExperimentId = this.contentExperimentId;
+    var cohortVariantId = this.cohorts[cohort]['variantId'];
+    if(contentExperimentId && cohortVariantId && typeof window.ga === "function"){
+      window.ga('set', 'expId', contentExperimentId);
+      window.ga('set', 'expVar', cohortVariantId);
+    };
+  };
+
+  MultivariateTest.prototype.createDummyEvent = function(cohort) {
+    // Fire off a dummy event to set the custom var and the content experiment on the page.
     // Ideally we'd be able to call setCustomVar before trackPageview,
     // but would need reordering the existing GA code.
-    window._gaq.push(['_trackEvent', this.cookieName(), 'run', '-', 0, true]);
+    GOVUK.analytics.trackEvent(this.cookieName(), 'run', {nonInteraction:true});
   };
 
   MultivariateTest.prototype.weightedCohortNames = function() {

data/app/assets/spec/unit/MultivariateTestSpec.js

@@ -1,7 +1,9 @@
 describe("MultivariateTest", function() {
   beforeEach(function() {
     GOVUK.cookie = jasmine.createSpy('GOVUK.cookie');
-    window._gaq = [];
+    GOVUK.analytics = {setDimension:function(){}, trackEvent:function(){}};
+    spyOn(GOVUK.analytics, "setDimension");
+    spyOn(GOVUK.analytics, "trackEvent");
   });
 
   describe("#run", function() {
@@ -11,7 +13,6 @@ describe("MultivariateTest", function() {
       var barSpy = jasmine.createSpy('barSpy');
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         cohorts: {
           foo: {callback: fooSpy},
           bar: {callback: barSpy}
@@ -34,7 +35,6 @@ describe("MultivariateTest", function() {
       var barSpy = jasmine.createSpy('barSpy');
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         cohorts: {
           foo: {callback: fooSpy},
           bar: {callback: barSpy}
@@ -43,7 +43,7 @@ describe("MultivariateTest", function() {
       expect(fooSpy).toHaveBeenCalled();
     });
 
-    it("should set a custom var", function() {
+    it("should set a custom var if one is defined", function() {
       GOVUK.cookie.and.returnValue('foo');
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
@@ -51,25 +51,19 @@ describe("MultivariateTest", function() {
           foo: {},
           bar: {}
         },
-        customVarIndex: 2
+        customDimensionIndex: 2
       });
-      expect(window._gaq).toEqual([
-        [
-          '_setCustomVar',
-          2,
-          'multivariatetest_cohort_stuff',
-          'foo',
-          2
-        ],
-        [
-          '_trackEvent',
-          'multivariatetest_cohort_stuff',
-          'run',
-          '-',
-          0,
-          true
-        ]
-      ]);
+      expect(GOVUK.analytics.setDimension).toHaveBeenCalledWith(
+        2,
+        'multivariatetest_cohort_stuff',
+        'foo',
+        2
+      );
+      expect(GOVUK.analytics.trackEvent).toHaveBeenCalledWith(
+        'multivariatetest_cohort_stuff',
+        'run',
+        {nonInteraction:true}
+      );
     });
 
     it("should set html for a cohort", function() {
@@ -77,7 +71,6 @@ describe("MultivariateTest", function() {
       var $el = $('<div>');
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         el: $el,
         cohorts: {
           foo: {html: "foo"},
@@ -94,7 +87,6 @@ describe("MultivariateTest", function() {
       var $el = $('<div>');
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         el: $el,
         cohorts: {
           foo: {callback: fooSpy},
@@ -108,7 +100,6 @@ describe("MultivariateTest", function() {
       GOVUK.cookie.and.returnValue('foo');
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         cohorts: {
           foo: {callback: 'fooCallback'},
           bar: {}
@@ -126,7 +117,6 @@ describe("MultivariateTest", function() {
       GOVUK.cookie.and.returnValue('baz');
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         cohorts: {
           foo: {callback: fooSpy},
           bar: {callback: barSpy}
@@ -145,7 +135,6 @@ describe("MultivariateTest", function() {
     it("should return the weighted names of the cohorts when no weights are defined", function() {
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         cohorts: {foo: {}, bar: {}, baz: {}}
       });
       expect(test.weightedCohortNames()).toEqual(['foo', 'bar', 'baz']);
@@ -154,7 +143,6 @@ describe("MultivariateTest", function() {
     it("should return the weighted names of the cohorts when weights are defined", function() {
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         cohorts: {foo: { weight: 2 }, bar: { weight: 1 }, baz: { weight: 3 }}
       });
       expect(test.weightedCohortNames()).toEqual(['foo', 'foo', 'bar', 'baz', 'baz', 'baz']);
@@ -163,7 +151,6 @@ describe("MultivariateTest", function() {
     it("should return the weighted names of the cohorts using default weighting", function() {
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         defaultWeight: 2,
         cohorts: {foo: {}, bar: {}, baz: {}}
       });
@@ -173,7 +160,6 @@ describe("MultivariateTest", function() {
     it("should return the weighted names of the cohorts using default weighting or defined weighting", function() {
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         defaultWeight: 2,
         cohorts: {foo: {}, bar: { weight: 1 }, baz: {}}
       });
@@ -185,10 +171,31 @@ describe("MultivariateTest", function() {
     it("should choose a random cohort", function() {
       var test = new GOVUK.MultivariateTest({
         name: 'stuff',
-        customVarIndex: 1,
         cohorts: {foo: {}, bar: {}}
       });
       expect(['foo', 'bar']).toContain(test.chooseRandomCohort());
     })
   });
+
+  describe("Google Content Experiment Integration", function() {
+    beforeEach(function() {
+      window.ga = function() {};
+      spyOn(window, 'ga');
+    });
+
+    it("should report the experiment data to Google", function() {
+      var test = new GOVUK.MultivariateTest({
+        name: 'stuff',
+        contentExperimentId: "asdfsadasdfa",
+        cohorts: {foo: {variantId: 0, weight: 0},  bar: {variantId: 1, weight: 1}}
+      });
+      expect(window.ga.calls.first().args).toEqual(['set', 'expId', 'asdfsadasdfa']);
+      expect(window.ga.calls.mostRecent().args).toEqual(['set', 'expVar', 1]);
+      expect(GOVUK.analytics.trackEvent).toHaveBeenCalledWith(
+        'multivariatetest_cohort_stuff',
+        'run',
+        {nonInteraction:true}
+      );
+    });
+  });
 });

data/app/assets/stylesheets/_colours.scss

@@ -105,5 +105,5 @@ $page-colour: $white;             // The page
 $alpha-colour: $pink;             // Alpha badges and banners
 $beta-colour: $orange;            // Beta badges and banners
 $banner-text-colour: #000;        // Text colour for Alpha & Beta banners
-$error-colour: $mellow-red;       // Error text and border colour
+$error-colour: #af1324;           // Error text and border colour
 $error-background: #fef7f7;       // Error background colour

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: govuk_frontend_toolkit
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-14 00:00:00.000000000 Z
+date: 2015-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -288,7 +288,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3001671793728050183
+      hash: 3731870620465373503
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -297,7 +297,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3001671793728050183
+      hash: 3731870620465373503
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23