Introduction
============
collective.googleanalytics is a product that integrates Plone with Google
Analytics. It includes both tracking and reporting functionality. The product
enables easy tracking of the standard Google statistics as well as external
links, e-mail address clicks and file downloads. It also defines Analytics
reports that are used to query Google and display the results using Google
Visualizations. Reports are Zope objects that can be imported and exported
using GenericSetup XML and modified on a site-by-site basis. The product
currently provides a portlet that can display results of reports as well
as a control panel for authorizing your site and configuring settings.

.. contents::


.. image:: https://secure.travis-ci.org/collective/collective.googleanalytics.png
    :target: http://travis-ci.org/collective/collective.googleanalytics


Installation
============
To install collective.googleanalytics, add it to the eggs section of your buildout. Then
re-run buildout and restart Zope.

On Plone 3
----------

On Plone 3 it is recommended to use the following version pins::

  [versions]
  collective.googleanalytics = 1.4.1
  gdata = 2.0.17
  simplejson = 2.3.3

Configuration
=============
When you install the product from the Plone Add-ons control panel, a new
control panel called Google Analytics will be added to your Plone site.
In this control panel, you can authorize the site to access your Google
Analytics data. If you receive an error when you attempt to authorize, see
the section on `Registering a Domain`_ below.

After authorizing your site, you can select the profile where you want to
track analytics for this site. Choose a profile from the dropdown menu. If you
do not see any profiles listed, make sure that your Google Analytics account
has access to at least one profile. Also, be sure to remove any Google
Analytics tracking code that you may have pasted in the Site control panel.

Once you have selected a profile for tracking, you can choose which tracking
plugins to enable. Tracking plugins allow you to track events on your site
in Google Analytics in addition to the normal data on page views and visits.
Which plugins you have available to you depends on which products you have
installed. For information on the default tracking plugins, see the
section on `Tracking Plugins`_ below.

Finally, you can choose roles to exclude from tracking. Google Analytics
data will not be recorded for users with the selected roles. Note that this
setting does not affect the inclusion of scripts specified in the Site
control panel.

On the settings tab, you can also configure the amount of time, in minutes,
that account information and report results will be cached, reducing the need
to query Google. Sixty minutes is the default caching interval.

Registering a Domain
====================
When you authorize your site to access your Google Analytics data, you may
receive an error::

    The site "http://example.com" has not been registered.

When this happens, you need to register your domain with Google before you
can authorize your site. Follow steps 1-3 of Google's `directions for
registering a new domain`__. In step two, you can upload the file provided
by Google to your Plone site root. Be sure to use the File content type, and
make sure that the short name matches the filename specified by Google.

__ http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html#new

Tracking Plugins
================

collective.googleanalytics ships with four tracking plugins:

Comments
    This plugin records a tracking event in Google Analytics for each comment
    created on your site.

Email links
    This plugin records a tracking event in Google Analytics each time a
    visitor clicks on a "mailto:" link.

External links
    This plugin records a tracking event in Google Analytics each at time a
    visitor clicks on a link with a domain name different from the domain
    name of your site.

File downloads
    This plugin records a tracking event in Google Analytics each time a
    visitor clicks on a l