src/chrome/common/extensions/docs/templates/articles/tut_analytics.html

   1 <h1>Tutorial: Google Analytics</h1>
   2
   3
   4 <p>This tutorial demonstrates using Google Analytics to track the usage of your
   5 extension.</p>
   6
   7 <h2 id="toc-requirements">Requirements</h2>
   8 <p>
   9   This tutorial expects that you have some familiarity writing extensions for
  10   Google Chrome.  If you need information on how to write an extension, please
  11   read the <a href="getstarted.html">Getting Started tutorial</a>.
  12 </p>
  13
  14 <p>
  15   You will also need a <a href="http://www.google.com/analytics">Google
  16   Analytics account</a> set up to track your extension. Note that when setting
  17   up the account, you can use any value in the Website's URL field, as your
  18   extension will not have an URL of its own.
  19 </p>
  20
  21 <p style="text-align: center">
  22   <img src="{{static}}/images/tut_analytics/screenshot01.png"
  23        style="width:400px;height:82px;"
  24        alt="The analytics setup with info for a chrome extension filled out." />
  25 </p>
  26
  27 <h2 id="toc-installing">Installing the tracking code</h2>
  28
  29 <p>
  30   The standard Google Analytics tracking code snippet fetches a file named
  31   <code>ga.js</code> from an SSL protected URL if the current page
  32   was loaded using the <code>https://</code> protocol.  <strong>Chrome
  33   extensions and applications may <em>only</em> use the SSL-protected version of
  34   <code>ga.js</code></strong>. Loading <code>ga.js</code> over insecure HTTP is
  35   disallowed by Chrome's default <a href="contentSecurityPolicy.html">Content
  36   Security Policy</a>. This, plus the fact that Chrome extensions are hosted
  37   under the <code>chrome-extension://</code> schema, requires a slight
  38   modification to the usual tracking snippet to pull <code>ga.js</code> directly
  39   from <code>https://ssl.google-analytics.com/ga.js</code> instead of the
  40   default location.
  41 </p>
  42
  43 <p>
  44   Below is a modified snippet for the
  45   <a href="http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html">asynchronous
  46   tracking API</a> (the modified line is bolded):
  47 </p>
  48
  49 <pre data-filename="asyncTracking.js">
  50 (function() {
  51   var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  52   <strong>ga.src = 'https://ssl.google-analytics.com/ga.js';</strong>
  53   var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  54 })();
  55 </pre>
  56
  57 <p>
  58   You'll also need to ensure that your extension has access to load the resource
  59   by relaxing the default content security policy. The policy definition in your
  60   <a href="manifest.html"><code>manifest.json</code></a> might look like:
  61 </p>
  62
  63 <pre data-filename="manifest.json">
  64 {
  65   ...,
  66   "content_security_policy": "script-src 'self' https://ssl.google-analytics.com; object-src 'self'",
  67   ...
  68 }
  69 </pre>
  70
  71 <p>
  72   Here is a popup page (<code>popup.html</code>) which loads the asynchronous
  73   tracking code via an external JavaScript file (<code>popup.js</code>) and
  74   tracks a single page view:
  75 </p>
  76
  77 <pre data-filename="popup.html">
  78 &lt;!DOCTYPE html>
  79 &lt;html>
  80  &lt;head>
  81    ...
  82   &lt;script src="popup.js">&lt;/script>
  83  &lt;/head>
  84  &lt;body>
  85    ...
  86  &lt;/body>
  87 &lt;/html>
  88 </pre>
  89
  90 <pre data-filename="popup.js">
  91 var _gaq = _gaq || [];
  92 _gaq.push(['_setAccount', 'UA-XXXXXXXX-X']);
  93 _gaq.push(['_trackPageview']);
  94
  95 (function() {
  96   var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  97   ga.src = 'https://ssl.google-analytics.com/ga.js';
  98   var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  99 })();
 100 </pre>
 101
 102 <p>
 103   Keep in mind that the string <code>UA-XXXXXXXX-X</code> should be replaced
 104   with your own Google Analytics account number.
 105 </p>
 106
 107 <h2 id="toc-tracking-pageviews">Tracking page views</h2>
 108
 109 <p>
 110   The <code>_gaq.push(['_trackPageview']);</code> code will track a single
 111   page view.  This code may be used on any page in your extension.  When
 112   placed on a background page, it will register a view once per browser
 113   session.  When placed on a popup, it will register a view once every time
 114   the popup is opened.
 115 </p>
 116
 117 <p>
 118   By looking at the page view data for each page in your extension, you can
 119   get an idea of how many times your users interact with your extension per
 120   browser session:
 121 </p>
 122
 123 <p style="text-align: center">
 124   <img src="{{static}}/images/tut_analytics/screenshot02.png"
 125        style="width:300px;height:119px;"
 126        alt="Analytics view of the top content for a site." />
 127 </p>
 128
 129 <h2 id="toc-debugging">Monitoring analytics requests</h2>
 130
 131 <p>
 132   To ensure that tracking data from your extension is being sent to Google
 133   Analytics, you can inspect the pages of your extension in the
 134   Developer Tools window (see the
 135   <a href="tut_debugging.html">debugging tutorial</a> for more information).
 136   As the following figure shows, you should see requests for a file named
 137   <strong>__utm.gif</strong> if everything is set up correctly.
 138 </p>
 139
 140 <p style="text-align: center">
 141   <img src="{{static}}/images/tut_analytics/screenshot04.png"
 142        style="width:683px;height:418px;"
 143        alt="Developer Tools window showing the __utm.gif request" />
 144 </p>
 145
 146 <h2 id="toc-tracking-events">Tracking events</h2>
 147
 148 <p>
 149   By configuring event tracking, you can determine which parts of your
 150   extension your users interact with the most.  For example, if you have
 151   three buttons users may click:
 152 </p>
 153
 154 <pre>
 155   &lt;button id='button1'>Button 1&lt;/button>
 156   &lt;button id='button2'>Button 2&lt;/button>
 157   &lt;button id='button3'>Button 3&lt;/button>
 158 </pre>
 159
 160 <p>
 161   Write a function that sends click events to Google Analytics:
 162 </p>
 163
 164 <pre>
 165   function trackButton(e) {
 166     _gaq.push(['_trackEvent', e.target.id, 'clicked']);
 167   };
 168 </pre>
 169
 170 <p>
 171   And use it as an event handler for each button's click:
 172 </p>
 173
 174 <pre>
 175   var buttons = document.querySelectorAll('button');
 176   for (var i = 0; i < buttons.length; i++) {
 177     buttons[i].addEventListener('click', trackButtonClick);
 178   }
 179 </pre>
 180
 181 <p>
 182   The Google Analytics event tracking overview page will give you metrics
 183   regarding how many times each individual button is clicked:
 184 </p>
 185
 186 <p style="text-align: center">
 187   <img src="{{static}}/images/tut_analytics/screenshot03.png"
 188        style="width:300px;height:482px;"
 189        alt="Analytics view of the event tracking data for a site." />
 190 </p>
 191
 192 <p>
 193   By using this approach, you can see which parts of your extension are
 194   under-or-overutilized.  This information can help guide decisions about UI
 195   redesigns or additional functionality to implement.
 196 </p>
 197
 198 <p>
 199   For more information about using event tracking, see the
 200   Google Analytics
 201   <a href="https://developers.google.com/analytics/devguides/collection/gajs/eventTrackerGuide">developer
 202   documentation</a>.
 203 </p>
 204
 205 <h2 id="toc-samplecode">Sample code</h2>
 206
 207 <p>
 208   A sample extension that uses these techniques is
 209   available in the Chromium source tree:
 210 </p>
 211
 212 <blockquote>
 213   <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/tutorials/analytics/">.../examples/tutorials/analytics/</a>
 214 </blockquote>