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
ScriptV2: `transformRequest` (#5488)
Karl-Aksel Puulmannc3dd21431cde
diff --git a/.github/workflows/tracker-script-npm-release.yml b/.github/workflows/tracker-script-npm-release.ymlindex 87136c46a1..503c79aac4 100644--- a/.github/workflows/tracker-script-npm-release.yml+++ b/.github/workflows/tracker-script-npm-release.yml@@ -58,7 +58,9 @@ jobs:uses: EndBug/add-and-commit@a94899bca583c204427a224a7af87c02f9b325d5with:message: "Released tracker script version ${{ steps.package.outputs.version }}"- add: "tracker/npm_package"+ github_token: ${{ secrets.PLAUSIBLE_BOT_GITHUB_TOKEN }}+ add: |+ - tracker/npm_package- name: Notify team on successif: ${{ success() }}diff --git a/tracker/npm_package/CHANGELOG.md b/tracker/npm_package/CHANGELOG.mdindex 5ef949544d..db718beaf9 100644--- a/tracker/npm_package/CHANGELOG.md+++ b/tracker/npm_package/CHANGELOG.md@@ -7,4 +7,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## Unreleased-Initial release.+- Support for `config.transformRequest`+- Support for passing `url` as option when calling `track`diff --git a/tracker/npm_package/README.md b/tracker/npm_package/README.mdindex 65903b8b81..f545ad755d 100644--- a/tracker/npm_package/README.md+++ b/tracker/npm_package/README.md@@ -50,6 +50,7 @@ See also [plausible.d.ts](https://github.com/plausible/analytics/blob/master/tra| `formSubmissions` | Whether to track form submissions. | `false` || `captureOnLocalhost` | Whether to capture events on localhost. | `false` || `customProperties` | Object or function that returns custom properties for a given event. | `{}` |+| `transformRequest` | Function that allows transforming or ignoring requests | |#### Using `customProperties`diff --git a/tracker/npm_package/package.json b/tracker/npm_package/package.jsonindex 38171574e4..e114c9f911 100644--- a/tracker/npm_package/package.json+++ b/tracker/npm_package/package.json@@ -1,6 +1,6 @@{"name": "macobo-test-tracker",- "version": "0.1.6",+ "version": "0.2.0","description": "Plausible Analytics official frontend tracking library","scripts": {"test": "echo \"Error: Testing done in the tracker folder\" && exit 1"diff --git a/tracker/npm_package/plausible.d.ts b/tracker/npm_package/plausible.d.tsindex ac33c5e7b3..c0eef8ab1a 100644--- a/tracker/npm_package/plausible.d.ts+++ b/tracker/npm_package/plausible.d.ts@@ -34,6 +34,13 @@ export interface PlausibleConfig {// Custom properties to add to all events tracked.// If passed as a function, it will be called when `track` is called.customProperties?: CustomProperties | ((eventName: string) => CustomProperties)++ // A function that can be used to transform the payload before it is sent to the API.+ // If the function returns null or any other falsy value, the event will be ignored.+ //+ // This can be used to avoid sending certain types of events, or modifying any event+ // parameters, e.g. to clean URLs of values that should not be recorded.+ transformRequest?: (payload: PlausibleRequestPayload) => PlausibleRequestPayload | null}export interface PlausibleEventOptions {@@ -56,7 +63,7 @@ export interface PlausibleEventOptions {// Overrides the URL of the page that the event is being tracked on.// If not provided, `location.href` will be used.- u?: string+ url?: string}export type CustomProperties = Record<string, string>@@ -67,3 +74,20 @@ export type PlausibleEventRevenue = {// Currency is an ISO 4217 string representing the currency code, e.g. "USD" or "EUR"currency: string}++export type PlausibleRequestPayload = {+ // Event name+ n: string,+ // URL of the event+ u: string,+ // Domain of the event+ d: string,+ // Referrer+ r?: string | null,+ // Custom properties+ p?: CustomProperties,+ // Revenue information+ $?: PlausibleEventRevenue,+ // Whether the event is interactive+ i?: boolean,+} & Record<string, unknown>diff --git a/tracker/package.json b/tracker/package.jsonindex 55cb3d05ca..b5d9a13f8e 100644--- a/tracker/package.json+++ b/tracker/package.json@@ -1,5 +1,5 @@{- "tracker_script_version": 16,+ "tracker_script_version": 17,"type": "module","scripts": {"deploy": "node compile.js",diff --git a/tracker/src/track.js b/tracker/src/track.jsindex 7fb4498983..18ad2a59c8 100644--- a/tracker/src/track.js+++ b/tracker/src/track.js@@ -55,7 +55,7 @@ export function track(eventName, options) {payload.v = COMPILE_TRACKER_SCRIPT_VERSIONif (COMPILE_MANUAL) {- var customURL = options && options.u+ var customURL = options && (options.u || options.url)payload.u = customURL ? customURL : location.href} else {@@ -111,6 +111,14 @@ export function track(eventName, options) {payload.h = 1}+ if ((COMPILE_PLAUSIBLE_WEB || COMPILE_PLAUSIBLE_NPM) && typeof config.transformRequest === 'function') {+ payload = config.transformRequest(payload)++ if (!payload) {+ return onIgnoredEvent(eventName, options, 'transformRequest')+ }+ }+if (isPageview) {postPageviewTrack(payload)}diff --git a/tracker/test/fixtures/plausible-npm.html b/tracker/test/fixtures/plausible-npm.htmlindex 08c468ce2f..288a1857cb 100644--- a/tracker/test/fixtures/plausible-npm.html+++ b/tracker/test/fixtures/plausible-npm.html@@ -19,7 +19,8 @@<a id="outbound-link" href="https://example.com">Outbound link</a>- <a id="manual-pageview" onclick="window.track('pageview', { u: '/:test-plausible' })">Manual pageview</a>+ <a id="manual-pageview-1" onclick="window.track('pageview', { u: '/:test-plausible' })">Manual pageview</a>+ <a id="manual-pageview-2" onclick="window.track('pageview', { url: '/:test-plausible-2' })">Manual pageview 2</a><a id="custom-event" onclick="window.track('Custom event', { props: { author: 'Karl' } })">Custom event</a>diff --git a/tracker/test/fixtures/plausible-web.html b/tracker/test/fixtures/plausible-web.htmlindex 4bb29b30fa..d9d9e3263f 100644--- a/tracker/test/fixtures/plausible-web.html+++ b/tracker/test/fixtures/plausible-web.html@@ -14,7 +14,8 @@<a id="outbound-link" href="https://example.com">Outbound link</a>- <a id="manual-pageview" onclick="plausible('pageview', { u: '/:test-plausible' })">Manual pageview</a>+ <a id="manual-pageview-1" onclick="plausible('pageview', { u: '/:test-plausible' })">Manual pageview</a>+ <a id="manual-pageview-2" onclick="plausible('pageview', { url: '/:test-plausible-2' })">Manual pageview 2</a><a id="custom-event" onclick="plausible('Custom event', { props: { author: 'Karl' } })">Custom event</a>diff --git a/tracker/test/shared-configuration-tests.js b/tracker/test/shared-configuration-tests.jsindex af2f456718..7664c77ff7 100644--- a/tracker/test/shared-configuration-tests.js+++ b/tracker/test/shared-configuration-tests.js@@ -11,15 +11,21 @@ import { test } from '@playwright/test'// Wrapper around calling `plausible.init` in the page context for users of `testPlausibleConfiguration`export async function callInit(page, config, parent) {- // Stringify the customProperties function to work around evaluate not being able to serialize functions+ // Stringify the customProperties and transformRequest functions to work around evaluate not being able to serialize functionsif (config && typeof config.customProperties === 'function') {config.customProperties = { "_wrapFunction": config.customProperties.toString() }}+ if (config && typeof config.transformRequest === 'function') {+ config.transformRequest = { "_wrapFunction": config.transformRequest.toString() }+ }await page.evaluate(({ config, parent }) => {if (config && config.customProperties && config.customProperties._wrapFunction) {config.customProperties = new Function(`return (${config.customProperties._wrapFunction})`)();}+ if (config && config.transformRequest && config.transformRequest._wrapFunction) {+ config.transformRequest = new Function(`return (${config.transformRequest._wrapFunction})`)();+ }eval(parent).init(config)}, { config, parent })}@@ -187,12 +193,15 @@ export function testPlausibleConfiguration({ openPage, initPlausible, fixtureNamaction: async () => {await openPage(page, {}, { skipPlausibleInit: true })await initPlausible(page, { autoCapturePageviews: false })- await page.click('#manual-pageview')+ await page.click('#manual-pageview-1')+ await page.click('#manual-pageview-2')await hideAndShowCurrentTab(page, { delay: 200 })},expectedRequests: [{ n: 'pageview', u: '/:test-plausible', d: 'example.com' },{ n: 'engagement', u: '/:test-plausible', d: 'example.com' },+ { n: 'pageview', u: '/:test-plausible-2', d: 'example.com' },+ { n: 'engagement', u: '/:test-plausible-2', d: 'example.com' },],})})@@ -232,5 +241,64 @@ export function testPlausibleConfiguration({ openPage, initPlausible, fixtureNamexpectedRequests: [{ n: 'pageview', d: 'example.com', u: expecting.stringContaining(fixtureName)}]})})++ test('supports ignoring requests with `transformRequest`', async ({ page }) => {+ await expectPlausibleInAction(page, {+ action: async () => {+ await openPage(page, {}, { skipPlausibleInit: true })+ await initPlausible(page, { transformRequest: () => null })+ await page.click('#custom-event')+ },+ expectedRequests: [],+ refutedRequests: [{ n: 'Custom event' }, { n: 'pageview' }]+ })+ })++ test('supports modifying the request payload with `transformRequest`', async ({ page }) => {+ const transformRequest = (payload) => {+ payload.p = payload.p || {}+ payload.p.eventName = payload.n+ payload.i = false++ return payload+ }++ await expectPlausibleInAction(page, {+ action: async () => {+ await openPage(page, {}, { skipPlausibleInit: true })+ await initPlausible(page, { transformRequest })+ await page.click('#custom-event')+ },+ expectedRequests: [+ { n: 'pageview', p: { eventName: 'pageview' }, i: false },+ { n: 'Custom event', p: { eventName: 'Custom event', author: 'Karl' }, i: false }+ ]+ })+ })++ test('transformRequest props are sent with engagement events', async ({ page }) => {+ const transformRequest = (payload) => {+ payload.p = payload.p || {}++ window.requestCount = (window.requestCount || 0) + 1+ payload.p.requestCount = window.requestCount++ return payload+ }++ await expectPlausibleInAction(page, {+ action: async () => {+ await openPage(page, {}, { skipPlausibleInit: true })+ await initPlausible(page, { transformRequest })+ await page.click('#custom-event')+ await hideAndShowCurrentTab(page, { delay: 200 })+ },+ expectedRequests: [+ { n: 'pageview', p: { requestCount: 1 } },+ { n: 'Custom event', p: { author: 'Karl', requestCount: 2 } },+ { n: 'engagement', p: { requestCount: 1 } }+ ]+ })+ })})}