Piwik Tracking API

Docs › Piwik Tracking API

The standard way of recording data in Piwik is to use the Javascript Tracking tag. This works well for most users where pasting a Javascript code in the page footer is not an issue.

There are other frequent cases however where Javascript can not be used: Ebay pages, MySpace pages, but also Software Apps, iPhone or Android apps, mobile websites, etc.

In these cases, you can use alternative ways to record visitors, visits, pages and Goal conversions in Piwik:

Simple Image Tracker
Advanced Image Tracker
PHP Piwik Tracking API

In the following, replace {$IDSITE} with your Piwik website ID, and replace http://www.example.org/piwik/ with your Piwik URL.

Two tracking method: Image tracking, or using the API

Image Tracker tag

The Simple Image Tracker tag can be used when Javascript is disallowed.

Some websites like MySpace or eBay will not allow users to add Javascript to their profile but accept HTML. In this case, you can still track visits with Piwik using the simple Image Tracker.
Note: the code doesn't use Javascript so Piwik will not be able to track some user information such as search keywords, referer websites, screen resolutions, plugin support and page titles.


<!-- Piwik Image Tracker -->

<img src="http://www.example.org/piwik/piwik.php?idsite={$IDSITE}&rec=1" style="border:0" alt="" />

<!-- End Piwik -->

The following parameters can also be passed to the image URL:

action_name - Defines the custom Page Title for this page view
idgoal - The request will trigger the given Goal
revenue - Used with idgoal, defines the custom revenue for this conversion

Piwik Tracking API (Advanced users)

It is also possible to call the Piwik Tracking API using your favorite programming language.

The Piwik Tracking API allows to trigger visits (page views and Goal conversions) from any environment (Desktop App, iPhone or Android app, Mobile website, etc.).

We currently provide a PHP client to call the API from your PHP projects. If you would like to contribute a version of the client in another programming language (Python, Java, Ruby, Perl, etc.) please create a ticket in our developer area (attach the client code to the ticket).

Follow these instructions to get started with the Tracking API:

Click here to download the file PiwikTracker.php
Upload the PiwikTracker.php file in the same path as your project files
Copy the following code, then paste it onto every page you want to track. <?php // -- Piwik Tracking API init -- require_once "/path/to/PiwikTracker.php"; PiwikTracker::$URL = 'http://www.example.org/piwik/'; ?>
Choose a Tracking method, then paste the code onto every page you want to track.
- Method 1: Advanced Image Tracker
  
  The client is used to generate the tracking URL that is wrapped inside a HTML <img src=''> tag.
  Paste this code before the </body> tag in your pages. <?php // Example 1: Tracks a pageview for Website id = {$IDSITE} echo '<img src="'. Piwik_getUrlTrackPageView( $idSite = {$IDSITE}, $customTitle = 'This title will appear in the report Actions > Page titles') . '" alt="" />'; // Example 2: Triggers a Goal conversion for Website id = {$IDSITE} and Goal id = 2 // $customRevenue is optional and is set to the amount generated by the current transaction (in online shops for example) echo '<img src="'. Piwik_getUrlTrackGoal( $idSite = {$IDSITE}, $idGoal = 2, $customRevenue = 39) . '" alt="" />'; ?>
  The Advanced Image Tracker method is similar to using the standard Javascript Tracking Tag. However, some user settings are not detected (resolution, local time, plugins and cookie support).
- Method 2: HTTP Request
  
  You can also query the Piwik Tracker API remotely via HTTP. This is useful for environment where you can't execute HTML nor Javascript.
  Paste this code anywhere in your code where you wish to track a user interaction. <?php $piwikTracker = new PiwikTracker( $idSite = {$IDSITE} ); // You can manually set the visitor details (resolution, time, plugins, etc.) // See all other ->set* functions available in the PiwikTracker.php file $piwikTracker->setResolution(1600, 1400); // Sends Tracker request via http $piwikTracker->doTrackPageView('Document title of current page view'); // You can also track Goal conversions $piwikTracker->doTrackGoal($idGoal = 1, $revenue = 42); ?>

PiwikTracker PHP Class API

Example call to track a pageview
$t = new PiwikTracker( $idSite = 1, 'http://example.org/piwik/'); // Optional tracking $t->setUserAgent( "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB) Firefox/3.6.6"); $t->setBrowserLanguage('fr'); $t->setLocalTime( '12:34:06' ); $t->setResolution( 1024, 768 ); $t->setBrowserHasCookies(true); $t->setCustomData( array('id' => 10, 'name' => 'test') ); $t->setPlugins($flash = true, $java = true, $director = false); // Mandatory $t->setUrl( $url = 'http://example.org/store/list-category-toys/' ); $t->doTrackPageView('This is the page title');
For more information, read the API documentation for the PiwikTracker class.

In Piwik, we use the Tracking API client in our test code, to generate fake (controlled) tracking requests used to test that reports are processed correctly. Check out some of the code in Main.test.php (or learn more about our QA process)

Debugging the Tracking calls

To verify that your data is being tracked properly, if you are writing a Tracker plugin, or if tracking doesn't work as expected, you can enable debug logging in the Piwik tracking file piwik.php.

In the file path/to/piwik/piwik.php, you can set $GLOBALS['PIWIK_TRACKER_DEBUG'] = true;

Tracking requests will then output the tracking logs rather than displaying a 1*1 transparent GIF beacon. You can then look at the http requests to piwik.php using a tool like Firebug Net panel.