| <h1>Tutorial: Google Analytics</h1> |
| |
| |
| <p>This tutorial demonstrates using Google Analytics to track the usage of your |
| extension.</p> |
| |
| <h2 id="toc-requirements">Requirements</h2> |
| <p> |
| This tutorial expects that you have some familiarity writing extensions for |
| Google Chrome. If you need information on how to write an extension, please |
| read the <a href="getstarted.html">Getting Started tutorial</a>. |
| </p> |
| |
| <p> |
| You will also need a <a href="http://www.google.com/analytics">Google |
| Analytics account</a> set up to track your extension. Note that when setting |
| up the account, you can use any value in the Website's URL field, as your |
| extension will not have an URL of its own. |
| </p> |
| |
| <p style="text-align: center"> |
| <img src="{{static}}/images/tut_analytics/screenshot01.png" |
| style="width:400px;height:82px;" |
| alt="The analytics setup with info for a chrome extension filled out." /> |
| </p> |
| |
| <h2 id="toc-installing">Installing the tracking code</h2> |
| |
| <p> |
| The standard Google Analytics tracking code snippet fetches a file named |
| <code>ga.js</code> from an SSL protected URL if the current page |
| was loaded using the <code>https://</code> protocol. <strong>Chrome |
| extensions and applications may <em>only</em> use the SSL-protected version of |
| <code>ga.js</code></strong>. Loading <code>ga.js</code> over insecure HTTP is |
| disallowed by Chrome's default <a href="contentSecurityPolicy.html">Content |
| Security Policy</a>. This, plus the fact that Chrome extensions are hosted |
| under the <code>chrome-extension://</code> schema, requires a slight |
| modification to the usual tracking snippet to pull <code>ga.js</code> directly |
| from <code>https://ssl.google-analytics.com/ga.js</code> instead of the |
| default location. |
| </p> |
| |
| <p> |
| Below is a modified snippet for the |
| <a href="http://code.google.com/apis/analytics/docs/tracking/asyncTracking.html">asynchronous |
| tracking API</a> (the modified line is bolded): |
| </p> |
| |
| <pre> |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| <strong>ga.src = 'https://ssl.google-analytics.com/ga.js';</strong> |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| </pre> |
| |
| <p> |
| You'll also need to ensure that your extension has access to load the resource |
| by relaxing the default content security policy. The policy definition in your |
| <a href="manifest.html"><code>manifest.json</code></a> might look like: |
| </p> |
| |
| <pre>{ |
| ..., |
| "content_security_policy": "script-src 'self' https://ssl.google-analytics.com; object-src 'self'", |
| ... |
| }</pre> |
| |
| <p> |
| Here is a popup page (<code>popup.html</code>) which loads the asynchronous |
| tracking code via an external JavaScript file (<code>popup.js</code>) and |
| tracks a single page view: |
| </p> |
| |
| <pre>popup.js: |
| ========= |
| |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-XXXXXXXX-X']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = 'https://ssl.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| |
| popup.html: |
| =========== |
| <!DOCTYPE html> |
| <html> |
| <head> |
| ... |
| <script src="popup.js"></script> |
| </head> |
| <body> |
| ... |
| </body> |
| </html> |
| </pre> |
| |
| <p> |
| Keep in mind that the string <code>UA-XXXXXXXX-X</code> should be replaced |
| with your own Google Analytics account number. |
| </p> |
| |
| <h2 id="toc-tracking-pageviews">Tracking page views</h2> |
| |
| <p> |
| The <code>_gaq.push(['_trackPageview']);</code> code will track a single |
| page view. This code may be used on any page in your extension. When |
| placed on a background page, it will register a view once per browser |
| session. When placed on a popup, it will register a view once every time |
| the popup is opened. |
| </p> |
| |
| <p> |
| By looking at the page view data for each page in your extension, you can |
| get an idea of how many times your users interact with your extension per |
| browser session: |
| </p> |
| |
| <p style="text-align: center"> |
| <img src="{{static}}/images/tut_analytics/screenshot02.png" |
| style="width:300px;height:119px;" |
| alt="Analytics view of the top content for a site." /> |
| </p> |
| |
| <h2 id="toc-debugging">Monitoring analytics requests</h2> |
| |
| <p> |
| To ensure that tracking data from your extension is being sent to Google |
| Analytics, you can inspect the pages of your extension in the |
| Developer Tools window (see the |
| <a href="tut_debugging.html">debugging tutorial</a> for more information). |
| As the following figure shows, you should see requests for a file named |
| <strong>__utm.gif</strong> if everything is set up correctly. |
| </p> |
| |
| <p style="text-align: center"> |
| <img src="{{static}}/images/tut_analytics/screenshot04.png" |
| style="width:683px;height:418px;" |
| alt="Developer Tools window showing the __utm.gif request" /> |
| </p> |
| |
| <h2 id="toc-tracking-events">Tracking events</h2> |
| |
| <p> |
| By configuring event tracking, you can determine which parts of your |
| extension your users interact with the most. For example, if you have |
| three buttons users may click: |
| </p> |
| |
| <pre> |
| <button id='button1'>Button 1</button> |
| <button id='button2'>Button 2</button> |
| <button id='button3'>Button 3</button> |
| </pre> |
| |
| <p> |
| Write a function that sends click events to Google Analytics: |
| </p> |
| |
| <pre> |
| function trackButton(e) { |
| _gaq.push(['_trackEvent', e.target.id, 'clicked']); |
| }; |
| </pre> |
| |
| <p> |
| And use it as an event handler for each button's click: |
| </p> |
| |
| <pre> |
| var buttons = document.querySelectorAll('button'); |
| for (var i = 0; i < buttons.length; i++) { |
| buttons[i].addEventListener('click', trackButtonClick); |
| } |
| </pre> |
| |
| <p> |
| The Google Analytics event tracking overview page will give you metrics |
| regarding how many times each individual button is clicked: |
| </p> |
| |
| <p style="text-align: center"> |
| <img src="{{static}}/images/tut_analytics/screenshot03.png" |
| style="width:300px;height:482px;" |
| alt="Analytics view of the event tracking data for a site." /> |
| </p> |
| |
| <p> |
| By using this approach, you can see which parts of your extension are |
| under-or-overutilized. This information can help guide decisions about UI |
| redesigns or additional functionality to implement. |
| </p> |
| |
| <p> |
| For more information about using event tracking, see the |
| Google Analytics |
| <a href="https://developers.google.com/analytics/devguides/collection/gajs/eventTrackerGuide">developer |
| documentation</a>. |
| </p> |
| |
| <h2 id="toc-samplecode">Sample code</h2> |
| |
| <p> |
| A sample extension that uses these techniques is |
| available in the Chromium source tree: |
| </p> |
| |
| <blockquote> |
| <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/tutorials/analytics/">.../examples/tutorials/analytics/</a> |
| </blockquote> |