plausible · macobo · Jun 20, 2025 · Jun 20, 2025 · Jun 20, 2025 · Jun 20, 2025
diff --git a/docs/custom-automatic-link-tracking.md b/docs/custom-automatic-link-tracking.md
@@ -10,25 +10,17 @@ If you track link clicks, then these count towards your billable monthly pagevie
 
 Many sites use link cloaking to make affiliate links cleaner and easier to manage. So rather than linking to `affiliatepartner.com/affiliateid` you link to a page on your domain name such as `yourdomain.com/go/affiliatepartner` and the visitor gets redirected to the actual affiliate link after clicking.
 
-The same system is used to make pretty URLs for file names. You have links to `yourdomain.com/product/download/productname` that actually redirect to `yourdomain.com/123456/Product2.3.exe`. 
+The same system is used to make pretty URLs for file names. You have links to `yourdomain.com/product/download/productname` that actually redirect to `yourdomain.com/123456/Product2.3.exe`.
 
 Instructions below can be used to start tracking every `<a>` (i.e. link) element on your site with some specified rules. It's very similar to our automated tracking of [outbound link clicks](outbound-link-click-tracking.md) and [file downloads](file-downloads-tracking.md) but you can choose based on the link URL (`href` attribute) which links to track.
 
 Here's how to automatically track clicks on cloaked affiliate links and other pretty URLs:
 
-:::tip Our WordPress plugin can track cloaked affiliate links automatically 
+:::tip Our WordPress plugin can track cloaked affiliate links automatically
 On WordPress? Check out our WordPress plugin which can track cloaked affiliate links automatically. [See more here](https://plausible.io/wordpress-analytics-plugin).
 :::
 
-## 1. Trigger custom events with JavaScript on your site
-
-First, make sure your tracking setup includes the second line as shown below:
-
-```html
-<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>
-<script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>
-```
-## 2. Add the JavaScript that will be sending the link click events to Plausible
+## 1. Add the JavaScript that will be sending the link click events to Plausible
 
 You need to add the following code to all of the pages where you want to track your links. You should insert the code below into your HTML page `<head>` section just under the custom event snippet.
 
@@ -43,15 +35,6 @@ On the line that says `var toBeTracked = '/go/'` change `/go/` to what you want
         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 handleLinkClick(event) {
@@ -62,26 +45,7 @@ On the line that says `var toBeTracked = '/go/'` change `/go/` to what you want
         if (link && shouldTrackLink(link)) {
             var eventName = 'Cloaked Link: Click'
             var eventProps = { url: link.href }
-            return sendLinkClickEvent(event, link, eventName, eventProps)
-        }
-    }
-
-    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 })
         }
     }
 
@@ -109,7 +73,7 @@ If simply containing a substring is not enough to differentiate between links yo
 
 where `\/` stands for a forward slash (escaped with `\`) and `.*` will match any (or empty) string in the middle. It will basically match anything that contains the format `products/<anything>/details`.
 
-## 3. Create a custom event goal in your Plausible Analytics account
+## 2. Create a custom event goal in your Plausible Analytics account
 
 You'll have to configure the goal for the click numbers to show up in your Plausible dashboard. To configure a goal, go to [your website's settings](website-settings.md) in your Plausible Analytics account and visit the "**Goals**" section. You should see an empty list with a prompt to add a goal.
 
@@ -119,6 +83,6 @@ Click on the "**+ Add goal**" button to go to the goal creation form.
 
 Select `Custom event` as the goal trigger and enter this exact name: `Cloaked Link: Click`.
 
-Next, click on the "**Add goal**" button and you'll be taken back to the Goals page. When you navigate back to your Plausible Analytics dashboard, you should see the number of visitors who have completed your new custom event. Goal conversions are listed at the very bottom of the dashboard. Note that at least one click is required for this to show in your dashboard. 
+Next, click on the "**Add goal**" button and you'll be taken back to the Goals page. When you navigate back to your Plausible Analytics dashboard, you should see the number of visitors who have completed your new custom event. Goal conversions are listed at the very bottom of the dashboard. Note that at least one click is required for this to show in your dashboard.
 
 That's it. You're now tracking all link clicks on your site with custom URL matching rules!
diff --git a/docs/custom-event-goals.md b/docs/custom-event-goals.md
@@ -8,35 +8,21 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 If you use the custom events feature, then these count towards your billable monthly pageviews.
 :::
 
-Custom events allow you to measure button clicks, purchases, subscription signups, form completions and pretty much any other action that you wish your visitors to take. 
-
-"**Custom events**" is an [optional enhanced measurement](script-extensions.md) that's not included in our default script. This is because we want to keep the default script as simple and lightweight as possible. If you want to track custom events, here's how to enable it:
-
-## Step 1: Enable "Custom events" for your site
-
-You can enable "**Custom events**" as an optional measurement when adding a new site to your Plausible account. If the site has already been added to your account, you can control what data is collected in the "**Site Installation**" area of the "**General**" section in your [site settings](website-settings.md).
-
-<img alt="Enable custom events tracking during onboarding" src={useBaseUrl('img/onboarding-enable-custom-events-tracking.png')} />
-
-## Step 2: Change the snippet on your site
-
-The tracking snippet changes depending on your selection of optional measurements. When making changes to your optional measurements, do ensure to insert the newest snippet into your site for all tracking to work as expected.
-
-Your Plausible tracking snippet should be inserted into [the Header (`<head>`) section of your site](plausible-script.md). Place the tracking script within the `<head> … </head>` tags.
+Custom events allow you to measure button clicks, purchases, subscription signups, form completions and pretty much any other action that you wish your visitors to take.
 
 :::tip Using WordPress?
-The quickest way to start tracking custom events is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) 
+The quickest way to start tracking custom events is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin)
 :::
 
-## Step 3: Add a CSS class name to the element you want to track on your site
+## Add a CSS class name to the element you want to track on your site
 
 :::tip Use pageview goals to track the "thank you" page or the order confirmation page
 As an alternative to custom events, check out the [pageview goals](pageview-goals.md). Since pageviews are collected automatically, you don’t need to change your website’s code to measure pageview goals. This makes pageview goals the easiest way to start tracking any type of conversions.
 :::
 
-Tag the site element you want to track with a CSS class name. How to do this varies depending on the site builder, CMS or framework you've used to build your site. 
+Tag the site element you want to track with a CSS class name. How to do this varies depending on the site builder, CMS or framework you've used to build your site.
 
-For instance, if you're using WordPress, you can click on any block element you want to track such as a button or a form. This will open up the block menu on the right-hand side of your screen. 
+For instance, if you're using WordPress, you can click on any block element you want to track such as a button or a form. This will open up the block menu on the right-hand side of your screen.
 
 <img alt="Click on any WordPress block element you want to track such as a button or a form" src={useBaseUrl('img/wordpress-button-css-class-name.png')} />
 
@@ -48,7 +34,7 @@ For example: `plausible-event-name=Form+Submit` will display as `Form Submit` in
 
 <img alt="Add a CSS class name in the 'Additional CSS class(es)' field" src={useBaseUrl('img/wordpress-css-class-name.png')} />
 
-When tracking form submits, it is important to tag the `<form>` element itself with the `plausible-event-name=...` class (not the `input` or `button` element inside the form). Normally, Plausible can track button clicks, but if a button is inside a form, it will navigate to the next page often leaving not enough time for the event to finish.
+When tracking form submits this way, we recommend tagging the `<form>` element itself with the `plausible-event-name=...` class (not the `input` or `button` element inside the form).
 
 :::tip Some CMSs (like Webflow) do not support an equals sign (`=`) in the classnames
 If that's the case, use a double dash (`--`) instead of the equals sign. For example: `plausible-event-name--signup`
@@ -80,9 +66,9 @@ Or if your element already has a class attribute, just separate the new ones wit
 
 After adding the class, please go back to your site, and verify that the class attribute got added with the exact required format. You can check it by right-clicking the element and inspecting it. This will show you the HTML code of the element.
 
-In some cases, the tracking classes might be added to a wrapper `<div>` element (parent to the element you want to track), but don't worry, Plausible will still be able to track clicks on the child element if its parent has the necessary classes. 
+In some cases, the tracking classes might be added to a wrapper `<div>` element (parent to the element you want to track), but don't worry, Plausible will still be able to track clicks on the child element if its parent has the necessary classes.
 
-Some CMSs like Webflow do not support an equals sign (`=`) in the classnames. If you add a class attribute with the value `plausible-event-name=Signup`, but when you go back to your page and inspect the element, it might have `class="plausible-event-name-Signup"` (equals sign replaced with a hyphen). 
+Some CMSs like Webflow do not support an equals sign (`=`) in the classnames. If you add a class attribute with the value `plausible-event-name=Signup`, but when you go back to your page and inspect the element, it might have `class="plausible-event-name-Signup"` (equals sign replaced with a hyphen).
 If that's the case, use a double dash (`--`) instead of the equals sign. For example: `plausible-event-name--signup`.
 
 :::tip Tracking form submissions may not work with forms that contain an element with `id="submit"` or `name="submit"`
@@ -95,7 +81,7 @@ If your CMS does not support adding CSS classes, please expand the following sec
 
 <summary>
 
-### My site builder does not support adding CSS classes 
+### My site builder does not support adding CSS classes
 
 If you're unable to add the classnames in your page editor, there's still a way for you to track custom events. This method includes copying and pasting some JavaScript code onto your page. You can expand this section and follow step-by-step instructions.
 
@@ -117,7 +103,7 @@ Go to your website, right-click and inspect the element you want to track, which
 
 </h3>
 
-If the element you want to track does not have an `id` attribute by default, you can try adding one in the edit mode of your CMS. However, if you don't have that option, then this approach will be impossible and you will have to check out the section at the bottom of this page - [implementing custom events manually with JavaScript](#trigger-custom-events-manually-with-a-javascript-function). 
+If the element you want to track does not have an `id` attribute by default, you can try adding one in the edit mode of your CMS. However, if you don't have that option, then this approach will be impossible and you will have to check out the section at the bottom of this page - [implementing custom events manually with JavaScript](#trigger-custom-events-manually-with-a-javascript-function).
 
 <h3>
 
@@ -205,7 +191,7 @@ You can click the link to automatically add all the goals you've been sending so
 
 That's it. You can now check our your goal conversions on the dashboard.
 
-## Edit a Custom Event Goal 
+## Edit a Custom Event Goal
 
 To edit a custom event goal, start by locating the custom event goal you want to update in the Goals list. Click on the "Edit goal" button next to it, which will bring up the goal editing form.
 
@@ -239,33 +225,35 @@ After you have the custom events in place, you can start creating [marketing fun
 
 </summary>
 
-For more specific tracking needs, you will have to write the JavaScript yourself. The API only consists of one function, which you can use in your code by including the second line in your tracking setup, as shown below: 
-
-```html
-<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>
-<script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>
-```
-
-This snippet creates a global function called `plausible` which can be used to trigger custom events from anywhere in your code.
-
-Here's what triggering a custom event looks like:
+For more specific tracking needs, you will have to write the JavaScript yourself. Here's what triggering a custom event looks like:
 
 ```javascript
 plausible('Signup')
 ```
 
 The first argument to this function ("Signup" in this case) is the name of your custom event (i.e. the name of your goal).
 
-The second (optional) argument to the `plausible` function is an object with that currently supports the following options: 
+The second (optional) argument to the `plausible` function is an object with that currently supports the following options:
 
-* `callback` – a function that is called once the event is logged successfully.
+* `callback` - a function that is called for every event after it's logged, ignored or errored.
 * `props` - an object with custom properties. Read more and see examples [here](/custom-props/for-custom-events)
 * `revenue` - an object with revenue tracking fields. Read more and see examples [here](ecommerce-revenue-tracking.md)
+* `interactive` - whether to include the event in bounce rate calculations (defaults to true).
 
-Here's an example of the options argument using the `callback` and `props` options. 
+Here's an example of the options argument using the `callback` and `props` options.
 
 ```javascript
-plausible('Download', {callback: navigateFn, props: {method: 'HTTP'}})
+plausible('Download', {callback: callback, props: {method: 'HTTP'}})
+
+function callback(result) {
+  if (result && result.status) {
+    console.debug("Request to plausible done. Status:", result.status)
+  } else if (result && result.error) {
+    console.log("Error handling request:", result.error)
+  } else {
+    console.log("Request was ignored")
+  }
+}
 ```
 
 To mark an event as non-interactive, you can set the `interactive` argument to `false`. This will exclude the event from bounce rate calculations.
@@ -293,7 +281,7 @@ Example: Tracking audio and video elements
 ```html
 <script>
     var mediaElement = document.getElementById('trackedMedia')
-    
+
     // Set a flag to ignore the case where playing has already started and is resumed from paused state
     var mediaAlreadyStarted = false