New Matomo Javascript Tracking API – How we designed it

There are a lot of changes in Matomo (Piwik) 0.4. Today, I’m going to write about the release of an exciting new version of piwik.js, Matomo’s JavaScript tracker. While the improvements are all under the hood, Matomo’s client-side code is now a heavyweight contender to the trackers from the “Big 3” (i.e., GA, Y!A, and MS).

Inspired by Remy Damour’s code contribution, planning and redevelopment of piwik.js began over 9 months ago. Over this period, we continued to maintain the legacy piwik.js while developing this new and improved version. We looked at the APIs of the “Big 3”. We heard your complaints. We read your suggestions. We tackled your support requests. And after many code reviews and test cycles, we believe it’s time to unleash the code.

On behalf of the Matomo community, I’d like to thank everyone who submitted bug reports, suggestions, and input that drove this rewrite.


The new piwik.js is:

  • Object-oriented.
    Multiple trackers on the same web page is now possible. And with the exception of legacy support, the code lives entirely in the Matomo namespace.
  • Backwards compatible.
    You don’t have to update the tracking code on your pages. Note: we have deprecated piwik_track(), piwik_log(), and global variables for configuration but backward compatibility will always remain.
  • XHTML-friendly.
    The code no longer modifies the DOM. Specifically, the calls to document.write() — to attach the transparent 1×1 web bug image or to detect plugins in Internet Explorer — are history.
  • Less restrictive.
    The code is more forgiving about where you insert the new tracking code in your pages. Also, custom data is now JSON stringified and no longer limited to a flat structure.
  • Industry-conforming.
    The code now tracks the click event instead of mousedown.
  • More customizable.
    Check out the API. For example, you can now define your own CSS classes for piwik_ignore, piwik_download, and piwik_link.
  • Heavily tested.
    We added automated unit tests via QUnit. The code also passes JSLint and (Microsoft’s) JavaScript Leak Detector.


You can find the updated documentation for the revamped JavaScript tracking API here:

As always, we would appreciate your feedback. Thank you for using, supporting, and promoting Matomo.

This post is from Anthon Pang (aka “vipsoft”), new rockstar developer in the Matomo team.

Share this post