Add tagged-events script extension (#2333)
Adds a new script extension that allows tracking interactions with specific HTML elements on a website. For example - to track link clicks on one specific `<a>` element, you can tag it like this: ```html <a href=... class="plausible-event-name=<your_event_name>"> ``` And you can also tag the link with custom property names and values: ```html <a href=... class="plausible-event-name=<your_event_name> plausible-event-<your_custom_prop>=<your_value>"> ``` Tagging a link as above will send a custom event with the given name and props, if a `click` or `auxclick` browser event happens, and targets the link element. The tracking behavior is somewhat different based on the HTML element type: - `<a>` - triggers on `click` and `auxclick` events - intercepts navigation based on the same rules as `outbound-links` and `file-downloads` - `<form>` - triggers on `submit` event - always intercepts navigation (calls `form.submit()` after preventing default and sending the Plausible event) - other (`<img>`, `<button>`, `<span>`, `<div>`, `<h2>`, etc ...) - triggers on `click` and `auxclick` events - does not prevent default to intercept possible navigation. Simply calls Plausible with the event name and props read from the element class list.pull/2463/head r2022.11.21-19
parent
3bedf9281c
commit
135471c32e
@ -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}}
|
||||
@ -0,0 +1,80 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta http-equiv="X-UA-Compatible" content="ie=edge">
|
||||
<title>Plausible Playwright tests</title>
|
||||
|
||||
<script defer src="/tracker/js/plausible.local.manual.tagged-events.js"></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<a id="link"
|
||||
class="plausible-event-name=Payment+Complete should ignore-this plausible-event-amount=100 plausible-event-method=Credit+Card"
|
||||
href="https://awesome.website.com/payment/">tagged link</a>
|
||||
|
||||
<form class="plausible-event-name=Signup plausible-event-type=Newsletter"
|
||||
action="https://awesome.website.com/register" method="post">
|
||||
<input type="text" id='form-text-input' />
|
||||
<input id="form-submit" type="submit" value="Submit" />
|
||||
</form>
|
||||
|
||||
<button id="button" class="plausible-event-name=Custom+Event plausible-event-foo=bar">
|
||||
Button
|
||||
</button>
|
||||
|
||||
<span id="span" class="plausible-event-name=Custom+Event plausible-event-foo=bar">
|
||||
Span
|
||||
</span>
|
||||
|
||||
<div id="div" class="plausible-event-name=Custom+Event plausible-event-foo=bar">
|
||||
<a id="link-with-div-parent" href="https://awesome.website.com/payment/">Div child</a>
|
||||
</div>
|
||||
|
||||
<a class="plausible-event-name=Custom+Event plausible-event-foo=bar" href="https://awesome.website.com/payment/">
|
||||
<h2 id="h2-with-link-parent">Link child</h2>
|
||||
</a>
|
||||
|
||||
<div class="plausible-event-name=Form+Submit">
|
||||
<form action="https://awesome.website.com/register" method="post">
|
||||
<input type="text" value="Form" />
|
||||
<input id="submit-form-with-tagged-parent" type="submit" value="Submit" />
|
||||
</form>
|
||||
</div>
|
||||
|
||||
<a id="not-tracked-link" class="plausible-event-amount=100 plausible-event-method=Credit+Card"
|
||||
href="https://awesome.website.com/payment/">
|
||||
Link (without plausible-event-name class)
|
||||
</a>
|
||||
|
||||
<button id="not-tracked-button" class="im not tracked">
|
||||
Button (without plausible-event-name class)
|
||||
</button>
|
||||
|
||||
<span id="not-tracked-span" class="plausible-event-name= still not tracked">
|
||||
Span (without plausible-event-name class)
|
||||
</span>
|
||||
|
||||
|
||||
<script>
|
||||
// Dynamically add a tagged element to DOM after one second
|
||||
setTimeout(function () {
|
||||
let taggedElement = document.createElement('button')
|
||||
taggedElement.id = 'dynamic-tagged-button'
|
||||
taggedElement.classList.add('plausible-event-name=Custom+Event')
|
||||
taggedElement.innerHTML += 'Dynamic tagged button'
|
||||
document.body.appendChild(taggedElement)
|
||||
}, 1000)
|
||||
</script>
|
||||
|
||||
<form id="form" class="plausible-event-name=Signup plausible-event-type=Newsletter"
|
||||
action="https://awesome.website.com/register" method="post">
|
||||
<input type="text" id='form-input' />
|
||||
<div id="form-div">div in a form</div>
|
||||
<input type="submit" value="Submit" />
|
||||
</form>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@ -0,0 +1,109 @@
|
||||
const { test } = require('./support/harness')
|
||||
const { mockRequest, mockManyRequests, isMac, expectCustomEvent } = require('./support/test-utils')
|
||||
const { expect } = require('@playwright/test')
|
||||
|
||||
test.describe('tagged-events extension', () => {
|
||||
test('tracks a tagged link click with custom props + url prop', async ({ page }) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
|
||||
const linkURL = await page.locator('#link').getAttribute('href')
|
||||
|
||||
const plausibleRequestMock = mockRequest(page, '/api/event')
|
||||
await page.click('#link')
|
||||
expectCustomEvent(await plausibleRequestMock, 'Payment Complete', { amount: '100', method: "Credit Card", url: linkURL })
|
||||
});
|
||||
|
||||
test('tracks a tagged form submit with custom props when submitting by pressing enter', async ({ page }) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
const plausibleRequestMock = mockRequest(page, '/api/event')
|
||||
|
||||
const inputLocator = page.locator('#form-text-input')
|
||||
await inputLocator.type('some input')
|
||||
await inputLocator.press('Enter')
|
||||
|
||||
expectCustomEvent(await plausibleRequestMock, 'Signup', { type: "Newsletter" })
|
||||
});
|
||||
|
||||
test('tracks submit on a form with a tagged parent when submit button is clicked', async ({ page }) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
|
||||
const plausibleRequestMockList = mockManyRequests(page, '/api/event', 2)
|
||||
|
||||
await page.click('#submit-form-with-tagged-parent')
|
||||
|
||||
const requests = await plausibleRequestMockList
|
||||
|
||||
expect(requests.length).toBe(1)
|
||||
expectCustomEvent(requests[0], "Form Submit", {})
|
||||
});
|
||||
|
||||
test('tracks click and auxclick on any tagged HTML element', async ({ page }, workerInfo) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
|
||||
const plausibleRequestMockList = mockManyRequests(page, '/api/event', 3)
|
||||
|
||||
await page.click('#button')
|
||||
await page.click('#span')
|
||||
await page.click('#div', { modifiers: [isMac(workerInfo) ? 'Meta' : 'Control'] })
|
||||
|
||||
const requests = await plausibleRequestMockList
|
||||
expect(requests.length).toBe(3)
|
||||
requests.forEach(request => expectCustomEvent(request, 'Custom Event', { foo: "bar" }))
|
||||
});
|
||||
|
||||
test('does not track elements without plausible-event-name class + link elements navigate', async ({ page }) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
const linkLocator = page.locator('#not-tracked-link')
|
||||
|
||||
const linkURL = await linkLocator.getAttribute('href')
|
||||
|
||||
const plausibleRequestMock = mockRequest(page, '/api/event')
|
||||
const navigationRequestMock = mockRequest(page, linkURL)
|
||||
|
||||
await page.click('#not-tracked-button')
|
||||
await page.click('#not-tracked-span')
|
||||
await linkLocator.click()
|
||||
|
||||
expect(await plausibleRequestMock, "should not have made Plausible request").toBeNull()
|
||||
expect((await navigationRequestMock).url()).toContain(linkURL)
|
||||
});
|
||||
|
||||
test('tracks tagged HTML elements when their child element is clicked', async ({ page }, workerInfo) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
|
||||
const plausibleRequestMockList = mockManyRequests(page, '/api/event', 2)
|
||||
|
||||
await page.click('#h2-with-link-parent', { modifiers: [isMac(workerInfo) ? 'Meta' : 'Control'] })
|
||||
await page.click('#link-with-div-parent')
|
||||
|
||||
const requests = await plausibleRequestMockList
|
||||
expect(requests.length).toBe(2)
|
||||
requests.forEach(request => expectCustomEvent(request, 'Custom Event', { foo: "bar" }))
|
||||
});
|
||||
|
||||
test('tracks tagged element that is dynamically added to the DOM', async ({ page }) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
|
||||
const plausibleRequestMock = mockRequest(page, '/api/event')
|
||||
|
||||
const buttonLocator = page.locator('#dynamic-tagged-button')
|
||||
await buttonLocator.waitFor({state: 'visible'})
|
||||
await page.waitForTimeout(500)
|
||||
|
||||
await buttonLocator.click()
|
||||
|
||||
expectCustomEvent(await plausibleRequestMock, 'Custom Event', {})
|
||||
});
|
||||
|
||||
test('does not track clicks inside a tagged form, except submit click', async ({ page }) => {
|
||||
await page.goto('/tagged-event.html')
|
||||
|
||||
const plausibleRequestMock = mockRequest(page, '/api/event')
|
||||
|
||||
await page.click('#form')
|
||||
await page.click('#form-input')
|
||||
await page.click('#form-div')
|
||||
|
||||
expect(await plausibleRequestMock, "should not have made Plausible request").toBeNull()
|
||||
});
|
||||
});
|
||||
Loading…
Reference in New Issue