The Google Analytics Measurement Protocol API lets you add data to your GA account that hasn’t been triggered by a user visiting a web page. Since it’s so flexible, you can use the Measurement Protocol to import almost any kind of data into your GA account, from orders taken offline in a shop, or on marketplaces such as eBay and Amazon, to customer-specific metrics for use in custom paid search audiences.
While the Measurement Protocol API is fairly straightforward to use, you do need to carefully construct the “payload” you pass to the API’s “endpoint” in order for things to work as expected. To make this easier, I created a simple Python package called PyGAMP to handle it. Here’s how to use it. This currently supports the following features of Google Analytics Measurement Protocol:
First, open a Jupyter notebook and install my PyGAMP package using pip3 install pygamp
, then import pygamp as pg
and uuid
. No credentials are required. You can import data into any Google Analytics account using just the tracking ID parameter, which is often visible of the source code of the page itself. The tracking ID will look like this: UA-123456-1
.
import pygamp as pg
import uuid
When you insert new data into Google Analytics there is a delay between the data being sent and its appearance within your main reports. However, you can see the data via the Realtime reports section of the GA interface a second or time after they hit GA.
Irrespective of the data you want to push to Google Analytics, you’ll require two things: a Universal Analytics property ID, and a client ID. The property ID, i.e. UA-123456789-1
, defines the account you want to push your data into. The client ID “pseudonymously” identifies a user, device, or browser, and is stored in a first-party cookie.
The client ID uses the random UUID v4 format and looks like this: 35009a79-1a05-49d7-b876-2b884d0f825b
. Specific client IDs can be extracted from the user’s cookie and stored in your database, allowing you to associate data that you push into GA with a specific user. However, in most cases you can just create a random UUID and push the data in with this. I’d suggest setting these up and assigning them to variables.
client_id = str(uuid.uuid4())
property_id = 'UA-123456789-2'
To make it clearer what each of the function arguments refer to I have added their names, but you don’t need to do this in your production code, unless you want to. To send a pageview, we can call pageview()
and pass in the cid
and property_id
, and then include the document_path
, document_hostname
, and document_title
.
pg.pageview(
cid=client_id,
property_id=property_id,
document_path='/hello',
document_hostname='example.com',
document_title='Hello'
)
The social()
function allows you to insert social interaction data into Google Analytics. This requires a social_action
, such as like
, the social_network
, i.e. facebook
, and the social_target
.
pg.social(
cid=client_id,
property_id=property_id,
social_action='like',
social_network='facebook',
social_target='/home'
)
Data on promotions can be added using the promotion_impression()
and promotion_click()
functions. These take a range of arguments defining the type and position of the promotion to record when each one was viewed and clicked.
pg.promotion_impression(
cid=client_id,
property_id=property_id,
document_hostname='example.com',
document_path='about-us',
document_title='About us',
promotion_index=2,
promotion_id='PROMO1',
promotion_name='Summer sale',
promotion_creative='Summer',
promotion_position='Slot 1'
)
pg.promotion_click(
cid=client_id,
property_id=property_id,
promotion_index=2,
promotion_id='PROMO1',
promotion_name='Summer sale',
promotion_creative='Summer',
promotion_position='Slot 1'
)
Events are perhaps the most useful feature in the whole of Google Analytics and let you record pretty much anything you like. They’re commonly used for tracking things like the products added to baskets, users filling in forms, and loads of other things. They’re easily created using the event()
function.
pg.event(
cid=client_id,
property_id=property_id,
category='Products',
action='Added to cart',
label='XYZ',
value=3,
non_interactive=0
)
Custom dimensions are one feature that definitely does need to be used with the actual client ID of the user, since they associate data to that individual within Google Analytics. For example, you might extract the client ID from the GA cookie, store it in your database, and then calculate customer-specific metrics via a model and then push the data back into GA.
pg.custom_dimension(
cid=client_id,
property_id=property_id,
index=2,
value='Analytics'
)
Similarly, custom metrics are associated with specific individuals, so need to be used with the user’s specific client_id
in order to work correctly. As with custom dimensions, these map to the index
of a specific metric that has already been created in GA.
pg.custom_metric(
cid=client_id,
property_id=property_id,
index=2,
value='99.99'
)
If you have retail premises, or take orders via marketplaces such as Amazon and eBay, and you want to add these orders to your Google Analytics account, you can use the enhanced_transaction()
function to push the data in. To do this, the first step is to create a dictionary (which I’ve called basket
) which contains the data on the products you want to add.
basket = {
1: {'product_id': 'ABC1',
'product_name': 'Product 1',
'product_price': 19.99,
'product_quantity': 1,
'product_brand': 'Apple',
'product_category': 'Phones',
'product_variant': '256GB',
},
2: {'product_id': 'ABC2',
'product_name': 'Product 2',
'product_price': 20.99,
'product_quantity': 2,
'product_brand': 'Apple',
'product_category': 'Phones',
'product_variant': '500GB',
},
3: {'product_id': 'ABC3',
'product_name': 'Product 3',
'product_price': 39.99,
'product_quantity': 3,
'product_brand': 'Apple',
'product_category': 'Phones',
},
}
Next, we can use the enhanced_transaction()
to push in the data on the transaction, along with the basket
dictionary containing the details on the items within.
pg.enhanced_transaction(
cid=client_id,
property_id=property_id,
document_hostname='example.com',
document_path='/order',
document_title='Order complete',
transaction_id='12345',
transaction_revenue=199.99,
transaction_tax=40.00,
transaction_shipping=0.00,
transaction_coupon='SALE',
items=basket)
Refunds can also be processed in Google Analytics using PyGAMP. These can either be done at the transaction level using refund_transaction()
or at the item level using refund_items()
. This allows you to remove any refunded transactions or items from your data, so your marketing team don’t get a false impression on what revenue was generated.
pg.refund_transaction(
cid=client_id,
property_id=property_id,
transaction_id='124698938'
)
pg.refund_items(
cid=client_id,
property_id=property_id,
transaction_id='124698938',
item_code='XYZ1',
item_quantity=1
)
Exceptions, such as application errors or site issues, can be recorded in Google Analytics using the exception()
function. This takes an exception_description
argument stating the name of the exception, and an integer value in exception_fatal
which is set to 1 on fatal exceptions or 0 on non-fatal exceptions.
pg.exception(
cid=client_id,
property_id=property_id,
exception_description='Payment error',
exception_fatal=0
)
Another app specific feature is the screenview, which can be pushed in using the screenview()
function. While these are designed for mobile apps, there’s no reason why you should use them to monitor data science applications, such as models.
pg.screenview(
cid=client_id,
property_id=property_id,
app_name='Angry Birds',
app_version='1.0',
screen_name='Home',
app_id='1234',
app_installer_id='Apple'
)
Matt Clarke, Friday, March 12, 2021