Skip to content

Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.

Tracker script version reported to /api/event (#5198)

Karl-Aksel Puulmann539f4a3f98b3
diff --git a/.github/workflows/tracker-version-bump.yml b/.github/workflows/tracker-version-bump.yml
new file mode 100644
index 0000000000..35d6bbf4e1
--- /dev/null
+++ b/.github/workflows/tracker-version-bump.yml
@@ -0,0 +1,75 @@
+name: "Tracker: Increment Reported Version"
+
+on:
+ pull_request:
+ paths:
+ - 'tracker/src/**'
+ - 'tracker/package.json'
+ - 'tracker/package-lock.json'
+
+jobs:
+ tracker-increment-reported-version:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v4
+ with:
+ repository: ${{ github.event.pull_request.head.repo.full_name }}
+ ref: ${{ github.event.pull_request.head.ref }}
+ token: ${{ secrets.PLAUSIBLE_BOT_GITHUB_TOKEN }}
+ fetch-depth: 0
+
+ - name: Checkout master for comparison
+ uses: actions/checkout@v4
+ with:
+ ref: master
+ path: master-branch
+
+ - name: Install jq
+ run: sudo apt-get install jq -y
+
+ - name: Compare and increment tracker_script_version
+ id: increment
+ run: |
+ cd tracker
+ # Get current version from PR branch
+ PR_VERSION=$(jq '.tracker_script_version' package.json)
+
+ # Get version from master, default to 0 if not present
+ MASTER_VERSION=$(jq '.tracker_script_version // 0' ../master-branch/tracker/package.json)
+
+ echo "PR tracker_script_version: $PR_VERSION"
+ echo "Master tracker_script_version: $MASTER_VERSION"
+
+ # Calculate new version
+ NEW_VERSION=$((PR_VERSION + 1))
+
+ # Check version conditions
+ if [ $PR_VERSION -lt $MASTER_VERSION ]; then
+ echo "::error::PR tracker tracker_script_version ($PR_VERSION) is less than master ($MASTER_VERSION) and cannot be incremented."
+ echo "::error::Rebase or merge master into your PR to fix this."
+ exit 1
+ elif [ $NEW_VERSION -eq $((MASTER_VERSION + 1)) ]; then
+ echo "Incrementing version from $PR_VERSION to $NEW_VERSION"
+ jq ".tracker_script_version = $NEW_VERSION" package.json > package.json.tmp
+ mv package.json.tmp package.json
+ echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+ echo "changed=true" >> $GITHUB_OUTPUT
+ else
+ echo "Already incremented tracker_script_version in PR, skipping."
+ echo "version=$PR_VERSION" >> $GITHUB_OUTPUT
+ echo "changed=false" >> $GITHUB_OUTPUT
+ fi
+
+ - name: Commit and push changes
+ uses: EndBug/add-and-commit@v9
+ if: steps.increment.outputs.changed == 'true'
+ with:
+ message: 'chore: Bump tracker_script_version to ${{ steps.increment.outputs.version }}'
+ github_token: ${{ secrets.PLAUSIBLE_BOT_GITHUB_TOKEN }}
+ add: |
+ - tracker/package.json
+ # Uncomment this once they're whitelisted by CLA agent
+ # default_author: github_actions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e2dd777050..b468702056 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ All notable changes to this project will be documented in this file.
- Support `["is", "segment", [<segment ID>]]` filter in Stats API
- Time on page metric is now sortable in reports
- Plausible tracker script now reports maximum scroll depth reached and time engaged with the site in an `engagement` event. These are reported as `sd` and `e` integer parameters to /api/event endpoint respectively. If you're using a custom proxy for plausible script, please ensure that these parameters are being passed forward.
+- Plausible tracker script now reports the version of the script in the `v` parameter sent with each request.
### Removed
diff --git a/tracker/compile.js b/tracker/compile.js
index b707b3a976..8d1548dc92 100644
--- a/tracker/compile.js
+++ b/tracker/compile.js
@@ -4,6 +4,7 @@ const path = require('path')
const Handlebars = require("handlebars");
const g = require("generatorics");
const { canSkipCompile } = require("./dev-compile/can-skip-compile");
+const { tracker_script_version } = require("./package.json");
if (process.env.NODE_ENV === 'dev' && canSkipCompile()) {
console.info('COMPILATION SKIPPED: No changes detected in tracker dependencies')
@@ -23,7 +24,7 @@ function relPath(segment) {
function compilefile(input, output, templateVars = {}) {
const code = fs.readFileSync(input).toString()
const template = Handlebars.compile(code)
- const rendered = template(templateVars)
+ const rendered = template({ ...templateVars, TRACKER_SCRIPT_VERSION: tracker_script_version })
const result = uglify.minify(rendered)
if (result.code) {
fs.writeFileSync(output, result.code)
@@ -41,4 +42,4 @@ compilefile(relPath('src/p.js'), relPath('../priv/tracker/js/p.js'))
variants.map(variant => {
const options = variant.map(variant => variant.replace('-', '_')).reduce((acc, curr) => (acc[curr] = true, acc), {})
compilefile(relPath('src/plausible.js'), relPath(`../priv/tracker/js/plausible.${variant.join('.')}.js`), options)
-})
\ No newline at end of file
+})
diff --git a/tracker/package.json b/tracker/package.json
index 31e5b48d06..38de725a5e 100644
--- a/tracker/package.json
+++ b/tracker/package.json
@@ -1,4 +1,5 @@
{
+ "tracker_script_version": 1,
"scripts": {
"deploy": "node compile.js",
"test": "npm run deploy && npx playwright test",
diff --git a/tracker/src/plausible.js b/tracker/src/plausible.js
index c01713c9eb..c1882fe7a6 100644
--- a/tracker/src/plausible.js
+++ b/tracker/src/plausible.js
@@ -42,16 +42,10 @@
// prevents registering multiple listeners in those cases.
var listeningOnEngagement = false
- // In SPA-s, multiple listeners that trigger the engagement event
- // might fire nearly at the same time. E.g. when navigating back
- // in browser history while using hash-based routing - a popstate
- // and hashchange will be fired in a very quick succession. This
- // flag prevents sending multiple engagement events in those cases.
- var engagementCooldown = false
-
// Timestamp indicating when this particular page last became visible.
// Reset during pageviews, set to null when page is closed.
var runningEngagementStart = null
+
// When page is hidden, this 'engaged' time is saved to this variable
var currentEngagementTime = 0
@@ -121,13 +115,10 @@
The first engagement event is always sent due to containing at least the initial scroll depth.
- We don't send engagements if:
- - Less than 300ms have passed since the last engagement event
- - The current pageview is ignored (onIgnoredEvent)
+ Also, we don't send engagements if the current pageview is ignored (onIgnoredEvent)
*/
- if (!engagementCooldown && !currentEngagementIgnored && (currentEngagementMaxScrollDepth < maxScrollDepthPx || engagementTime >= 3000)) {
+ if (!currentEngagementIgnored && (currentEngagementMaxScrollDepth < maxScrollDepthPx || engagementTime >= 3000)) {
currentEngagementMaxScrollDepth = maxScrollDepthPx
- setTimeout(function () {engagementCooldown = false}, 300)
var payload = {
n: 'engagement',
@@ -135,7 +126,8 @@
d: dataDomain,
u: currentEngagementURL,
p: currentEngagementProps,
- e: engagementTime
+ e: engagementTime,
+ v: {{TRACKER_SCRIPT_VERSION}}
}
// Reset current engagement time metrics. They will restart upon when page becomes visible or the next SPA pageview
@@ -150,20 +142,24 @@
}
}
+ function onVisibilityChange() {
+ if (document.visibilityState === 'visible' && document.hasFocus() && runningEngagementStart === null) {
+ runningEngagementStart = Date.now()
+ } else if (document.visibilityState === 'hidden' || !document.hasFocus()) {
+ // Tab went back to background or lost focus. Save the engaged time so far
+ currentEngagementTime = getEngagementTime()
+ runningEngagementStart = null
+
+ triggerEngagement()
+ }
+ }
+
function registerEngagementListener() {
if (!listeningOnEngagement) {
// Only register visibilitychange listener only after initial page load and pageview
- document.addEventListener('visibilitychange', function() {
- if (document.visibilityState === 'hidden') {
- // Tab went back to background. Save the engaged time so far
- currentEngagementTime = getEngagementTime()
- runningEngagementStart = null
-
- triggerEngagement()
- } else if (document.visibilityState === 'visible' && runningEngagementStart === null) {
- runningEngagementStart = Date.now()
- }
- })
+ document.addEventListener('visibilitychange', onVisibilityChange)
+ window.addEventListener('blur', onVisibilityChange)
+ window.addEventListener('focus', onVisibilityChange)
listeningOnEngagement = true
}
}
@@ -210,6 +206,7 @@
var payload = {}
payload.n = eventName
+ payload.v = {{TRACKER_SCRIPT_VERSION}}
{{#if manual}}
var customURL = options && options.u
diff --git a/tracker/test/engagement.spec.js b/tracker/test/engagement.spec.js
index a6386c901a..82db3f530b 100644
--- a/tracker/test/engagement.spec.js
+++ b/tracker/test/engagement.spec.js
@@ -1,7 +1,8 @@
const { expect } = require("@playwright/test")
-const { expectPlausibleInAction, engagementCooldown, hideAndShowCurrentTab } = require('./support/test-utils')
+const { expectPlausibleInAction, hideAndShowCurrentTab, focus, blur, blurAndFocusPage } = require('./support/test-utils')
const { test } = require('@playwright/test')
const { LOCAL_SERVER_ADDR } = require('./support/server')
+const { tracker_script_version } = require('../package.json')
test.describe('engagement events', () => {
test('sends an engagement event with time measurement when navigating to the next page', async ({ page }) => {
@@ -14,7 +15,7 @@ test.describe('engagement events', () => {
const [request] = await expectPlausibleInAction(page, {
action: () => page.click('#navigate-away'),
- expectedRequests: [{n: 'engagement', u: `${LOCAL_SERVER_ADDR}/engagement.html`}]
+ expectedRequests: [{n: 'engagement', u: `${LOCAL_SERVER_ADDR}/engagement.html`, v: tracker_script_version}]
})
expect(request.e).toBeGreaterThan(1000)
@@ -99,8 +100,6 @@ test.describe('engagement events', () => {
expectedRequests: [{n: 'engagement', u: pageBaseURL, h: 1}]
})
- await engagementCooldown(page)
-
// Navigate from ignored page to a tracked page ->
// no engagement from the current page, pageview on the next page
await expectPlausibleInAction(page, {
@@ -109,8 +108,6 @@ test.describe('engagement events', () => {
refutedRequests: [{n: 'engagement'}]
})
- await engagementCooldown(page)
-
// Navigate from a tracked page to another tracked page ->
// engagement with the last page URL, pageview with the new URL
await expectPlausibleInAction(page, {
@@ -162,8 +159,6 @@ test.describe('engagement events', () => {
]
})
- await engagementCooldown(page)
-
await expectPlausibleInAction(page, {
action: () => page.click('#jane-post'),
expectedRequests: [
@@ -172,8 +167,6 @@ test.describe('engagement events', () => {
]
})
- await engagementCooldown(page)
-
await expectPlausibleInAction(page, {
action: () => page.click('#home'),
expectedRequests: [
@@ -310,4 +303,36 @@ test.describe('engagement events', () => {
expect(request4.e).toBeGreaterThan(3000)
expect(request4.e).toBeLessThan(3500)
})
+
+ test('tracks engagement time whilst tab gains and loses focus', async ({ page }) => {
+ await expectPlausibleInAction(page, {
+ action: () => page.goto('/engagement.html'),
+ expectedRequests: [{n: 'pageview'}],
+ })
+
+ const [request1] = await expectPlausibleInAction(page, {
+ action: () => blur(page),
+ expectedRequests: [{n: 'engagement', u: `${LOCAL_SERVER_ADDR}/engagement.html`}],
+ })
+ expect(request1.e).toBeLessThan(500)
+
+ await focus(page)
+ await page.waitForTimeout(1000)
+
+ await expectPlausibleInAction(page, {
+ action: () => blurAndFocusPage(page, { delay: 3000 }),
+ refutedRequests: [{n: 'engagement'}],
+ mockRequestTimeout: 100
+ })
+
+ await page.waitForTimeout(2500)
+
+ const [request2] = await expectPlausibleInAction(page, {
+ action: () => blur(page),
+ expectedRequests: [{n: 'engagement', u: `${LOCAL_SERVER_ADDR}/engagement.html`}],
+ })
+
+ expect(request2.e).toBeGreaterThan(3500)
+ expect(request2.e).toBeLessThan(4000)
+ })
})
diff --git a/tracker/test/pageview.spec.js b/tracker/test/pageview.spec.js
index 76225c4f14..fe88455768 100644
--- a/tracker/test/pageview.spec.js
+++ b/tracker/test/pageview.spec.js
@@ -1,5 +1,6 @@
const { mockRequest } = require('./support/test-utils')
const { expect, test } = require('@playwright/test')
+const { tracker_script_version } = require('../package.json')
test.describe('Basic installation', () => {
test('Sends pageview automatically', async ({ page }) => {
@@ -9,5 +10,6 @@ test.describe('Basic installation', () => {
const plausibleRequest = await plausibleRequestMock
expect(plausibleRequest.url()).toContain('/api/event')
expect(plausibleRequest.postDataJSON().n).toEqual('pageview')
+ expect(plausibleRequest.postDataJSON().v).toEqual(tracker_script_version)
})
})
diff --git a/tracker/test/scroll-depth.spec.js b/tracker/test/scroll-depth.spec.js
index 3d94fabbba..d33019c795 100644
--- a/tracker/test/scroll-depth.spec.js
+++ b/tracker/test/scroll-depth.spec.js
@@ -1,4 +1,4 @@
-const { engagementCooldown, expectPlausibleInAction, hideCurrentTab, hideAndShowCurrentTab } = require('./support/test-utils')
+const { expectPlausibleInAction, hideCurrentTab, hideAndShowCurrentTab } = require('./support/test-utils')
const { test } = require('@playwright/test')
const { LOCAL_SERVER_ADDR } = require('./support/server')
@@ -32,8 +32,6 @@ test.describe('scroll depth (engagement events)', () => {
]
})
- await engagementCooldown(page)
-
await expectPlausibleInAction(page, {
action: () => page.click('#home-link'),
expectedRequests: [
diff --git a/tracker/test/support/test-utils.js b/tracker/test/support/test-utils.js
index f6f8d7cd48..645aee3f3d 100644
--- a/tracker/test/support/test-utils.js
+++ b/tracker/test/support/test-utils.js
@@ -1,11 +1,5 @@
const { expect, Page } = require("@playwright/test");
-// Since engagement events in the Plausible script are throttled to 300ms, we
-// often need to wait for an artificial timeout before navigating in tests.
-exports.engagementCooldown = async function(page) {
- return page.waitForTimeout(400)
-}
-
// Mocks an HTTP request call with the given path. Returns a Promise that resolves to the request
// data. If the request is not made, resolves to null after 3 seconds.
const mockRequest = function (page, path) {
@@ -161,6 +155,23 @@ exports.showCurrentTab = async function(page) {
return toggleTabVisibility(page, false)
}
+async function setFocus(page, focus) {
+ await page.evaluate((focus) => {
+ Object.defineProperty(document, 'hasFocus', { value: () => focus, writable: true })
+
+ const eventName = focus ? 'focus' : 'blur'
+ window.dispatchEvent(new Event(eventName))
+ }, focus)
+}
+
+exports.focus = async function(page) {
+ return setFocus(page, true)
+}
+
+exports.blur = async function(page) {
+ return setFocus(page, false)
+}
+
exports.hideAndShowCurrentTab = async function(page, options = {}) {
await exports.hideCurrentTab(page)
if (options.delay > 0) {
@@ -169,6 +180,14 @@ exports.hideAndShowCurrentTab = async function(page, options = {}) {
await exports.showCurrentTab(page)
}
+exports.blurAndFocusPage = async function(page, options = {}) {
+ await exports.blur(page)
+ if (options.delay > 0) {
+ await delay(options.delay)
+ }
+ await exports.focus(page)
+}
+
function includesSubset(body, subset) {
return Object.keys(subset).every((key) => {
if (typeof subset[key] === 'object') {