mirumee / google-measurement-protocol

A Python implementation of Google Analytics Measurement Protocol

google-measurement-protocol

A Python implementation of Google Analytics Measurement Protocol

Transaction handling depends on the prices library.

Generating a client ID

Google strongly encourages using UUID version 4 as unique user handles. It's up to you to generate and persist the ID between actions, just make sure that all actions performed by the same user are reported using the same client ID.

import uuid

client_id = uuid.uuid4()

Reporting a page view

There are two ways to obtain a page view data to send to Google Analytics:

pageview(path[, host_name=None][, title=None][, language=None][, referrer=None])

pageview(location='http://example.com/my-page/?foo=1'[, title=None][, language=None][, referrer=None])

Example:

from google_measurement_protocol import pageview, report

data = pageview(path='/my-page/', title='My Page', referrer='http://example.com/')
report('UA-123456-1', client_id, data)

Reporting an event

Use the event function to obtain data:

event('category', 'action'[, label=None][, value=None])

Example:

from google_measurement_protocol import event, report

data = event('profile', 'user_registered')
report('UA-123456-1', client_id, data)

Reporting a transaction

First create Items to describe the contents of the transaction:

item(name, unit_price[, quantity=None][, item_id=None][, category=None])

Then the transaction itself:

transaction(transaction_id, items, revenue[, tax=None][, shipping=None][, affiliation=None])

Example:

from google_measurement_protocol import item, report, transaction
from prices import Money

transaction_id = '0001'  # any string should do
items = [
    item('My awesome product', Money(10, 'EUR'), quantity=2),
    item('Another product', Money(17, 'EUR'))]
data = transaction(transaction_id, items, Money(37, 'EUR'))
report('UA-123456-1', client_id, data)

Reporting an extended ecommerce purchase

For Extended Ecommerce we have implemented Purchase tracking, please note this will add an event automatically, as required by Google Analytics.

First use enhanced_items to describe the contents of the transaction:

enhanced_item(
    name, unit_price[, quantity=None][, item_id=None][, category=None]
    [, brand=None][, variant=None])

Then the enhanced_purchase itself:

enhanced_purchase(
    transaction_id, items, revenue, url_page[, tax=None][, shipping=None]
    [, host=None][, affiliation=None])

Please note you have to add an explicit path when creating your enhanced_purchase instance.

Example:

from google_measurement_protocol import enhanced_item, enhanced_purchase, report

transaction_id = '0001'  # any string should do
items = [
    enhanced_item('My awesome product', Money(10, 'USD'), quantity=2),
    enhanced_item('Another product', Money(15, 'USD'))]
data = enhanced_purchase(transaction_id, items, Money(27, 'USD'), '/cart/')
report('UA-123456-1', client_id, data)

Reporting extra data

In adition to documented arguments, all functions accept any number of extra named arguments, that are then in the data.

For example. to include language parameter in sent event, you may do this:

from google_measurement_protocol import event, report

data = event('profile', 'user_registered', ul='en-us')
report('UA-123456-1', client_id, data)

report also supports passing extra data, which is then added to every payload sent to API. This example is equal to previous one:

from google_measurement_protocol import event, report

data = event('profile', 'user_registered')
report('UA-123456-1', client_id, data, ul='en-us')

You can also pass extra_headers to report() function to submit additional information. It is passed directly as additional headers to requests library. This is currently the only way to pass User-Agent.

Example:

from google_measurement_protocol import PageView, report, SystemInfo

data = pageview(path='/my-page/', title='My Page', referrer='http://example.com/')
headers = {'user-agent': 'my-user-agent 1.0'}
report('UA-123456-1', client_id, data, extra_header=headers)

google-measurement-protocol's Issues

Make the network request asynchronous

Blocking the server code is unrealistic in most cases. The network request should be done asynchronously.

Would you consider merging something like the following commit that uses a separate thread?

adityar7@770d199

Reading Google Analytics Measurement Protocol ?

Hi,
How can I use it to read the "Google Analytics Measurement Protocol"?
That is: receive GA data on the server and put it in my own DB?

• Ed

python 2.x not supported

Due to extensive use of function annotations, it is impossible to use the library with python 2.x code
As I am able to python2.7 -m pip install google-measurement-protocol this gives a false impression that the library is usable
It's a pity that it's not ...

Quotes for url_page

When sending an url_page for EnhancedPurchase I end up seeing quotes in the report. Any clues why this might be the case?

Support more extra data/parameters

Currently extra_info can be used to add extra parameters. But only SystemInfo is documented as available.

I started creating a CustomDimension class based on the impl of SystemInfo, but I also needed other parameters (session control/override).
I ended up just passing a list of dicts into the extra_info parameter, which works but is kinda 'undocumented API'?
I think the request method should either allow a list 'extra data class instances' (Requestables)? Or document the 'list of dicts' as acceptable input...?

`enhanced_item` accepting a float as a quantity

Is it possible to supply a float as the quantity in enhanced_item? I'm not sure how Google deals with this, but I have weight based products as well as individual units.

It's possible to multiply this by 100 to get the quantity in grams, e.g. 0.5 kg of carrots becomes 500 grams - this feels messy from the reporting side.

Send uip using systeminfo

Hey,

In Saleor I want to send uip as an additional attribute. This is used to provide provide location data to Google Measurement Protocol. I managed to do this without any changes to google measurement protocol but it's probably not the "correct" way, as it involves sending a dictionary instead of a SystemInfo instance.

Saleor version:

My version

def report_view(client_id, ip, path, language, headers):
    host_name = headers.get('HTTP_HOST', None)
    referrer = headers.get('HTTP_REFERER', None)
    pv = ga.PageView(path, host_name=host_name, referrer=referrer)
    #extra_info = ga.SystemInfo(language=language) #old line
    extra_info = [{'ul': language, 'uip': ip}] #new line
    extra_headers = {}
    user_agent = headers.get('HTTP_USER_AGENT', None)
    if user_agent:
        extra_headers['user-agent'] = user_agent
    _report(client_id, pv, extra_info=extra_info, extra_headers=extra_headers)

I was thinking of making a pull request to Saleor to allow sending the uip (possibly configurable by a setting). But I think the way I'm doing, using a dictionary is not the correct way. But the SystemInfo class confuses me. Is it possible to modify it to add additional, optional attributes such as uip.

Change of User-Agent

Hits are not getting through to GA server unless the user-agent is changed to something else using extra headers. It must be different from python-requests/x.xx.x

Sample
report(google_id, visitor_id, data, extra_headers={"User-Agent": "YourFabulousAgent/0.1"})

fix url tracking

https://www.google-analytics.com/collect

https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide