Support » Plugin: Matomo Analytics - Ethical Stats. Powerful Insights. » Tracking downloads served through ZotPress

Tracking downloads served through ZotPress

  • Resolved Mark

    (@codeispoetry)


    8 months, 3 weeks ago

    Blown away by this plugin. Very well-executed and amazing that it basically all works out of the box!

    Here’s one of the few things I couldn’t get to work (yet). I’m using ZotPress to generate publication lists with PDF download links, for which I would like to track downloads using Matomo. Thing is, downloads are not on the same server but retrieved via the Zotero API, which means for instance the links don’t end in .pdf and are not natively recognised as downloads. The links all look like this:

    <a title="Download" class="zp-DownloadURL" href="https://mydomain.net/wp-content/plugins/zotpress/lib/request/request.dl.php?api_user_id=1234567&dlkey=HDSBBZ9D&content_type=application/pdf">PDF</a>

    BTW, baseline checks: Matomo can and does detect downloads on this site: a direct link to a PDF on same server is detected as a download, and a click on an URL with piwik-download class or an additional zp-DownloadURL class is also detected as a download.

    My problem is with the dynamic links generated by ZotPress.

    I’ve tried a few things, to no avail:

    1. I added the CSS class zp-DownloadURL to setDownloadclasses so that Matomo will recognize clicks on these links as downloads.

    Result: Clicks in ZotPress-generated lists are not detected as a download. (Note that this class does work when I create my own URL manually; see baseline check above.)

    2. I added a Goal triggered when visiting an URL that contains zotpress/lib/request/request.dl.php (middle part of the ZotPress download link)

    Result: click doesn’t trigger goal.

    3. I added a Goal triggered when visiting an URL that matches the expression application\/pdf (final part of the ZotPress download link)

    Result: click doesn’t trigger goal.

    4. I added application\/pdf to the filetypes recognized as download

    Result: isn’t recognised as download (and yes I was getting desparate)

    Not being a JS person at all, I’m at a loss where to start debugging this. (I mention this because the FAQ for troubles with download tracking mentions “you might have to manually edit your Javascript code to return false in onclick events” — I wouldn’t know where to do this.) Help appreciated!

    • This topic was modified 8 months, 3 weeks ago by Mark.

    The page I need help with: [log in to see the link]

Viewing 12 replies - 1 through 12 (of 12 total)
  • Plugin Author Thomas

    (@tsteur)

    8 months, 3 weeks ago

    Hi @codeispoetry
    thanks for creating the issue. I have installed the same plugin and been looking through the code as well as been trying to find the issue for quite a while on the link you mentioned (you probably notice my visit in the visits log 🙂 ).

    It looks like this is due to https://github.com/matomo-org/matomo/issues/15780

    Basically, Matomo is working as expecting and adding the click listener to all links on the page including the PDF links etc. However, there seems to be something dynamic like you say and Zotpress seems to replace the link elements or so and as such Matomo is not tracking these links.

    If I call _paq.push(['enableLinkTracking']) after the page loaded again, the links are tracked. I couldn’t quite figure out how/where Zotpress is replacing these link elements and why they would do it. However, maybe a few things could help improve the situation until we have fixed above referenced issue.

    * I reckon you can disable content impressions (unless you actually changed your theme to support it)
    * You can likely remove all the addDownloadExtensions, setDownloadExtensions, setLinkClasses . They shouldn’t be needed and I assume you did it for debugging purposes and trying to make it work.

    Now you have two options:

    1. If you have a custom theme and you are a developer, then you could add something like this to your theme

    setTimeout(function () { window._paq = window._paq || [];window._paq.push(['enableLinkTracking']) }, 4000)

    2. Assuming you likely don’t have a custom theme and maybe aren’t a developer, you could:

    * Change the tracking mode in Matomo tracking settings from “Default tracking” to “Enter manually”.
    * Then copy above code with the set timeout and paste it add the end of the “tracking code” field.
    * Then save the changes.

    It might not work in all cases, but it should improve the situation. It will basically 4 seconds after it executes that code search for links to track. The zotpress link elements might be replaced by then, or not depending on how fast the page loads so it wouldn’t always work.

    I hope this doesn’t sound all too confusing and feel free to otherwise create a user with the Matomo Super User role for us (email: wordpress at matomo.org) and we help you getting it to work. Sorry about all the trouble! I will see if we can also solve this in the next release already partially.

    Blown away by this plugin. Very well-executed and amazing that it basically all works out of the box!

    That’s great to hear! Feel free to leave a review, it would really help us 🙂

    Let me know any questions and again sorry if it got a bit technical.

    Mark

    (@codeispoetry)

    8 months, 3 weeks ago

    Thanks for the comprehensive reply. This is looking good — adding the timeout (and removing some of my earlier attempts) to the tracking code does indeed result in better tracking. FYI, your own visit, before these modifications, registered as a few reloads of the page but only a single download.

    I’m still not getting 100% success but about 4 out of 6 tries are now detected as downloads. I wonder what else can be done to ensure better coverage; 4 seconds seems pretty long, I don’t think ZotPress is still busy then. And all of the external links that go to doi.org are now also correctly tracked (and trigger the goal I set for them). So the timeout does indeed work.

    (I will also look on the ZotPress side if this cannot be improved further. For instance, since publication lists don’t change that often and can be treated as static content, I’ll look into whether I can get a good caching plugin to work so that ZotPress doesn’t need to mess with the DOM after it is ready. If that works I can probably get rid of the timeout again. Does that reasoning seem basically correct?)

    Mark

    (@codeispoetry)

    8 months, 2 weeks ago

    Update: some questions remain.

    First, if I want to place this in a child theme, would this be the way to go? (I’m dubious because when I try this it doesn’t help tracking ZotPress links or downloads at all.) (1) Put the delay code from above in /js/matomo_delay.js, (2) add the script in functions.php through the wp_enqueue_scripts hook, like this:

    
function matomo_delay() {
wp_enqueue_script(
    'custom-script',
    get_stylesheet_directory_uri() . '/js/matomo_delay.js',
    array( 'jquery' ),
	1.0.0,
	TRUE
 );
}
add_action( 'wp_enqueue_scripts', 'matomo_delay' );

    (The TRUE refers to ‘in footer’ and makes the script appear in the footer, right after the Matomo tracking code.)

    Second, whether I use the above method or append it to the manual tracking code, download detection is still very erratic. I find it pretty hard to troubleshoot this and would be happy to let you have a look. I’ll create a user and send you an email at the indicated address.

    Plugin Author Thomas

    (@tsteur)

    8 months, 2 weeks ago

    @codeispoetry I’ve worked already on a patch yesterday that might help in https://github.com/matomo-org/matomo/pull/15915 but cannot guarantee.

    Maybe we could see if the patch will already fix it for you as it will be also included in the next release.

    Basically, what I would recommend you do is update this file:

    
wp-content/plugins/matomo/app/js/piwik.min.js

    with the content of this URL: https://raw.githubusercontent.com/matomo-org/matomo/3.x-dev/js/piwik.min.js

    It may take a few hours for Matomo to update the tracking code for all your blogs. Afterwards, things might work automatically.

    Alternatively, you could update the file uploads/matomo/matomo.js in each of your site’s upload directory directly to test it sooner. I suppose a path may look like eg wp-content/uploads/sites/1/matomo/matomo.js.

    Would that maybe easier? If you could update this file, feel free to let me know and I’ll have another look again in case it doesn’t work.

    Hoping my instructions are somewhat helpful / clear.

    Mark

    (@codeispoetry)

    8 months, 2 weeks ago

    Yes, all clear, I’ve updated the main js file and will give it a few hours to see what happens. Can do some testing again in a few hours (my afternoon).

    Mark

    (@codeispoetry)

    8 months, 2 weeks ago

    Neat — this seems to work! I’ve done away with the delay code and am using the updated piwik.min.js, and clicks on Zotpress URLs are now marked as downloads as long as zp-DownloadURL is added to the download classes.

    The only thing I’m still having trouble with is getting these clicks to trigger a goal. Download-related goals seem to expect a filename (in whole or part), and none of the URL-related goals (‘Visit a given URL’, ‘Click on link to external website’) register as triggered when clicking these kinds of links.

    Plugin Author Thomas

    (@tsteur)

    8 months, 2 weeks ago

    Great to hear this works!

    Regarding the download: What works for us is for example “Goal is triggered when visitors download a file where the filename matches the expression …” see https://paste.pics/c16959f93de17c46123b2c311f33dcac

    Eg we have “https://builds.matomo.org/.*\.zip” as pattern. You could have a pattern like “.*pdf.*” which might work.

    Mark

    (@codeispoetry)

    8 months, 2 weeks ago

    I decided to give it a day and see what works and what doesn’t, but this part still doesn’t work (and somehow tracking of downloads seems still to be erratic despite using the fixed piwik.min.js above).

    Regarding how to trigger goals, I’m thinking the reason the kind of pattern you exemplify doesn’t work is that ZotPress retrieves its files through a REST API and that the URLs don’t actually end in a file extension but look like this:

    ... /request.dl.php?api_user_id=2473932&dlkey=YV6WD77A&content_type=application/pdf

    I’ve tried in vain to construct various patterns and regexes to match this; it seems to me that the problem lies before that, in that Matomo simply doesn’t register this as a URL that points to a file.

    If Matomo were to recognize that kind of link as a file download, this solves another problem, namely that right now I need to set a downloadclass. Trouble is, while I can tell ZotPress to add that class, sometimes I want to link to those URLs manually (i.e. in non-ZotPress-generated content). Right now the only way to get those registered as downloads is to also add the download class manually. Whereas if Matomo would see those URLs as a file download, the download would be registered whether it has a class or not.

    Plugin Author Thomas

    (@tsteur)

    8 months, 2 weeks ago

    Hi @codeispoetry also just replied by email. It looks to me in your reports like it is detecting it as a download? Also mentioned in the email you’ll need to configure in the Goals report that “a download” should trigger the goal, not when a visitor “visit a given url” (which basically only applies to page view). Hope this helps?

    Mark

    (@codeispoetry)

    8 months, 2 weeks ago

    You are right these URLs are now able to trigger goals of the type “Download” with the regex you gave (.*pdf.*). Excellent! So am I right in inferring that these links are detected as “Download” because they have the right download CSS class, which makes them available to trigger a goal?

    Only remaining question with regard to Download tracking is: what about ZotPress-like links that have no class="zpDownloadURL" or similar? Those are still not recognised as downloads (in the sense of appearing under Behaviour > Downloads) in my testing. Could that be because they don’t come with an extension? And would there be a way to get them recognized as such, even without a CSS class, and apart from goals?

    (To avoid you doing double work and for the benefit of future readers I can update the thread if you answer by mail 🙂 .)

    • This reply was modified 8 months, 2 weeks ago by Mark.
    • This reply was modified 8 months, 2 weeks ago by Mark.
    Plugin Author Thomas

    (@tsteur)

    8 months, 2 weeks ago

    > Could that be because they don’t come with an extension?

    Yes that would be the case. By default we detect these extensions as downloads: https://github.com/matomo-org/matomo/blob/3.13.5/js/piwik.js#L3081

    You can change this list in the file types for download settings but if they don’t have a filetype this likely won’t work.

    We have three ways to detect a download:

    * The link element has a “download” attribute telling the browser it is a download
    * Using the file extensions
    * Using the css class

    If none of it is there, we cannot detect it unfortunately. Might be worth it asking zotpress to eg set the download attribute or maybe they can set a css class?

    Mark

    (@codeispoetry)

    8 months, 2 weeks ago

    Thanks, that clears it up! I’d rather have the ZotPress URLs looked a bit more like files indeed (including readable sensible filenames) so I’ll take that up with them. I had already modified the code to set a CSS class but I’m trying to avoid modding plugins because I don’t want to break updates. Hence my attempts to get to the bottom of it here. This is now resolved as far as I am concerned, and you’ve gone beyond your duties in supporting. If I could give six stars out of five I would update my review! Thanks again.

Viewing 12 replies - 1 through 12 (of 12 total)
  • The topic ‘Tracking downloads served through ZotPress’ is closed to new replies.

Topic Tags

Views