From bff50a4e86da57cc232bbe45be29b7b0902faa4d Mon Sep 17 00:00:00 2001
From: Paul Hayes <fofr@users.noreply.github.com>
Date: Tue, 10 Mar 2015 13:23:03 +0000
Subject: [PATCH] Avoid example duplication

Keep a canonical example that can be copy and pasted within the
analytics documentation.

* Include link to docs from within tracker.js
* Remove old example-init.js
---
 docs/analytics.md                             | 62 ++++++++++---------
 .../analytics/example-init/example-init.js    | 24 -------
 javascripts/govuk/analytics/tracker.js        |  3 +
 3 files changed, 36 insertions(+), 53 deletions(-)
 delete mode 100644 javascripts/govuk/analytics/example-init/example-init.js

diff --git a/docs/analytics.md b/docs/analytics.md
index 5d16eaca..c1e88908 100644
--- a/docs/analytics.md
+++ b/docs/analytics.md
@@ -12,38 +12,42 @@ The toolkit provides an abstraction around analytics to make tracking pageviews,
 ## Create an analytics tracker
 
 The minimum you need to use the analytics function is:
-1. Include the following files from /javascripts/govuk/analytics in your project:
-  1. google-analytics-classic-tracker.js
-  2. google-analytics-universal-tracker.js
-  3. tracker.js
-2. Copy the file example-init/example-init.js from the same folder to your own project and replace the dummy IDs with your own (they begin with `UA-`)
-
-Load and create the analytics tracker at the earliest opportunity so that:
-* the time until the first pageview is tracked is kept small and pageviews aren’t missed
-* javascript that depends on `GOVUK.analytics` runs after the tracker has been created
 
-An excerpt from the [`example-init.js`](/javascripts/govuk/analytics/example-init/example-init.js) file:
+1. Include the following files from /javascripts/govuk/analytics in your project:
+  * google-analytics-classic-tracker.js
+  * google-analytics-universal-tracker.js
+  * tracker.js
+2. Copy the following `init` script into your own project and replace the dummy IDs with your own (they begin with `UA-`).
+  * This initialisation can occur immediately as this API has no dependencies.
+  * Load and create the analytics tracker at the earliest opportunity so that:
+    * the time until the first pageview is tracked is kept small and pageviews aren’t missed
+    * javascript that depends on `GOVUK.analytics` runs after the tracker has been created
 
 ```js
-// Load Google Analytics libraries
-GOVUK.Tracker.load();
-
-// Use document.domain in dev, preview and staging so that tracking works
-// Otherwise explicitly set the domain as www.gov.uk (and not gov.uk).
-var cookieDomain = (document.domain === 'www.gov.uk') ? '.www.gov.uk' : document.domain;
-
-// Configure profiles, setup custom vars, track initial pageview
-GOVUK.analytics = new GOVUK.Tracker({
-  universalId: 'UA-XXXXXXXX-X',
-  classicId: 'UA-XXXXXXXX-X',
-  cookieDomain: cookieDomain
-});
-
-// Set custom dimensions before tracking pageviews
-// GOVUK.analytics.setDimension(…)
-
-// Track initial pageview
-GOVUK.analytics.trackPageview();
+(function() {
+  "use strict";
+
+  // Load Google Analytics libraries
+  GOVUK.Tracker.load();
+
+  // Use document.domain in dev, preview and staging so that tracking works
+  // Otherwise explicitly set the domain as www.gov.uk (and not gov.uk).
+  var cookieDomain = (document.domain === 'www.gov.uk') ? '.www.gov.uk' : document.domain;
+
+  // Configure profiles and make interface public
+  // for custom dimensions, virtual pageviews and events
+  GOVUK.analytics = new GOVUK.Tracker({
+    universalId: 'UA-XXXXXXXX-X',
+    classicId: 'UA-XXXXXXXX-X',
+    cookieDomain: cookieDomain
+  });
+
+  // Set custom dimensions before tracking pageviews
+  // GOVUK.analytics.setDimension(…)
+
+  // Track initial pageview
+  GOVUK.analytics.trackPageview();
+})();
 ```
 
 Once instantiated, the `GOVUK.analytics` object can be used to track virtual pageviews, custom events and custom dimensions.
diff --git a/javascripts/govuk/analytics/example-init/example-init.js b/javascripts/govuk/analytics/example-init/example-init.js
deleted file mode 100644
index 3613d05c..00000000
--- a/javascripts/govuk/analytics/example-init/example-init.js
+++ /dev/null
@@ -1,24 +0,0 @@
-(function() {
-  "use strict";
-
-  // Load Google Analytics libraries
-  GOVUK.Tracker.load();
-
-  // Use document.domain in dev, preview and staging so that tracking works
-  // Otherwise explicitly set the domain as www.gov.uk (and not gov.uk).
-  var cookieDomain = (document.domain === 'www.gov.uk') ? '.www.gov.uk' : document.domain;
-
-  // Configure profiles, setup custom vars, track initial pageview
-  // and make interface public for virtual pageviews and events
-  GOVUK.analytics = new GOVUK.Tracker({
-    universalId: 'UA-XXXXXXXX-X',
-    classicId: 'UA-XXXXXXXX-X',
-    cookieDomain: cookieDomain
-  });
-
-  // Set custom dimensions before tracking pageviews
-  // GOVUK.analytics.setDimension(…)
-
-  // Track initial pageview
-  GOVUK.analytics.trackPageview();
-})();
diff --git a/javascripts/govuk/analytics/tracker.js b/javascripts/govuk/analytics/tracker.js
index 3e4c7157..446ad9c8 100644
--- a/javascripts/govuk/analytics/tracker.js
+++ b/javascripts/govuk/analytics/tracker.js
@@ -2,6 +2,9 @@
   "use strict";
   window.GOVUK = window.GOVUK || {};
 
+  // For usage and initialisation see:
+  // https://github.com/alphagov/govuk_frontend_toolkit/blob/master/docs/analytics.md#create-an-analytics-tracker
+
   var Tracker = function(config) {
     this.universal = new GOVUK.GoogleAnalyticsUniversalTracker(config.universalId, config.cookieDomain);
     this.classic = new GOVUK.GoogleAnalyticsClassicTracker(config.classicId, config.cookieDomain);