Tracking API

Javascript client for Tracking API

This is default recommended client. Learn more at: developer.matomo.org/api-reference/tracking-javascript

Using the Javascript client works well for most users where pasting a Javascript code in the page footer is not an issue.

Tracking API Clients

Sometimes you cannot use JavaScript to track data with Matomo. Whether you develop iOS apps, Android apps, Titanium apps, or apps written in PHP, Java, C#, C++, Python, etc. you can use a native client to track the data in Matomo.

Learn more in Tracking API Clients and SDKs

Tracking API Reference

If you are not using Javascript, PHP, Java, Python, C#, C++, Python or Objective -C (for which clients are available), you can still directly call the Tracking Web API over HTTPS.

The Tracking Web API Reference documents the various parameters and features of the Tracking API.

Use case: Tracking data using the php client

We will now look at some of these methods to record data in Matomo. In the following, replace {$IDSITE} with your Matomo website ID, and replace http://piwik.example.org/ with your Matomo 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 Matomo using the Image Tracker.Note: the code doesn’t use Javascript so Matomo will not be able to track some user information such as search keywords, referrers, screen resolutions, browser plugins and page titles. The image tracker code also does not create first party tracking cookies which results in some information being lost.

  1. <!-- Matomo Image Tracker -->
  2. <img src="https://piwik.example.org/piwik.php?idsite={$IDSITE}&amp;rec=1" style="border:0" alt="" />
  3. <!-- End Matomo -->

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
  • bots – Set &bots=1 to track all requests to the tracking image, including from bots and robots
  • and more! – There are many more parameters you can set beyond the main ones above. See the Tracking API documentation page.

Matomo Tracking API (Advanced users)

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

Follow these instructions to get started with the PHP Tracking Web API client:

  • Click here to download the file PiwikTracker.php (You may need to right click this link and select Save Page As)
  • 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.
  1. <?php 
  2. // -- Matomo Tracking API init -- 
  3. require_once "/path/to/PiwikTracker.php";
  4. PiwikTracker::$URL = 'http://piwik.example.org/';
  5. ?>

  • Choose a Tracking method, then paste the code onto every page you want to track.

    • Method 1: Advanced Image TrackerThe client is used to generate the tracking URL that is wrapped inside a HTML code.Paste this code before the code in your pages.
  1. <?php 
  2. // Example 1: Tracks a pageview for Website id = {$IDSITE}
  3. echo '<img src="'. str_replace("&","&amp;", Piwik_getUrlTrackPageView( $idSite = {$IDSITE}, $customTitle = 'This title will appear in the report Actions > Page titles')) . '" alt="" />';
  4. // Example 2: Triggers a Goal conversion for Website id = {$IDSITE} and Goal id = 2
  5. // $customRevenue is optional and is set to the amount generated by the current transaction (in online shops for example)
  6. echo '<img src="'. str_replace("&","&amp;", Piwik_getUrlTrackGoal( $idSite = {$IDSITE}, $idGoal = 2, $customRevenue = 39)) . '" alt="" />';
  7. ?>

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 RequestYou can also query the Matomo 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.
  1. <?php 
  2. $piwikTracker = new PiwikTracker( $idSite = {$IDSITE} );
  4. // Specify an API token with at least Write permission, so the Visitor IP address can be recorded 
  5. // Learn more about token_auth: https://matomo.org/faq/general/faq_114/
  6. $piwikTracker->setTokenAuth('my_token_auth_value_here');
  8. // You can manually set the visitor details (resolution, time, plugins, etc.) 
  9. // See all other ->set* functions available in the PiwikTracker.php file
  10. $piwikTracker->setResolution(1600, 1400);
  12. // Sends Tracker request via http
  13. $piwikTracker->doTrackPageView('Document title of current page view');
  15. // You can also track Goal conversions
  16. $piwikTracker->doTrackGoal($idGoal = 1, $revenue = 42);
  17. ?>

Read more about the Matomo Tracking HTTP API or the PHP Client.

More information

See also these related FAQ entries