govuk_frontend_toolkit 7.3.0 → 7.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0334902cdeefff962323abe904470c7558848f31bda9660316d85abf05e26d34
-  data.tar.gz: f69772e14fcbbbd38c6a5fecdc627618c990d481f6a818b8bba157d231b69a73
+  metadata.gz: c7d913fed9e8375459ac2c0cb48ba26fd4bea526a38faa372ca84cbcb0333e2b
+  data.tar.gz: 87d5bacfb307d6586cb334764aa31e5165a4720320374905023498c273ed95a8
 SHA512:
-  metadata.gz: 57596cc95ffa5ec4c46b0e020cefde1007f2c2d074707e53b6ed3a221e5807e13c040f62289fc89fc561d5e56f758b6279e56f685f839a46149eb2eae1f12425
-  data.tar.gz: 608f7fa34a8f4723b883b564d401f52a3c9afca816303c574f7f0ca4574c458d0d9b32e243fa6828e5840ab403069275ed405d6a564efde0532fda50b2adf919
+  metadata.gz: fb987f4d033bd8089be306d3301fb5f93c07ff0fbcc52f5d5938b006413312184d31893fb48869e9d4fcd324a21de6358830f8fa4112f21c5d548a7a848b6af7
+  data.tar.gz: 0340fecd6ab4340d6fdfb47dd7ed6d76b867ab45cd39bd6c5846330a1836c0b414f8f981af5bc0bdeb73da8f93b2cb04c91e02b4a94fb12f3b51a684fed50688

data/app/assets/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 7.4.0
+
+- Allow wrapping arguments to analytics as PII safe to tell the analytics code not to attempt to strip PII from the values: ([PR #448](https://github.com/alphagov/govuk_frontend_toolkit/pull/448))
+- Documentation improvements: ([PR #446](https://github.com/alphagov/govuk_frontend_toolkit/pull/446), [PR #447](https://github.com/alphagov/govuk_frontend_toolkit/pull/447))
+
 # 7.3.0
 
 - Strip PII from all arguments passed to GA.  Emails are stripped by default, postcodes can also be stripped if configured to do so: ([PR #435](https://github.com/alphagov/govuk_frontend_toolkit/pull/435)).

data/app/assets/README.md

@@ -1,11 +1,5 @@
 # GOV.UK frontend toolkit
 
----
-
-#### You can help us improve the GOV.UK frontend toolkit by completing our [5 minute survey](https://www.surveymonkey.co.uk/r/2MZRS9H).
-
----
-
 A collection of Sass and JavaScript files for using as part of your
 application's frontend.
 
@@ -39,6 +33,20 @@ may need to upgrade to a more recent version to use the grid helpers. Minimal
 compatible versions include `node-sass` 1.0.0, `grunt-sass` 0.16.0,
 `gulp-sass` 1.2.0 and `libsass` 3.0.0.
 
+### Django
+
+Requirement: [NodeJS](https://nodejs.org/en/) installed. This gives you [Node Package Manager](https://docs.npmjs.com/getting-started/installing-node)(NPM) which is required to install npm packages.
+
+The easiest way to integrate it would be to create a `package.json` file in your application with `npm init` 
+
+You then install the toolkit with `npm install --save govuk_frontend_toolkit`.
+If you need javascript files, they will live in (`node_modules/govuk_frontend_toolkit/javascripts`).
+If you need stylesheets they will live in (`node_modules/govuk_frontend_toolkit/stylesheets`).
+
+With Django you can use https://github.com/jrief/django-sass-processor to compile Sass files.
+
+Note: if you need complete styles you might want to install govuk-elements-sass package that also installs toolkit
+
 ### Composer
 
 [govuk_frontend_toolkit_composer][toolkit_composer_github] is an composer package that can be

data/app/assets/VERSION.txt

@@ -1 +1 @@
-7.3.0
+7.4.0

data/app/assets/docs/analytics.md

@@ -249,3 +249,22 @@ initialize time as follows:
 
 Any value other than the JS literal `true` for `stripPostcodePII` will leave
 the analytics module configured not to strip postcodes.
+
+#### Avoding false positives
+
+Sometimes you will have data you want to send to analytics that looks like PII
+and would be stripped out.  For example on GOV.UK the content_ids that belong
+to every document can sometimes contain a string of characters that look like a
+UK postcode: in `eed5b92e-8279-4ca9-a141-5c35ed22fcf1` the substring `c35ed` in
+the final portion looks like a postcode, `C3 5ED`, and will be transformed into
+`eed5b92e-8279-4ca9-a141-5[postcode]22fcf1` which breaks the `content_id`.  To
+send data that you know is not PII, but it looks like an email address or a UK
+postcode you can provide your arguments wrapped in a `GOVUK.Analytics.PIISafe`
+object.  If any argument to an analytics function is an instance of one of these
+objects the value contained within will be extracted and sent directly to the
+analytics tracker without attempting to strip PII from it.  For example:
+
+```js
+  GOVUK.analytics.setDimension(1, new GOVUK.Analytics.PIISafe('this-is-not-an@email-address-but-it-looks-like-one'));
+  GOVUK.analytics.trackEvent('report title clicked', new GOVUK.Analytics.PIISafe('this report title looks like it contains a P0 5TC ode but it does not really'));
+````

data/app/assets/javascripts/govuk/analytics/analytics.js

@@ -29,10 +29,15 @@
     }
   }
 
+  var PIISafe = function (value) {
+    this.value = value
+  }
+  Analytics.PIISafe = PIISafe
+
   Analytics.prototype.stripPII = function (value) {
     if (typeof value === 'string') {
       return this.stripPIIFromString(value)
-    } else if (Object.prototype.toString.call(value) === '[object Array]') {
+    } else if (Object.prototype.toString.call(value) === '[object Array]' || Object.prototype.toString.call(value) === '[object Arguments]') {
       return this.stripPIIFromArray(value)
     } else if (typeof value === 'object') {
       return this.stripPIIFromObject(value)
@@ -51,12 +56,16 @@
   }
 
   Analytics.prototype.stripPIIFromObject = function (object) {
-    for (var property in object) {
-      var value = object[property]
+    if (object instanceof Analytics.PIISafe) {
+      return object.value
+    } else {
+      for (var property in object) {
+        var value = object[property]
 
-      object[property] = this.stripPII(value)
+        object[property] = this.stripPII(value)
+      }
+      return object
     }
-    return object
   }
 
   Analytics.prototype.stripPIIFromArray = function (array) {

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

@@ -150,6 +150,24 @@ describe('GOVUK.Analytics', function () {
       analytics.setDimension(1, 'SW1+1AA-value', { label: 'RG209NJ', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
       expect(window.ga.calls.mostRecent().args).toEqual(['set', 'dimension1', '[postcode]-value']) // set dimension ignores extra options
     })
+
+    it('ignores any PIISafe arguments even if they look like emails or postcodes', function () {
+      analytics = new GOVUK.Analytics({
+        universalId: 'universal-id',
+        cookieDomain: '.www.gov.uk',
+        siteSpeedSampleRate: 100,
+        stripPostcodePII: true
+      })
+
+      analytics.trackPageview(new GOVUK.Analytics.PIISafe('/path/to/an/embedded/SW1+1AA/postcode/?with=an&postcode=SP4%207DE'), new GOVUK.Analytics.PIISafe('an.email@example.com'), { label: new GOVUK.Analytics.PIISafe('another.email@example.com'), value: ['data', 'data', new GOVUK.Analytics.PIISafe('someone has added their personalIV63 6TU postcode')] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', 'pageview', { page: '/path/to/an/embedded/SW1+1AA/postcode/?with=an&postcode=SP4%207DE', title: 'an.email@example.com', label: 'another.email@example.com', value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] }])
+
+      analytics.trackEvent(new GOVUK.Analytics.PIISafe('SW1+1AA-category'), new GOVUK.Analytics.PIISafe('an.email@example.com-action'), { label: new GOVUK.Analytics.PIISafe('RG209NJ'), value: ['data', 'data', 'someone has added their personalIV63 6TU postcode'] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', { hitType: 'event', eventCategory: 'SW1+1AA-category', eventAction: 'an.email@example.com-action', eventLabel: 'RG209NJ' }]) // trackEvent ignores options other than label or integer values for value
+
+      analytics.setDimension(1, new GOVUK.Analytics.PIISafe('an.email@SW1+1AA-value.com'), { label: new GOVUK.Analytics.PIISafe('RG209NJ'), value: ['data', 'data', new GOVUK.Analytics.PIISafe('someone has added their personalIV63 6TU postcode')] })
+      expect(window.ga.calls.mostRecent().args).toEqual(['set', 'dimension1', 'an.email@SW1+1AA-value.com']) // set dimension ignores extra options
+    })
   })
 
   describe('when tracking social media shares', function () {
@@ -224,6 +242,31 @@ describe('GOVUK.Analytics', function () {
         value: ['data', 'data', 'someone has added their personal[postcode] postcode']
       }])
     })
+
+    it('ignores any PIISafe arguments even if they look like emails or postcodes', function () {
+      analytics = new GOVUK.Analytics({
+        universalId: 'universal-id',
+        cookieDomain: '.www.gov.uk',
+        siteSpeedSampleRate: 100,
+        stripPostcodePII: true
+      })
+
+      analytics.trackShare('email', {
+        to: new GOVUK.Analytics.PIISafe('IV63 6TU'),
+        label: new GOVUK.Analytics.PIISafe('an.email@example.com'),
+        value: new GOVUK.Analytics.PIISafe(['data', 'another.email@example.com', 'someone has added their personalTD15 2SE postcode'])
+      })
+
+      expect(window.ga.calls.mostRecent().args).toEqual(['send', {
+        hitType: 'social',
+        socialNetwork: 'email',
+        socialAction: 'share',
+        socialTarget: jasmine.any(String),
+        to: 'IV63 6TU',
+        label: 'an.email@example.com',
+        value: ['data', 'another.email@example.com', 'someone has added their personalTD15 2SE postcode']
+      }])
+    })
   })
 
   describe('when adding a linked domain', function () {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_frontend_toolkit
 version: !ruby/object:Gem::Version
-  version: 7.3.0
+  version: 7.4.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-08 00:00:00.000000000 Z
+date: 2018-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties