Piwik Tracking API

  1. Two tracking methods: Image tracking, or using the API
  2. How to use the PHP Tracker API: example
  3. Tracking API PHP Client Reference
  4. Java Tracker class
  5. Python Tracker class
  6. API Reference
  7. Debugging the Tracking calls
  8. Tracking API REST documentation
  9. Example Tracking URL

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 client for Tracking API
  • Java client for Tracking API
  • Python client for Tracking API
  • Direct calls to the Piwik Tracking API

We will now look at each of these methods to record data in Piwik.

Two tracking methods: Image tracking, or using the API

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

Image Tracker code

The Image Tracker code can be used when Javascript is not allowed.

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 Image Tracker.
Note: the code doesn't use Javascript so Piwik will not be able to track some user information such as search keywords, referrers, screen resolutions, browser plugins and page titles.

<!-- Piwik Image Tracker -->
<img src="http://demo.piwik.org/piwik.php?idsite={$IDSITE}&amp;rec=1" style="border:0" alt="" />
<!-- End Piwik -->
The following parameters can also be passed to the image URL:
  • rec - (required) The parameter &rec=1 is required to force the request to be recorded
  • idsite - (required) Defines the Website ID being tracked
  • action_name - Defines the custom Page Title for this page view
  • urlref - The Referrer URL: must be set to the referrer URL used before landing on the page containing the Image tracker. For example, in PHP this value is accessible via 
    $_SERVER['HTTP_REFERER']
  • idgoal - The request will trigger the given Goal
  • revenue - Used with idgoal, defines the custom revenue for this conversion
  • and more! - There are many more parameters you can set beyond the main ones above. See the Tracking API documentation page.

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 (please 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://demo.piwik.org/';
    ?>
  • 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=''> code.
      Paste this code before the </body> code in your pages. <?php
      // Example 1: Tracks a pageview for Website id = {$IDSITE}
      echo '<img src="'. str_replace("&","&amp;", 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="'. str_replace("&","&amp;", Piwik_getUrlTrackGoal( $idSite = {$IDSITE}, $idGoal = 2, $customRevenue = 39)) . '" alt="" />';
      ?>
      The Advanced Image Tracker method is similar to using the standard Javascript Tracking code. 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);
      ?>

How to use the PHP Tracker API: example

The following code snippet is an example of how to track a Page View using the Tracking API PHP client.

$t = new PiwikTracker( $idSite = 1, ‘http://example.org/piwik/’);
// Optional function calls
$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->setPlugins($flash = true, $java = true, $director = false);
// set a Custom Variable called ‘Gender’
$t->setCustomVariable( 1, ‘gender’, ‘male’ );
// If you want to force the visitor IP, or force the server date time to a date in the past,
// it is required to authenticate the Tracking request by calling setTokenAuth
// You can pass the Super User token_auth or any user with ‘admin’ privilege on the website $idSite
$t->setTokenAuth( $token_auth );
$t->setIp( “134.10.22.1″ );
$t->setForceVisitDateTime( ’2011-04-05 23:55:02′ );
// if you wanted to force to record the page view or conversion to a specific visitorId
// $t->setVisitorId( “33c31e01394bdc63″ );
// Mandatory: set the URL being tracked
$t->setUrl( $url = ‘http://example.org/store/list-category-toys/’ );
// Finally, track the page view with a Custom Page Title
// In the standard JS API, the content of the <title> tag would be set as the page title
$t->doTrackPageView(‘This is the page title’);

Ecommerce tracking example
Here is an example showing how to track Ecommerce interactions on your website, using the PHP Tracking API. Usually, Ecommerce tracking is done using standard Javascript code, but it is very common to record Ecommerce interactions after the fact (for example, when payment is done with Paypal and user doesn’t come back on the website after purchase). For more information about Ecommerce tracking in Piwik, check out the documentation: Tracking Ecommerce in Piwik.

$t = new PiwikTracker( $idSite = 1, ‘http://example.org/piwik/’);
// Force IP to the actual visitor IP
$t->setTokenAuth( $token_auth );
$t->setIp( “134.10.22.1″ );
// Example 1: on a Product page, track an “Ecommerce Product view”
$t->setUrl( $url = ‘http://www.mystore.com/Endurance-Shackletons-Legendary-Antarctic-Expedition’ );
$t->setEcommerceView($sku = ‘SKU0011′, $name = ‘Endurance – Shackleton’, $category = ‘Books’);
$t->doTrackPageView( ‘Endurance Shackletons Legendary Antarctic Expedition – Mystore.com’);
// Example 2: Tracking Ecommerce Cart containing 2 products
$t->addEcommerceItem($sku = ‘SKU0011′, $name = ‘Endurance – Shackleton’ , $category = ‘Books’, $price = 17, $quantity = 1);
// Note that when setting a product category, you can specify an array of up to 5 categories to track for this product
$t->addEcommerceItem($sku = ‘SKU0321′, $name = ‘Amélie’ , $categories = array(‘DVD Foreign’,'Best sellers’,'Our pick’), $price = 25, $quantity = 1);
$t->doTrackEcommerceCartUpdate($grandTotal = 42);

// Example 3: Tracking Ecommerce Order
$t->addEcommerceItem($sku = ‘SKU0011′, $name = ‘Endurance – Shackleton’ , $category = ‘Books’, $price = 17, $quantity = 1);
$t->addEcommerceItem($sku = ‘SKU0321′, $name = ‘Amélie’ , $categories = array(‘DVD Foreign’,'Best sellers’,'Our pick’), $price = 25, $quantity = 1);
$t->doTrackEcommerceOrder($orderId = ‘B000111387′, $grandTotal = 55.5, $subTotal = 42, $tax = 8, $shipping = 5.5, $discount = 10);

Set the visitor IP, or the visit date/time
To set the visitor IP, or the date and time of the visit, or to force to record the visit (or page, or goal conversion) to a specific Visitor ID, you must call setTokenAuth( $token_auth ). The token_auth must be either the Super User token_auth, or the token_auth of any user with ‘admin’ permission for the website you are recording data against.

Track Ecommerce, Custom Variables, etc.
The PHP Tracking Client provides all features of the Javascript Tracker, in particular all Ecommerce Tracking, Custom Variable, etc. is also available in the PHP Tracking client. Functions are named the same as the Javascript functions.

Tracking API PHP Client Reference

See below the full reference for the PHP Client used to track visits, page views, actions or Goal conversions in Piwik.

Source: API documentation for the PiwikTracker class.

Java Tracker class

A Java client for the Piwik Tracking API was submitted by a Piwik user. The code and doc can be found in the Java Tracking Client for Piwik.

Python Tracker class

A complete Python client implementation of the Tracker API is also available at Piwik Tracking API Client in Python.

If you wish to contribute an implementation of the Piwik Tracker class in another language, please do so and send us an email and we will gladly list it here.

API Reference

If you are not using PHP, Java, or Javascript (for which clients are available), you might be looking for the REST API reference documentation so you can build your simple Piwik client to track your app or software analytics.

Debugging the Tracking calls

See: http://piwik.org/docs/tracking-api/reference/#toc-debugging-the-tracking-api-requests

Tracking API REST documentation

See: http://piwik.org/docs/tracking-api/reference/#toc-tracking-api-reference

Example Tracking URL

See: http://piwik.org/docs/tracking-api/reference/#toc-example-http-request-to-piwik-tracking-api

More information

In Piwik, we use the Tracking API PHP client in our Quality Assurance process, to generate fake (controlled) tracking requests used to test that reports are processed correctly. For more information, you can check out some of the code in Main.test.php, and learn more about our QA process.

See also these related FAQ entries

Feedback on this page

Have you found an error in this page, or do you think some information is missing or not clear? We appreciate you taking the time to send us your suggestions and feedback on this page.

2012 © Piwik.org.
Contact Us

Leading Open Source Web Analytics
Design by clearcode
And built on Free Software!