Tracking API Reference

Please check the official Piwik API documentation as well:

PiwikTracker

class piwikapi.tracking.PiwikTracker(id_site, request)

The Piwik tracker class

Parameters:
  • id_site (int) – Site ID
  • request (A Django-like request object) – Request
Return type:

None

LENGTH_VISITOR_ID = 16

Length of the visitor ID

KNOWN_PLUGINS = {'director': 'dir', 'quick_time': 'qt', 'silverlight': 'ag', 'java': 'java', 'gears': 'gears', 'real_player': 'realp', 'pdf': 'pdf', 'flash': 'fla', 'windows_media': 'wma'}

List of plugins Piwik knows

set_local_time(datetime)

Set the time

Parameters:datetime (datetime.datetime object) – Time
Return type:None
set_token_auth(token_auth)

Set the auth token for the request. The token can be viewed in the user management section of your Piwik install.

Parameters:token_auth (str) – Auth token
Return type:None
set_api_url(api_url)

Set which Piwik API URL to use

Parameters:api_url (str) – API URL
Return type:None
set_ip(ip)

Set the IP to be tracked. You probably want to use this as the request comes from your own server.

Requires setting the auth token.

Parameters:ip (str) – IP
Return type:None
set_browser_has_cookies()

Call this is the browser supports cookies

Return type:None
set_browser_language(language)

Set the browser language. Piwik uses this to guess the visitor’s origin when GeoIP is not enabled

Parameters:language (str) – Accept-Language
Return type:None
set_user_agent(user_agent)

Set the user agent. By default the original request’s UA is used.

Parameters:user_agent (str) – User agent
Return type:None
set_resolution(width, height)

Set the visitor’s screen width and height

Parameters:
  • width (int or str) – Screen width
  • height (int or str) – Screen height
Return type:

None

set_visitor_id(visitor_id)
Parameters:visitor_id (str) – Visitor I
Raises:InvalidParameter if the visitor_id has an incorrect length
Return type:None
set_debug_string_append(string)
Parameters:string (str) – str to append
Return type:None
set_url_referer(referer)

Set the referer URL

Parameters:referer (str) – Referer
Return type:None
set_url(url)

Set URL being tracked

Parameters:url (str) – URL
set_attribution_info(json_encoded)

NOT SUPPORTED

Set the attribution info for the visit, so that subsequent goal conversions are properly attributed to the right referer, timestamp, campaign name and keyword.

This must be a JSON encoded string that you would normally fetch from the Javascript API, see function getAttributionInfo() in http://dev.piwik.org/trac/browser/trunk/js/piwik.js

Parameters:json_encoded (string) – JSON encoded list containing attribution info
Raises:InvalidParameter if the json_encoded data is incorrect
Return type:none
set_force_visit_date_time(datetime)

Override the server date and time for the tracking request.

By default Piwik tracks requests for the “current” datetime, but this method allows you to track visits in the past. Time are in UTC.

Requires setting the auth token.

Parameters:datetime (datetime.datetime object) – datetime
Return type:None
get_visitor_id()

PARTIAL, no cookie support

If the user initiating the request has the Piwik first party cookie, this function will try and return the ID parsed from this first party cookie.

If you call this function from a server, where the call is triggered by a cron or script not initiated by the actual visitor being tracked, then it will return the random Visitor ID that was assigned to this visit object.

This can be used if you wish to record more visits, actions or goals for this visitor ID later on.

Return type:str
get_attribution_info()

NOT SUPPORTED

To support this we’d need to parse the cookies in the request obejct. Not sure if this makes sense...

Return the currently assigned attribution info stored in a first party cookie.

This method only works if the user is initiating the current request and his cookies can be read by this API.

Return type:string, JSON encoded string containing the referer info for goal conversion attribution
get_random_visitor_id()

Return a random visitor ID

Return type:str

NOT TESTED

By default, PiwikTracker will read third party cookies from the response and sets them in the next request.

Return type:None
do_track_page_view(document_title)

Track a page view, return the request body

Parameters:document_title (str) – The title of the page the user is on
Return type:str
do_track_action(action_url, action_type)

Track a download or outlink

Parameters:
  • action_url (str) – URL of the download or outlink
  • action_type (str) – Type of the action, either ‘download’ or ‘link’
Raises:

InvalidParameter if action type is unknown

Return type:

str

set_custom_variable(id, name, value, scope='visit')

Set a custom variable

See http://piwik.org/docs/custom-variables/

Parameters:
  • id (int) – Custom variable slot ID, 1-5
  • name (str) – Variable name
  • value (str) – Variable value
  • scope (str or None) – Variable scope, either visit or page, defaults to visit
Return type:

None

set_plugins(**kwargs)

Set supported plugins

>>> piwiktrackerinstance.set_plugins(flash=True)

See KNOWN_PLUGINS keys for valid values.

Parameters:kwargs (dict of {str: int}) – A plugin: version dict, e.g. {‘java’: 6}, see also KNOWN_PLUGINS
Return type:None
get_custom_variable(id, scope='visit')

PARTIAL, no cookie support

Returns the current custom variable stored in a first party cookie.

Parameters:
  • id (int) – Custom variable slot ID, 1-5
  • scope (str) – Variable scope, either visit or page
Return type:

mixed stuff TODO

PiwikTrackerEcommerce

class piwikapi.tracking.PiwikTrackerEcommerce(id_site, request)

The Piwik tracker class for ecommerce

add_ecommerce_item(sku, name=False, category=False, price=False, quantity=1)

Add an item to the ecommerce order.

This should be called before do_track_ecommerce_order() or before do_track_ecommerce_cart_update().

This method can be called for all individual products in the cart/order.

Parameters:
  • sku – Product SKU
  • name (str or None) – Name of the product
  • category (str, list or None) – Name of the category for the current category page or the product
  • price (int or None) – Price of the product
  • quantity – Product quantity, defaults to 1
Return type:

None

do_track_ecommerce_cart_update(grand_total)

Track a cart update (add/remove/update item)

On every cart update you must call add_ecommerce_item() for each item in the cart, including items which were in the previous cart. Items get deleted until they are re-submitted.

Parameters:grand_total (float) – Grand total revenue of the transaction, including taxes, shipping, etc.
Return type:str
do_track_ecommerce_order(order_id, grand_total, sub_total=False, tax=False, shipping=False, discount=False)

Track an ecommerce order

If the order contains items you must call add_ecommerce_item() first for each item.

All revenues will be individually summed and reported by Piwik.

Parameters:
  • order_id (str) – Unique order ID (required). Used to avoid re-recording an order on page reload.
  • grand_total (float) – Grand total revenue of the transaction, including taxes, shipping, etc.
  • sub_total (float or None) – Sub total amount, typicalle the sum of item prices for all items in this order, before tax and shipping
  • tax (float or None) – Tax amount for this order
  • shipping (float or None) – Shipping amount for this order
  • discount (float or None) – Discount for this order
Return type:

str

do_track_goal(id_goal, revenue=False)

Record a goal conversion

Parameters:
  • id_goal (int) – Goal ID
  • revenue (int (TODO why int here and not float!?)) – Revenue for this conversion
Return type:

str

set_ecommerce_view(sku=False, name=False, category=False, price=False)

Set the page view as an item/product page view, or an ecommerce category page view.

This method will set three custom variables of ‘page’ scope with the SKU, name and category for this page view.

On a category page you may set the category argument only.

Tracking product/category page views will allow Piwik to report on product and category conversion rates.

To enable ecommerce tracking see doc/install.rst

Parameters:
  • SKU (str or None) – Product SKU being viewed
  • name (str or None) – Name of the product
  • category (str, list or None) – Name of the category for the current category page or the product
  • price (float or None) – Price of the product
Return type:

None