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

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