Understanding the tracking of outlinks and downloads

Hi Piwik team
I understand (basically) how the piwik tag communicates with the piwik server to count page impressions, visitors etc. However, the docs and FAQs are a bit brief on how the tracking of outlinks and downloads works (it only says it happens “automatically”).

Now my site is mostly javascript, and I was able to convert the piwik tag into a js function that works really fine. The piwik docs somewhere say that outlink/download tracking only works with real HTML <a href=> links, not in js. I can confirm that now :-))

But how does it work? Behind the curtains I mean. I like to think that if I understand that, I can adjust it to my purposes as well.

Thanks for your patience with users like me :slight_smile:

We use a click event handler (like GA and Y!A) if you enable link tracking.

If you have your own click handler, keep in mind:

  • if link tracking is enabled, your click handler should not return a value (true/false) as there is a cross browser issue which could prevent other click handlers (such as Piwik’s) from executing
  • if link tracking is disabled, you can use the trackLink() method to track outlinks/downloads manually

See http://piwik.org/docs/javascript-tracking/

The uncompressed code for piwik.js can be found in the piwik/js/ folder.

Hi vipsoft
The remark about the event-handler working “behind the curtains” was helpful.

I am indeed using my own hyperlink-handler, i.e. in HTML it says for example

<a href="java script:Display(123)">Click here</a>

while in the depths of my JS, I am using either “window.open” or “window.location.href” depending on if I want a new page in my current window or a new window. “123” points to URL number 123 in a centrally administered list (for easy site maintenance).

So if I got your advice right, I will disable automatic link tracking in the Piwik tag, and instead place a

piwikTracker.trackLink(sourceUrl, linkType, customData);

into my link handling code. Is that correct?

I also understand that “sourceUrl” and “linkType” are just strings. Is that true? How does Piwik use or interpret them, i.e. where/how do they show up on the dashboard? I also understood the Piwik ignores “customData”.

Thanks for clarifying

linkType is a string, either “link” (for Actions | Outlinks) or “download” (for Actions | Downloads).

sourceUrl is a URL, e.g., http://piwik.org/latest.zip

customData (and presumably a custom linkType) is not used by Piwik core but may be used by a third party plugin.

Hi vipsoft
Your replies helped me understand, thanks for that. To give some feedback: In my own javascript link handler, I now call a function similar to this:

function trackclick(linkname, linktype)   // linktype must be "link" or "download"
    if (linkname!="") whattocount=linkname;

    if (linktype=="download") aswhat="download";

    /* anything that is not production is test */
    if (pathname().substr(0,20)==prodsiteURL)   // pathname() is a selfmade function
    { site_id = pwkIDSITE_prod;}
    { site_id = pwkIDSITE_test;}

    var piwikTracker = Piwik.getTracker(pwkBaseURL + "piwik.php", site_id);
    piwikTracker.trackLink(whattocount, aswhat, "");

Works as desired. I will add again the try…catch bracket around the piwik calls later (had removed it so the Firefox JS console tells me if something goes wrong here). The other function called from my webpages to count impressions and visits is of course very similar to this.

Thought I mention it for those few who write their own sites just for fun :slight_smile:


If you would like to write a little doc about it, it would be a good start for the user documentation style_emoticons/<#EMO_DIR#>/smile.gif it would be published in http://piwik.org/docs/

Hi Matthieu
"Thanks for the flowers" (german saying).
Yes will be glad to but let me finish some experiments first.