diff --git a/CHANGELOG.md b/CHANGELOG.md index a7bbf55c0..d6ce06a3d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. ## Unreleased ### Added +- A `tagged-events` script extension for out-of-the-box custom event tracking - The ability to escape `|` characters with `\` in Stats API filter values - An upper bound of 1000 to the `limit` parameter in Stats API - The `exclusions` script extension now also takes a `data-include` attribute tag diff --git a/lib/plausible_web/plugs/tracker.ex b/lib/plausible_web/plugs/tracker.ex index b11dc4f7a..cd10a955f 100644 --- a/lib/plausible_web/plugs/tracker.ex +++ b/lib/plausible_web/plugs/tracker.ex @@ -10,7 +10,8 @@ defmodule PlausibleWeb.Tracker do "local", "manual", "file-downloads", - "dimensions" + "dimensions", + "tagged-events" ] # Generates Power Set of all variants diff --git a/tracker/compile.js b/tracker/compile.js index 2da88662d..125cc835a 100644 --- a/tracker/compile.js +++ b/tracker/compile.js @@ -8,6 +8,8 @@ Handlebars.registerHelper('any', function (...args) { return args.slice(0, -1).some(Boolean) }) +Handlebars.registerPartial('customEvents', Handlebars.compile(fs.readFileSync(relPath('src/customEvents.js')).toString())) + function relPath(segment) { return path.join(__dirname, segment) } @@ -24,7 +26,7 @@ function compilefile(input, output, templateVars = {}) { } } -const base_variants = ["hash", "outbound-links", "exclusions", "compat", "local", "manual", "file-downloads", "dimensions"] +const base_variants = ["hash", "outbound-links", "exclusions", "compat", "local", "manual", "file-downloads", "dimensions", "tagged-events"] const variants = [...g.clone.powerSet(base_variants)].filter(a => a.length > 0).map(a => a.sort()); compilefile(relPath('src/plausible.js'), relPath('../priv/tracker/js/plausible.js')) diff --git a/tracker/src/customEvents.js b/tracker/src/customEvents.js new file mode 100644 index 000000000..7d3c563aa --- /dev/null +++ b/tracker/src/customEvents.js @@ -0,0 +1,198 @@ +function getLinkEl(link) { + while (link && (typeof link.tagName === 'undefined' || !isLink(link) || !link.href)) { + link = link.parentNode + } + return link +} + +function isLink(element) { + return element && element.tagName && element.tagName.toLowerCase() === 'a' +} + +function shouldFollowLink(event, link) { + // If default has been prevented by an external script, Plausible should not intercept navigation. + if (event.defaultPrevented) { return false } + + var targetsCurrentWindow = !link.target || link.target.match(/^_(self|parent|top)$/i) + var isRegularClick = !(event.ctrlKey || event.metaKey || event.shiftKey) && event.type === 'click' + return targetsCurrentWindow && isRegularClick +} + +var MIDDLE_MOUSE_BUTTON = 1 + +function handleLinkClickEvent(event) { + if (event.type === 'auxclick' && event.button !== MIDDLE_MOUSE_BUTTON) { return } + + var link = getLinkEl(event.target) + var hrefWithoutQuery = link && link.href && link.href.split('?')[0] + + {{#if tagged_events}} + if (isElementOrParentTagged(link, 0)) { + // Return to prevent sending multiple events with the same action. + // Clicks on tagged links are handled by another function. + return + } + {{/if}} + + {{#if outbound_links}} + if (isOutboundLink(link)) { + return sendLinkClickEvent(event, link, { name: 'Outbound Link: Click', props: { url: link.href } }) + } + {{/if}} + + {{#if file_downloads}} + if (isDownloadToTrack(hrefWithoutQuery)) { + return sendLinkClickEvent(event, link, { name: 'File Download', props: { url: hrefWithoutQuery } }) + } + {{/if}} +} + +function sendLinkClickEvent(event, link, eventAttrs) { + var followedLink = false + + function followLink() { + if (!followedLink) { + followedLink = true + window.location = link.href + } + } + + if (shouldFollowLink(event, link)) { + plausible(eventAttrs.name, { props: eventAttrs.props, callback: followLink }) + setTimeout(followLink, 5000) + event.preventDefault() + } else { + plausible(eventAttrs.name, { props: eventAttrs.props }) + } +} + +document.addEventListener('click', handleLinkClickEvent) +document.addEventListener('auxclick', handleLinkClickEvent) + +{{#if outbound_links}} +function isOutboundLink(link) { + return link && link.href && link.host && link.host !== location.host +} +{{/if}} + +{{#if file_downloads}} +var defaultFileTypes = ['pdf', 'xlsx', 'docx', 'txt', 'rtf', 'csv', 'exe', 'key', 'pps', 'ppt', 'pptx', '7z', 'pkg', 'rar', 'gz', 'zip', 'avi', 'mov', 'mp4', 'mpeg', 'wmv', 'midi', 'mp3', 'wav', 'wma'] +var fileTypesAttr = scriptEl.getAttribute('file-types') +var addFileTypesAttr = scriptEl.getAttribute('add-file-types') +var fileTypesToTrack = (fileTypesAttr && fileTypesAttr.split(",")) || (addFileTypesAttr && addFileTypesAttr.split(",").concat(defaultFileTypes)) || defaultFileTypes; + +function isDownloadToTrack(url) { + if (!url) { return false } + + var fileType = url.split('.').pop(); + return fileTypesToTrack.some(function (fileTypeToTrack) { + return fileTypeToTrack === fileType + }) +} +{{/if}} + +{{#if tagged_events}} +// Finds event attributes by iterating over the given element's (or its +// parent's) classList. Returns an object with `name` and `props` keys. +function getTaggedEventAttributes(htmlElement) { + var taggedElement = isTagged(htmlElement) ? htmlElement : htmlElement && htmlElement.parentNode + var eventAttrs = { name: null, props: {} } + + var classList = taggedElement && taggedElement.classList + if (!classList) { return eventAttrs } + + for (var i = 0; i < classList.length; i++) { + var className = classList.item(i) + + var matchList = className.match(/plausible-event-(.+)=(.+)/) + if (!matchList) { continue } + + var key = matchList[1] + var value = matchList[2].replace(/\+/g, ' ') + + if (key.toLowerCase() === 'name') { + eventAttrs.name = value + } else { + eventAttrs.props[key] = value + } + } + + return eventAttrs +} + +function handleTaggedFormSubmitEvent(event) { + var form = event.target + var eventAttrs = getTaggedEventAttributes(form) + if (!eventAttrs.name) { return } + + event.preventDefault() + var formSubmitted = false + + function submitForm() { + if (!formSubmitted) { + formSubmitted = true + form.submit() + } + } + + setTimeout(submitForm, 5000) + plausible(eventAttrs.name, { props: eventAttrs.props, callback: submitForm }) +} + +function isForm(element) { + return element && element.tagName && element.tagName.toLowerCase() === 'form' +} + +var PARENTS_TO_SEARCH_LIMIT = 3 + +function handleTaggedElementClickEvent(event) { + if (event.type === 'auxclick' && event.button !== MIDDLE_MOUSE_BUTTON) { return } + + var clicked = event.target + + var clickedLink + var taggedElement + // Iterate over parents to find the tagged element. Also search for + // a link element to call for different tracking behavior if found. + for (var i = 0; i <= PARENTS_TO_SEARCH_LIMIT; i++) { + if (!clicked) { break } + + // Clicks inside forms are not tracked. Only form submits are. + if (isForm(clicked)) { return } + if (isLink(clicked)) { clickedLink = clicked } + if (isTagged(clicked)) { taggedElement = clicked } + clicked = clicked.parentNode + } + + if (taggedElement) { + var eventAttrs = getTaggedEventAttributes(taggedElement) + + if (clickedLink) { + eventAttrs.props.url = clickedLink.href + sendLinkClickEvent(event, clickedLink, eventAttrs) + } else { + plausible(eventAttrs.name, { props: eventAttrs.props }) + } + } +} + +function isTagged(element) { + var classList = element && element.classList + if (classList) { + for (var i = 0; i < classList.length; i++) { + if (classList.item(i).match(/plausible-event-name=(.+)/)) { return true } + } + } + return false +} + +function isElementOrParentTagged(element, parentsChecked) { + if (!element || parentsChecked > PARENTS_TO_SEARCH_LIMIT) { return false } + if (isTagged(element)) { return true } + return isElementOrParentTagged(element.parentNode, parentsChecked + 1) +} + +document.addEventListener('submit', handleTaggedFormSubmitEvent) +document.addEventListener('click', handleTaggedElementClickEvent) +document.addEventListener('auxclick', handleTaggedElementClickEvent) +{{/if}} diff --git a/tracker/src/plausible.js b/tracker/src/plausible.js index 10f14b2fd..6aa6d2e62 100644 --- a/tracker/src/plausible.js +++ b/tracker/src/plausible.js @@ -155,91 +155,7 @@ } {{/unless}} - // CUSTOM EVENT TRACKING - {{#if (any outbound_links file_downloads)}} - function getLinkEl(link) { - while (link && (typeof link.tagName === 'undefined' || link.tagName.toLowerCase() !== 'a' || !link.href)) { - link = link.parentNode - } - return link - } - - function shouldFollowLink(event, link) { - // If default has been prevented by an external script, Plausible should not intercept navigation. - if (event.defaultPrevented) { return false } - - var targetsCurrentWindow = !link.target || link.target.match(/^_(self|parent|top)$/i) - var isRegularClick = !(event.ctrlKey || event.metaKey || event.shiftKey) && event.type === 'click' - return targetsCurrentWindow && isRegularClick - } - - var MIDDLE_MOUSE_BUTTON = 1 - - function handleLinkClickEvent(event) { - if (event.type === 'auxclick' && event.button !== MIDDLE_MOUSE_BUTTON) { return } - - var link = getLinkEl(event.target) - var hrefWithoutQuery = link && link.href && link.href.split('?')[0] - - {{#if outbound_links}} - if (isOutboundLink(link)) { - var eventName = 'Outbound Link: Click' - var eventProps = {url: link.href} - return sendLinkClickEvent(event, link, eventName, eventProps) - } - {{/if}} - - {{#if file_downloads}} - if (isDownloadToTrack(hrefWithoutQuery)) { - var eventName = 'File Download' - var eventProps = {url: hrefWithoutQuery} - return sendLinkClickEvent(event, link, eventName, eventProps) - } - {{/if}} - } - - function sendLinkClickEvent(event, link, eventName, eventProps) { - var followedLink = false - - function followLink() { - if (!followedLink) { - followedLink = true - window.location = link.href - } - } - - if (shouldFollowLink(event, link)) { - plausible(eventName, { props: eventProps, callback: followLink }) - setTimeout(followLink, 5000) - event.preventDefault() - } else { - plausible(eventName, { props: eventProps }) - } - } - - document.addEventListener('click', handleLinkClickEvent) - document.addEventListener('auxclick', handleLinkClickEvent) - {{/if}} - - {{#if outbound_links}} - function isOutboundLink(link) { - return link && link.href && link.host && link.host !== location.host - } - {{/if}} - - {{#if file_downloads}} - var defaultFileTypes = ['pdf', 'xlsx', 'docx', 'txt', 'rtf', 'csv', 'exe', 'key', 'pps', 'ppt', 'pptx', '7z', 'pkg', 'rar', 'gz', 'zip', 'avi', 'mov', 'mp4', 'mpeg', 'wmv', 'midi', 'mp3', 'wav', 'wma'] - var fileTypesAttr = scriptEl.getAttribute('file-types') - var addFileTypesAttr = scriptEl.getAttribute('add-file-types') - var fileTypesToTrack = (fileTypesAttr && fileTypesAttr.split(",")) || (addFileTypesAttr && addFileTypesAttr.split(",").concat(defaultFileTypes)) || defaultFileTypes; - - function isDownloadToTrack(url) { - if (!url) { return false } - - var fileType = url.split('.').pop(); - return fileTypesToTrack.some(function(fileTypeToTrack) { - return fileTypeToTrack === fileType - }) - } + {{#if (any outbound_links file_downloads tagged_events)}} + {{> customEvents}} {{/if}} })(); diff --git a/tracker/test/custom-event-edge-cases.spec.js b/tracker/test/custom-event-edge-cases.spec.js index b9762fd54..d946fbca5 100644 --- a/tracker/test/custom-event-edge-cases.spec.js +++ b/tracker/test/custom-event-edge-cases.spec.js @@ -4,7 +4,7 @@ const { expect } = require('@playwright/test'); const { LOCAL_SERVER_ADDR } = require('./support/server'); -test.describe('script.file-downloads.outbound-links.js', () => { +test.describe('script.file-downloads.outbound-links.tagged-events.js', () => { test('sends only outbound link event when clicked link is both download and outbound', async ({ page }) => { await page.goto('/custom-event-edge-case.html') const downloadURL = await page.locator('#outbound-download-link').getAttribute('href') @@ -26,4 +26,15 @@ test.describe('script.file-downloads.outbound-links.js', () => { expectCustomEvent(await plausibleRequestMock, 'File Download', {url: downloadURL}) }); + + test('sends only tagged event when clicked link is tagged + outbound + download', async ({ page }) => { + await page.goto('/custom-event-edge-case.html') + + const plausibleRequestMockList = mockManyRequests(page, '/api/event', 3) + await page.click('#tagged-outbound-download-link') + + const requests = await plausibleRequestMockList + expect(requests.length).toBe(1) + expectCustomEvent(requests[0], 'Foo', {}) + }); }); diff --git a/tracker/test/fixtures/custom-event-edge-case.html b/tracker/test/fixtures/custom-event-edge-case.html index f5019dae7..0461ce87c 100644 --- a/tracker/test/fixtures/custom-event-edge-case.html +++ b/tracker/test/fixtures/custom-event-edge-case.html @@ -7,13 +7,15 @@