Differences within this fork

This fork tries to render this library usable under Python 2 and 3. It requires requests and six.

It is a work in progress and is not yet tested in production environments under 2 or 3. Test suite passes using 2.7.7 and 3.4.1. At some point, if it turns out to be stable enough, I may try to merge it or something like it back into the ancestral repo, if the analytics-pros folks are interested.

It eliminates the use of HTTPLog for testing and uses the mock library instead. This prevents the test suite from making actual requests, but requires that one trust the requests library to do its job.

Install this fork with:

pip install -e git+https://github.com/eviljosh/universal-analytics-python.git#egg=universal-analytics-python

The remaining documentation is unchanged.

Universal Analytics for Python

This library provides a Python interface to Google Analytics, supporting the Universal Analytics Measurement Protocol, with an interface modeled (loosely) after Google's analytics.js.

NOTE this project is reasonably feature-complete for most use-cases, covering all relevant features of the Measurement Protocol, however we still consider it beta. Please feel free to file issues for feature requests.

Contact

Email: opensource@analyticspros.com

Installation

The easiest way to install universal-analytics is directly from PyPi using pip by running the following command:

pip install universal-analytics-python

Or use latest code:

pip install -e git+https://github.com/analytics-pros/universal-analytics-python.git#egg=universal-analytics-python-dev

Otherwise you can download source code and install it directly:

python setup.py install

Usage

For the most accurate data in your reports, Analytics Pros recommends establishing a distinct ID for each of your users, and integrating that ID on your front-end web tracking, as well as back-end tracking calls. This provides for a consistent, correct representation of user engagement, without skewing overall visit metrics (and others).

A simple example:

from UniversalAnalytics import Tracker

tracker = Tracker.create('UA-XXXXX-Y', client_id = CUSTOMER_UNIQUE_ID)
tracker.send('event', 'Subscription', 'billing')

Please see the tests/main.py script for additional examples.

This library support the following tracking types, with corresponding (optional) arguments:

• pageview: [ page path ]
• event: category, action, [ label [, value ] ]
• social: network, action [, target ]
• timing: category, variable, time [, label ]

Additional tracking types supported with property dictionaries:

• transaction
• item
• screenview
• exception

Property dictionaries permit the same naming conventions given in the analytics.js Field Reference, with the addition of common spelling variations, abbreviations, and hyphenated names (rather than camel-case). These are also demonstrated in the tests/main.py file.

Further, the property dictionaries support names as per the Measurement Protocol Parameter Reference, and properties/parameters can be passed as named arguments.

Example:

  # as python named-arguments
  tracker.send('pageview', path = "/test", title = "Test page") 
  
  # as property dictionary 
  tracker.send('pageview', {
    'path': "/test",
    'title': "Test page"
  })

Features not implemented

• Throttling

We're particularly interested in the scope of throttling for back-end tracking for users who have a defined use-case for it. Please contact us if you have such a use-case.

Tests

Run unit tests with: python -m unittest discover test/

License

universal-analytics-python is licensed under the BSD license