Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.
TypeScript analyticsanalytics-dashboardclickhouseelixirgoogle-analyticsmarketingopen-source-analyticsphoenixplausible-analyticspostgresqlprivacyprivacy-friendlyself-hostedsimple-analyticsstatisticstailwindcssweb-analyticswebsite-analyticswebsite-statswebsite-tracking
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.ymlnew file mode 100644index 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_actionsdiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.### Removeddiff --git a/tracker/compile.js b/tracker/compile.jsindex 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.jsonindex 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.jsindex 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 variablevar 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.udiff --git a/tracker/test/engagement.spec.js b/tracker/test/engagement.spec.jsindex 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 pageawait 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 URLawait 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.jsindex 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 plausibleRequestMockexpect(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.jsindex 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.jsindex 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') {