Extensions Docs Server: Doc conversion script

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

+<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="gettingstarted.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:
+===========
+&lt;!DOCTYPE html>
+&lt;html>
+ &lt;head>
+   ...
+  &lt;script src="popup.js">&lt;/script>
+ &lt;/head>
+ &lt;body>
+   ...
+ &lt;/body>
+&lt;/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>
+  &lt;button id='button1'>Button 1&lt;/button>
+  &lt;button id='button2'>Button 2&lt;/button>
+  &lt;button id='button3'>Button 3&lt;/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 the event tracking API, see the
+  Google Analytics
+  <a href="http://code.google.com/apis/analytics/docs/tracking/eventTrackerOverview.html">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>
+</p>