diff --git a/docs/custom-automatic-link-tracking.md b/docs/custom-automatic-link-tracking.md index 5086b8f6..c12541e4 100644 --- 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 `` (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 - - -``` -## 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 `` 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//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 index ab1eba38..2310c4e5 100644 --- 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). - -Enable custom events tracking during onboarding - -## 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 (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` 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. Click on any WordPress block element you want to track such as a button or a form @@ -48,7 +34,7 @@ For example: `plausible-event-name=Form+Submit` will display as `Form Submit` in Add a CSS class name in the 'Additional CSS class(es)' field -When tracking form submits, it is important to tag the `
` 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 `` 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 `
` 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 `
` 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 -### 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 -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).

@@ -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,16 +225,7 @@ After you have the custom events in place, you can start creating [marketing fun

-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 - - -``` - -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') @@ -256,16 +233,27 @@ 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 +```javascript +plausible.init({ + autoCapturePageviews: false +}) ``` - ## 2. Trigger the pageview event Once you've added the manual extension, the `pageview` event won't be sent automatically anymore: you'll have to trigger it manually. -To trigger events manually, you need to add the following script after your regular Plausible tracking script: - -```html - - -``` - -Once that's done, you can create another script in which you will trigger your pageview event: +To trigger your pageview event, call the following javascript function: -```html - - +```javascript +plausible('pageview') ``` -At this point, your pageview events are being triggered just like before, but you haven't defined a custom location yet. +At this point, your pageview events are being triggered just like before, but you haven't defined a custom location yet. This is what we'll do in the next step. ## 3. Specify a custom location -The `plausible` function in the `manual` script extension allows you to provide an option named `u`. +The `plausible` function allows you to provide an option named `url`. This option allows you to specify the URL of the page you're on. -To use it, you can update your `pageview` trigger code to add the `u` option as the second parameter, like so: +To use it, you can update your `pageview` trigger code to add the `url` option as the second parameter, like so: ```js -plausible('pageview', { u: "https://yourdomain.com/my-custom-location" + window.location.search }); +plausible('pageview', { url: "https://yourdomain.com/my-custom-location" + window.location.search }); ``` :::note The `+ window.location.search` is needed to persist query parameters from your actual URL. Plausible uses `ref`, `source`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` and `utm_term` query parameters for source acquisition. [Learn more here](top-referrers.md). ::: -At this point, your entire setup should look like this: - -```html - - - - - -``` - -Once you have specified an URL through the `u` option, all the pageview events triggered from that script will be sent as if they came from that URL. In this case, all the pageview events will appear as if they came from `https://yourdomain.com/my-custom-location`). +Once you have specified an URL through the `url` option, all the pageview events triggered from that script will be sent as if they came from that URL. In this case, all the pageview events will appear as if they came from `https://yourdomain.com/my-custom-location`). -You can specify the `u` option in your other events as well if you wish to do so. +You can specify the `url` option in your other events as well if you wish to do so. In a real-world scenario, the URL you provide to Plausible would likely be dynamic, changing depending on the current page and context. The URL can be provided by a JavaScript variable or function, or rendered by the server when generating the page. You can take a look at the examples below to see how URLs can be provided dynamically in common use cases. @@ -99,19 +75,23 @@ Let's say you have multiple URLs that link to the same pages, such as: Perhaps you would like to combine all the pageviews for these pages so they all appear in Plausible as the canonical URL for this product (which might be `https://yourdomain.com/products/banana-leather-shoe`, for example). -To do so, you could write a JavaScript function that gets the canonical URL and that provides it to Plausible's pageview event: +`transformRequest` allows providing an option for getting the canonical URL and overriding the request url. To do so, in your Plausible tracking snippet, add the following: -```html - - - + if (canonicalMeta) { + payload.u = canonicalMeta.href + window.location.search + } + return payload +} + +// At the end, update plausible.init call +plausible.init({ + transformRequest: transformRequest +}) ``` _Et voilà!_ From now on, your pageviews will automatically appear as coming from the canonical URL (`https://yourdomain.com/products/banana-leather-shoe` for the product we used in our example). @@ -120,30 +100,36 @@ Plus, if you trigger other events on the page, you can reuse the `url` variable ### Redacting identifiers from URLs -If you have a web application, you likely have URLs with identifiers in them, such as `https://yourapp.com/project/123456/settings`. This is great for your users as they can easily bookmark pages within your app. +If you have a web application, you likely have URLs with identifiers in them, such as `https://yourapp.com/project/123456/settings`. This is great for your users as they can easily bookmark pages within your app. However, having the dashboard page of every project appear as individual pages in your analytics may not be all that great. In fact, it can rapidly make your data really hard to analyze: imagine seeing 100 different URLs in your analytics for the same route, instead of seeing a single URL with 100 pageviews. In situations like these, redacting identifiers from URLs can make things much more manageable, and only takes a few minutes to implement. -For example, you could write a JavaScript function that uses a regular expression to remove numerical identifiers from the URLs that Plausible receives: +For example, you could write a `transformRequest` that uses a regular expression to remove numerical identifiers from the URLs that Plausible receives. To do so, insert this into your snippet: -```html - - - + return url.replace(/\/\d+\//g, "/_ID_/"); +} + +function transformRequest(payload) { + payload.u = redactedUrl() + window.location.search + return payload +} + +// At the end, update plausible.init call +plausible.init({ + transformRequest: transformRequest +}) ``` -And just like that, your pageviews will start being tracked as `https://yourapp.com/project/_ID_/settings`. +And just like that, your pageviews will start being tracked as `https://yourapp.com/project/_ID_/settings`. If your identifiers aren't entirely numerical, or if you only want to redact some identifiers but keep others, you can update the regular expression to match your format. With all the different identifiers being aggregated under the same URL, it's suddenly much easier to see which pages and features your visitors use the most! -Thanks to [Émile Perron](https://github.com/EmilePerron) for the contribution! +Thanks to [Émile Perron](https://github.com/EmilePerron) for the contribution! diff --git a/docs/custom-props/for-custom-events.md b/docs/custom-props/for-custom-events.md index bccdb24f..3a8869ff 100644 --- a/docs/custom-props/for-custom-events.md +++ b/docs/custom-props/for-custom-events.md @@ -4,17 +4,9 @@ title: Attach custom properties to custom events import useBaseUrl from '@docusaurus/useBaseUrl'; -## Step 1: Enable "Custom events" for your site +## Tag properties to custom events you want to track -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). - -Enable custom events tracking during onboarding - -Note that 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. - -## Step 2. Tag properties to custom events you want to track - -Now, let's say you have a contact form both in the header and footer of your site. In addition to tracking submissions, you might want to know which section of your site the form was submitted on. Instead of creating separate goals for each form, you can send a custom property instead: +Let's say you have a contact form both in the header and footer of your site. In addition to tracking submissions, you might want to know which section of your site the form was submitted on. Instead of creating separate goals for each form, you can send a custom property instead: Similarly to how you define an event name inside the `class` attribute, you can use the format `plausible-event-=` to define custom properties. Following the same example, your code might look something like this: @@ -36,10 +28,14 @@ This is because you can't include the space character in the `class` attribute You can add up to 30 classes for custom properties. Simply separate them with a space character like in the above example. +:::note +If you don't see a `plausible.init` call in your snippet, [upgrade your script](/script-update-guide) +::: +
- + ## Tag custom properties using the manual method diff --git a/docs/custom-props/for-pageviews.md b/docs/custom-props/for-pageviews.md index cf99c72e..1f994214 100644 --- a/docs/custom-props/for-pageviews.md +++ b/docs/custom-props/for-pageviews.md @@ -4,75 +4,58 @@ title: Attach custom properties to pageviews import useBaseUrl from '@docusaurus/useBaseUrl'; -## Step 1: Enable "Custom properties" for your site - -You can enable "**Custom properties**" 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). - -Enable custom props for pageviews during onboarding - -Note that 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. - -## Step 2: Add your custom properties to your Plausible snippet +:::tip Using WordPress? +The quickest way to start tracking custom properties is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) +::: -You should now add the custom properties as HTML attributes to your Plausible snippet (the ` -``` +You can add custom properties by updating your Plausible snippet. -You can add up to 30 custom properties alongside a pageview by adding multiple attributes: +To add properties that attach to every tracked event, update the `plausible.init` call to pass `customProperties` option: -```html - +```javascript +plausible.init({ + // ... Other initialization options + customProperties: { + author: "John Doe", + type: "blog-post" + } +}) ``` -All properties provided in the snippet will automatically be attached to any [custom event conversions](custom-event-goals.md) as well. - -Your Plausible tracking snippet should be inserted into [the Header (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` tags. - That's it! You're now tracking custom properties alongside pageviews. -:::tip Using WordPress? -The quickest way to start tracking custom properties is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) +:::note +If you don't see a `plausible.init` call in your snippet, [upgrade your script](/script-update-guide) :::
-## Using `script.manual.js` as an alternative +## Advanced: Dynamically setting custom properties -As an alternative, you can also use our `manual` script extension to send custom properties for pageviews. It works exactly the same way as with [custom properties for custom events](/custom-props/for-custom-events#2-using-the-manual-method). Make sure to write `pageview` exactly the same as in the following example: +To include dynamic data for custom properties, set `customProperties` to be a function. This function will be called for every event. -```javascript -plausible('pageview', {props: {author: 'John Doe', logged_in: 'false'}}) -``` - -This will send a pageview with properties `author` and `logged_in`. - -## Using a combination of `script.manual.pageview-props.js` +For example: -You can also combine the `manual` extension with the `pageview-props` extension. For example, if you're using this snippet: +```js +plausible.init({ + // ... Other initialization options + customProperties: function(eventName) { + if (eventName == "pageview") { + return { + author: "John Doe", + title: document.title + } + } -```html - + return {} + } +}) ``` -and also calling the `plausible` function manually like this: - -```javascript -plausible('pageview', {props: {author: 'John Doe'}}) -``` - -Then the pageview will be sent with two properties - `author` and `logged_in`. If you provide the exact same property name in the snippet and in sending the pageview manually, the value from the manual `plausible` function call will take precedence. For example, if you do this: - -```html - - -``` - -Then the pageview will be sent with `logged_in = true`. -
diff --git a/docs/custom-query-params.md b/docs/custom-query-params.md index e1a32bbd..098ee44d 100644 --- a/docs/custom-query-params.md +++ b/docs/custom-query-params.md @@ -8,31 +8,23 @@ Other than the source attribution query parameters listed above, Plausible strip If you still want some pages to be reported with the complete URL that includes the query part, here's what you should do: -## 1. Add the `manual` script extension +## 1. Disable automatic pageviews -You can use Plausible's manual script extension and define a custom location for all such pageviews. +To specify a custom location for your event, you must disable automatic pageview tracking. Update your snippet to set `autoCapturePageviews` to `false`. -To do so, change your Plausible script snippet `src` attribute from `https://plausible.io/js/script.js` to `https://plausible.io/js/script.manual.js`. - -The new snippet will look like this (make sure to change the `data-domain` attribute to the domain you added to your Plausible account): - -```html - +```javascript +plausible.init({ + autoCapturePageviews: false +}) ``` -Do this on all the pages where you want to track the custom query parameters. -## 2. Trigger the pageview event with a custom `u` attribute +Do this on all the pages where you want to track the custom query parameters. -Once you've started using the manual extension, the `pageview` event won't be sent automatically. This means that the stats won't be tracked anymore by default. You'll have to trigger the events to be counted manually. +## 2. Trigger the pageview event with a custom `url` attribute -To trigger events manually, you need to add the following script after your regular Plausible tracking snippet: +Once you've disabled `autoCapturePageviews` extension, the `pageview` event won't be sent automatically. This means that the stats won't be tracked anymore by default. You'll have to trigger the events to be counted manually. -```html - - -``` - -Once that's done, you can create another script in which you will trigger your pageview event. This is where you can also define a custom location and +Now you can create another script in which you will trigger your pageview event. This is where you can also define a custom location and make the query part of the URL look like a standard subfolder. To do so, add the following snippet: ```html @@ -48,42 +40,21 @@ make the query part of the URL look like a standard subfolder. To do so, add the } return customUrl } - plausible('pageview', { u: prepareUrl(["CUSTOM_PARAM_1", "CUSTOM_PARAM_2", ... ]) + window.location.search }) + plausible('pageview', { url: prepareUrl(["CUSTOM_PARAM_1", "CUSTOM_PARAM_2", ... ]) + window.location.search }) ``` Make sure to replace `CUSTOM_PARAM_X` with your query parameter names. You can define as many as you want. For example, for `yoursite.com/blog/index.php?article=some_article&page=11` you could write the last line as ```javascript -plausible('pageview', { u: prepareUrl(["article", "page"]) + window.location.search }); +plausible('pageview', { url: prepareUrl(["article", "page"]) + window.location.search }); ``` and the page path will be reported to your dashboard as `blog/index.php/some_article/11` -At this point, your entire setup should look like this: - -```html - - - - - -``` :::note The `+ window.location.search` is needed to persist source acquisition query parameters from your actual URL. Plausible uses `ref`, `source`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` and `utm_term` query parameters for source acquisition. ::: -That's it! You're now tracking the complete URLs of the pages that include custom parameters. +That's it! You're now tracking the complete URLs of the pages that include custom parameters. diff --git a/docs/ecommerce-revenue-tracking.md b/docs/ecommerce-revenue-tracking.md index 45fe48cb..57e40975 100644 --- a/docs/ecommerce-revenue-tracking.md +++ b/docs/ecommerce-revenue-tracking.md @@ -4,7 +4,7 @@ title: Ecommerce revenue and attribution tracking import useBaseUrl from '@docusaurus/useBaseUrl'; -You can assign dynamic monetary values to custom events to track revenue attribution. Revenue attribution helps you determine which marketing campaigns and landing pages result in the most revenue for your business or ecommerce store. +You can assign dynamic monetary values to custom events to track revenue attribution. Revenue attribution helps you determine which marketing campaigns and landing pages result in the most revenue for your business or ecommerce store. When you create a new custom event, you can optionally assign a monetary value to it. Our revenue tracking supports multi-currencies too. You can send data in any local currency that the purchase is made in. When using revenue tracking, you'll be able to see these metrics in your dashboard: @@ -16,31 +16,19 @@ When you create a new custom event, you can optionally assign a monetary value t Ecommerce revenue goal top graph -The revenue metrics are fully filterable. For instance, you can see the total or average revenue for a particular custom event per any dimension such as a specific date, referral source, marketing campaign, entry page, country or device. +The revenue metrics are fully filterable. For instance, you can see the total or average revenue for a particular custom event per any dimension such as a specific date, referral source, marketing campaign, entry page, country or device. You can add multiple filters to [create audience segments](filters-segments.md) too. This allows you to see the conversions and revenue from for instance the audience segment that's located in Germany, Austria and Switzerland, that were referred by a particular UTM campaign and are using Mac OS. -"**Ecommerce revenue**" 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 ecommerce revenue, here's how to enable it: +If you want to track ecommerce revenue, here's how to enable it: -## Step 1: Enable "Ecommerce revenue" for your site - -You can enable "**Ecommerce revenue**" 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). - -Enable revenue tracking during onboarding - -## 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 (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` tags. - -## Step 3: Add a new custom event and specify the currency of your choice +## Step 1: Add a new custom event and specify the currency of your choice Go to your [site settings](website-settings.md) and in the "**Goals**" section click on the "**Add goal**" button. Choose "**Custom event**" as the goal trigger, enter the goal name in the "**Event name**" field, switch to "**Enable Revenue Tracking**" and set the base currency of your choice. This currency will be used for total and average revenue metrics in the dashboard. Note that the currency for a specific event cannot be changed later. Add goal and choose your currency -## Step 4: Send the revenue data from your site +## Step 2: Send the revenue data from your site You can now start sending revenue data from your site alongside custom events. You can send the revenue data in the currency that the purchase was made in too and we'll convert it to your goal's base currency. @@ -62,7 +50,7 @@ window.plausible("goal name", {revenue: {currency: "USD", amount: 10.29}}) Or using the [Events API](events-api.md) directly. -Custom events and revenue goals are listed at the bottom of your dashboard and will appear as soon as the first conversion has been tracked. +Custom events and revenue goals are listed at the bottom of your dashboard and will appear as soon as the first conversion has been tracked. Ecommerce revenue tracking goal @@ -82,7 +70,7 @@ All this is done automatically for you by our plugin and you don't need to manua ## Integrating with Shopify -If you're using Shopify, you can track sales and revenue by making a few changes to the order status page. See [our complete Shopify guide here](shopify-integration.md). +If you're using Shopify, you can track sales and revenue by making a few changes to the order status page. See [our complete Shopify guide here](shopify-integration.md). ## Integrating with Magento diff --git a/docs/error-pages-tracking-404.md b/docs/error-pages-tracking-404.md index c63c6785..ed7d2646 100644 --- a/docs/error-pages-tracking-404.md +++ b/docs/error-pages-tracking-404.md @@ -16,27 +16,9 @@ Tracking 404 error pages is essential for many site owners and Plausible helps y * See where visitors find broken links to your 404 error pages * Then you can manually fix broken links and redirect error pages -"**404 error pages**" is an [optional enhanced measurement](script-extensions.md). If you want to track 404 error pages, here's how to enable it: +"**404 error pages**" requires additional work in addition to [setting up tracking script](/plausible-script). If you want to track 404 error pages, here's how to enable it: -## Step 1: Enable "404 error pages" for your site - -You can enable "**404 error pages**" 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). - -Enable 404 tracking during onboarding - -After you enable 404 error pages tracking, we will automatically add a new goal called `404` to your site. - -:::tip Using Google Tag Manager to integrate Plausible? -Please follow [our GTM-specific instructions](google-tag-manager.md) to correctly set up 404 error pages tracking -::: - -## 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 (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` tags. - -## Step 3: Paste this piece of code to your 404 page template +## Paste this piece of code to your 404 page template Add this code to your 404 page. For instance, if you're using WordPress, your 404 page template will be called `404.php`. It will be located within your theme files. @@ -47,7 +29,7 @@ Add this code to your 404 page. For instance, if you're using WordPress, your 40 You can place this code anywhere in the `` or `` section of your 404 page template. :::tip Using WordPress? -The quickest way to start tracking 404 error pages is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) +The quickest way to start tracking 404 error pages is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) ::: ## See all the visits on 404 error pages in your dashboard @@ -64,8 +46,8 @@ Check out this blog post for more details on the value of [tracking 404 error pa You can control what data is collected in the "**Site Installation**" area of the "**General**" section in your [site settings](website-settings.md). -When making changes to your optional measurements, your snippet will change so do ensure to insert the newest snippet into your site for 404 error pages tracking to stop. You should also remove the code that you inserted into your 404 error page template. +When making changes to your optional measurements, your snippet will change so do ensure to insert the newest snippet into your site for 404 error pages tracking to stop. You should also remove the code that you inserted into your 404 error page template. -After you disable 404 error pages tracking, we will automatically remove the goal called `404` from your site. +After you disable 404 error pages tracking, we will automatically remove the goal called `404` from your site. Thanks to [Jeremiah Lee](https://www.jeremiahlee.com/) for contributing this to the Plausible Analytics community! diff --git a/docs/file-downloads-tracking.md b/docs/file-downloads-tracking.md index 55e533d0..fba90806 100644 --- a/docs/file-downloads-tracking.md +++ b/docs/file-downloads-tracking.md @@ -17,26 +17,18 @@ File downloads tracking is essential for many site owners and Plausible helps yo * Filter the dashboard by a file URL to see what type of visitors click the most (referral source, entry page, location, device, browser, OS) * Group your file downloads by any domain name or keyword -"**File downloads**" 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 file downloads, here's how to enable it: +"**File downloads**" is an [optional enhanced measurement](script-extensions.md). If you want to track file downloads, here's how to enable it: -## Step 1: Enable "File downloads" for your site +## Enable "File downloads" for your site You can enable "**File downloads**" 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). Enable outbound file downloads tracking during onboarding -After you enable file downloads tracking, we will automatically add a new goal called `File Download` to your site. - -## 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 (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` tags. - -After you change the tracking snippet on your site, all the file downloads will start being tracked and will be displayed in the "**Goal Conversions**" report of your Plausible Analytics dashboard. You'll see the "**File Download**" goal as soon as the first file download has been tracked. +After you enable file downloads tracking on your site, all the file downloads will start being tracked and will be displayed in the "**Goal Conversions**" report of your Plausible Analytics dashboard. You'll see the "**File Download**" goal as soon as the first file download has been tracked. :::tip Using WordPress? -The quickest way to start tracking file downloads is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) +The quickest way to start tracking file downloads is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) ::: ## See all the file download clicks in your dashboard @@ -48,8 +40,8 @@ Click on "**File Download**" goal in the "**Goal Conversions**" report of your P * The conversion rate * Top referral sources that lead to clicks * Top pages that drive the clicks -* Countries, regions and cities that click on file download -* Devices (screen size, browser, OS) that click on file download +* Countries, regions and cities that click on file download +* Devices (screen size, browser, OS) that click on file download Click on a particular file URL to filter the dashboard by those clicks only and get the full overview of that specific file. @@ -57,23 +49,23 @@ Want to group file downloads by the domain name or any other keyword? In the "** ## Which file types are tracked? -Our "**File downloads**" tracking captures a file download event each time a link is clicked with a document, presentation, text file, compressed file, video, audio or other common file type. Both internal and external files downloads are tracked. These file extensions are tracked by default: +Our "**File downloads**" tracking captures a file download event each time a link is clicked with a document, presentation, text file, compressed file, video, audio or other common file type. Both internal and external files downloads are tracked. These file extensions are tracked by default: `.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`, `.dmg` ## What if I want to track a different file type? -You can also specify a custom list of file types to track with a `file-types` attribute tag. With this, you can track other file types not present in our default list. Say you only want to track `.js` and `.py` files, you can use manually setup your tracking snippet like this: +You can also specify a custom list of file types to track with a `file-types` attribute tag. With this, you can track other file types not present in our default list. Say you only want to track `.js` and `.py` files, you can pass the following argument to `plausible.init`: -```html - +```javascript +plausible.init({ + fileDownloads: { + fileExtensions: ["pdf", "js"] + } +}) ``` -Using the `file-types` attribute will override our default list and only your custom file type downloads will be tracked. If you want to add custom file type downloads without overriding the default list you can use `add-file-types` instead like this: - -```html - -``` +Using the `fileExtensions` option will override our default list and only your custom file type downloads will be tracked. Learn more about [effectively optimizing for file downloads](https://plausible.io/blog/track-file-downloads-in-web-analytics) on our blog. @@ -81,6 +73,4 @@ Learn more about [effectively optimizing for file downloads](https://plausible.i You can control what data is collected in the "**Site Installation**" area of the "**General**" section in your [site settings](website-settings.md). -When making changes to your optional measurements, your snippet will change so do ensure to insert the newest snippet into your site for file downloads tracking to stop. - After you disable file downloads tracking, we will automatically remove the goal called `File Download` from your site. diff --git a/docs/form-submission-tracking.md b/docs/form-submission-tracking.md new file mode 100644 index 00000000..20a9de37 --- /dev/null +++ b/docs/form-submission-tracking.md @@ -0,0 +1,37 @@ +--- +title: Form submissions tracking +--- + + +:::note +If you use the form submissions tracking feature, then these count towards your billable monthly pageviews. +::: + +Plausible helps you automate tracking form submissions. With our "**Form submissions**" tracking you can: + +## Enable "Form submissions" for your site + +You can enable "**Form submissions**" 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). + + +Enable form submissions tracking during onboarding + +After you enable form submissions click tracking, we will automatically add a new goal called `Form: Submission` to your site. + +:::tip Using WordPress? +The quickest way to start tracking form submissions is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) +::: + +## See all the form submissions clicks in your dashboard + +Click on "**Form: Submission**" goal in the "**Goal Conversions**" report of your Plausible dashboard to see the full list of all form submissions and have your dashboard filtered by them. You can see: + +* The number of total form submissions +* The number of unique form submissions +* The conversion rate +* Top referral sources that lead to submissions +* Top pages that drive the submissions +* Countries that submit forms +* Devices (screen size, browser, OS) that click on forms + +Click on a particular form URL to filter the dashboard by those submissions only and get the full overview of that specific URL. diff --git a/docs/hash-based-routing.md b/docs/hash-based-routing.md index 3f4581a5..b452d18f 100644 --- a/docs/hash-based-routing.md +++ b/docs/hash-based-routing.md @@ -6,15 +6,17 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; If your site is using page paths with a `#` in the URL, you can use our "**Hashed page paths**" tracking to see the different pages your visitors have viewed. Here's how to enable it: -## Step 1: Enable "Hashed page paths" for your site +## Update your snippet -You can enable "**Hashed page paths**" tracking 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 how data is collected in the "**Site Installation**" area of the "**General**" section in your [site settings](website-settings.md). +We display your snippet during the process of adding a new site to your account. You can also see the snippet within the "**Site Installation**" area of the "**General** section in your [site settings](website-settings.md). -Enable hashed page paths tracking during onboarding +Update the snippet to pass the following argument to `plausible.init`: -## 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. We display your snippet during the process of adding a new site to your account. You can also see the snippet within the "**Site Installation**" area of the "**General** section in your [site settings](website-settings.md). +```javascript +plausible.init({ + hashBasedRouting: true +}) +``` Your Plausible tracking snippet should be inserted into [the Header (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` tags. diff --git a/docs/integration-guides.md b/docs/integration-guides.md index e1743815..2bacee73 100644 --- a/docs/integration-guides.md +++ b/docs/integration-guides.md @@ -302,7 +302,7 @@ A [Sylius Plausible plugin](https://github.com/Setono/sylius-plausible-plugin) t ## Turbo / Turbolinks -We offer a manual mode in case you want full control over when pageviews are triggered on your website. The most common use-case for this is when you use Turbo (formerly Turbolinks). [Learn more here](script-extensions.md) +We allow disabling automatic pageview tracking in case you want full control over when pageviews are triggered on your website. The most common use-case for this is when you use Turbo (formerly Turbolinks). [Learn more here](script-extensions.md) ## TYPO3 diff --git a/docs/outbound-link-click-tracking.md b/docs/outbound-link-click-tracking.md index 7fc40574..885264f2 100644 --- a/docs/outbound-link-click-tracking.md +++ b/docs/outbound-link-click-tracking.md @@ -17,9 +17,9 @@ Outbound link click tracking is essential for many site owners and Plausible hel * Filter the dashboard by external URL to see what type of visitors click the most (referral source, entry page, location, device, browser, OS) * Group your external link clicks by domain name or any keyword -"**Outbound links**" 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 external link clicks, here's how to enable it: +"**Outbound links**" is an [optional enhanced measurement](script-extensions.md). If you want to track external link clicks, here's how to enable it: -## Step 1: Enable "Outbound links" for your site +## Enable "Outbound links" for your site You can enable "**Outbound links**" 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). @@ -27,16 +27,8 @@ You can enable "**Outbound links**" as an optional measurement when adding a new After you enable outbound link click tracking, we will automatically add a new goal called `Outbound Link: Click` to your site. -## 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 (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` tags. - -After you change the tracking snippet on your site, all the external link clicks will start being tracked and will be displayed in the "**Goal Conversions**" report of your Plausible Analytics dashboard. You'll see the "**Outbound Link: Click**" goal as soon as the first external link click has been tracked. - :::tip Using WordPress? -The quickest way to start tracking outbound link clicks is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) +The quickest way to start tracking outbound link clicks is to use our [official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) ::: ## See all the outbound link clicks in your dashboard @@ -65,6 +57,6 @@ Check out this blog post for more details on the value of [tracking outbound lin You can control what data is collected in the "**Site Installation**" area of the "**General**" section in your [site settings](website-settings.md). -When making changes to your optional measurements, your snippet will change so do ensure to insert the newest snippet into your site for outbound link click tracking to stop. +When making changes to your optional measurements, your snippet will change so do ensure to insert the newest snippet into your site for outbound link click tracking to stop. After you disable outbound link click tracking, we will automatically remove the goal called `Outbound Link: Click` from your site. diff --git a/docs/plausible-script.md b/docs/plausible-script.md index 793a299a..8c4b69cb 100644 --- a/docs/plausible-script.md +++ b/docs/plausible-script.md @@ -4,13 +4,13 @@ title: Add the snippet to your website import useBaseUrl from '@docusaurus/useBaseUrl'; -To integrate your website with Plausible Analytics, you need to insert a Plausible tracking snippet into the header section of your site. Place the snippet within the ` … ` tags. +To integrate your website with Plausible Analytics, you need to insert a Plausible tracking snippet into the header section of your site. Place the snippet within the ` … ` tags. We display your snippet during the process of adding a new site to your account. For sites that you've already added to your account, you can find your JavaScript snippet by [logging into your Plausible account](https://plausible.io/sites). Here you'll find the list of websites you've added to Plausible. -Click on the menu icon on the right-hand side of the site you'd like to get the snippet for and choose "**Settings**" to enter the [site settings](website-settings.md). Then scroll down to the "**Site Installation**" area of the "**General**" section. Click on the "**Review Installation**" button to get the installation details including your snippet. +Click on the menu icon on the right-hand side of the site you'd like to get the snippet for and choose "**Settings**" to enter the [site settings](website-settings.md). Then scroll down to the "**Site Installation**" area of the "**General**" section. Click on the "**Review Installation**" button to get the installation details including your snippet. -There you can also enable any [optional enhanced measurements](script-extensions.md). Note that the 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. +There you can also enable any [optional enhanced measurements](script-extensions.md). Add script extensions and verify your installation @@ -29,49 +29,9 @@ Installing Plausible on a site can be a slightly different process depending on * If you'd like to serve our snippet as a first-party connection from your domain name, we offer a way to proxy our script. See [full details here](/proxy/introduction.md). * Prefer to avoid JavaScript and use server side tracking instead? We have [the events API for that](events-api.md). - -We've put together [several other guides and plugins](integration-guides.md) that cover popular website builders, content management systems (CMS) and frameworks. These can help you set up and start counting your site visitors in no time. - -## Can I send stats to multiple dashboards at the same time? - -Yes, you can send your visitor stats to multiple Plausible dashboards at the same time. To do this, you need to configure the data-domain attribute as a comma-separated list in the Plausible snippet. Here's an example: - -```html - -``` - -## Is there a roll-up view? - -:::note -Pageviews tracked using the roll-up view will count towards your billable monthly pageviews. -::: - -Rollup reporting allows you to aggregate stats from multiple sites and see them in one combined dashboard while keeping the individual site stats on their own separate dashboards. This way you get detailed insights into individual site performance and a holistic view of your whole network too. -This is useful when building multi-tenant applications, offering [a white label analytics dashboard](https://plausible.io/white-label-web-analytics) or in similar situations. It allows you to keep all your global traffic in one dashboard for internal purposes but also share the traffic from individual tenant sites with the particular client only. - -Here's how you can use it: - -* Say you have `yoursite.com`, `yoursecondsite.com` and `anothersite.com` as websites in your Plausible account -* Then you could add a new site to your Plausible account called for example `rollup.mysites.com` (you can come up with any name that you want for this, it doesn't need to be an actual domain) -* On the `yoursite.com` site, add the new site name to the data-domain attribute in your Plausible snippet like this: - -```html - -``` - -* And on `yoursecondsite.com` site, add the new site name to the data-domain attribute in your Plausible snippet like this: - -```html - -``` - -* Add the new site name to the data-domain attribute in your Plausible snippet on the `anothersite.com` site too. Like this: - -```html - -``` +We've put together [several other guides and plugins](integration-guides.md) that cover popular website builders, content management systems (CMS) and frameworks. These can help you set up and start counting your site visitors in no time. -## How to check if Plausible Analytics is installed correctly +## How to check if Plausible Analytics is installed correctly After adding the Plausible snippet to your website, you can use our testing tool to verify that the snippet is installed correctly and the integration is working. Have some issues with the integration? Take a look at [our guide to troubleshooting your Plausible Analytics integration](troubleshoot-integration.md). diff --git a/docs/script-extensions.md b/docs/script-extensions.md index ce93288e..6b9de635 100644 --- a/docs/script-extensions.md +++ b/docs/script-extensions.md @@ -4,113 +4,86 @@ title: Enable optional measurements import useBaseUrl from '@docusaurus/useBaseUrl'; -We're proud to have one of the most [lightweight JavaScript snippets](https://plausible.io/lightweight-web-analytics) in the analytics industry. +The Plausible JavaScript snippet offer enhanced measurements and configuration for tailoring to how you want to use Plausible. -We achieve that by radically limiting the number of options in the default script. Instead, we offer enhanced measurements as optional script extensions tailored to how you want to use Plausible. This approach makes sure that you only load the code that will actually be used on your website. - -You can enable these optional measurements when adding a new site to your Plausible account or in the "**Site Installation**" area of the "**General**" section in your [site settings](website-settings.md). +Optional measurements can enabled when adding a new site to your Plausible account or in the "**Site Installation**" area of the "**General**" section in your [site settings](website-settings.md). Enable optional enhanced measurements -:::tip The snippet changes depending on your selection of measurements -Note that the tracking snippet that you need to insert into your site changes depending on your selection of enhanced 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 -::: - Here's the list of our optional measurements: | Optional Measurement | Explanation | |--------------------------|----------------------------------------------------------------------------------------------------| | Outbound links | Automatically [track clicks on outbound links](outbound-link-click-tracking.md) | | File downloads | Automatically [track file downloads](file-downloads-tracking.md) | -| 404 error pages | Automatically [track 404 error pages](error-pages-tracking-404.md) | -| Hashed page paths | Automatically track page paths that use a `#` in the URL ([hash-based routing](hash-based-routing.md)) | -| Custom events | Allows you to [track custom events](custom-event-goals.md) such as link clicks, form submits and any other HTML element clicks | -| Custom properties | Allows you to attach [custom properties](/custom-props/introduction) (also known as custom dimensions in Google Analytics) when sending a pageview or custom event to create custom metrics | -| Ecommerce revenue | Allows you to assign dynamic [monetary values](ecommerce-revenue-tracking.md) to custom events and track revenue attribution | +| Form submissions | Automatically [track form submissions](form-submission-tracking.md) | -
+## `plausible.init()` configuration - +Additionally, `plausible.init()` can be called with different options further enhance its behavior. Supported options are: -## Advanced tracking options +| Option | Type | Default | Description | +| -- | -- | -- | -- | +| endpoint | `string` | `"https://plausible.io/api/event"` | Allows [proxying requests](/proxy/introduction) | +| hashBasedRouting | `boolean` | `false` | Track page paths that use a `#` in the URL ([hash-based routing](hash-based-routing.md)) | +| fileDownloads | `boolean` or `{ fileExtensions }` | `false` | Automatically [track file downloads](file-downloads-tracking.md) | +| outboundLinks | `boolean` | `false` | [track clicks on outbound links](outbound-link-click-tracking.md) | +| customProperties | `object` or `function(eventName)` | `{}` | [Add custom props globally](/custom-props/introduction) | +| formSubmissions | `boolean` | `false` | [Track form submissions](form-submission-tracking.md) | +| captureOnLocalhost | `boolean` | `false` | Enables tracking on localhost for dev environments | +| autoCapturePageviews | `boolean` | `true` | Automatically track pageviews | +| logging | `boolean` | `true` | Enable/disable logging done by script | +| transformRequest | `function(payload)` | – | Modify or filter events before sending (e.g. [for custom locations](/custom-locations))| - -In addition to the above list (`script.outbound-links.js`, `script.file-downloads.js`, `script.hash.js`, `script.tagged-events.js`, `script.pageview-props.js` and `script.revenue.js`), we also have some more advanced tracking options available. Note that these are not included in the site onboarding list so you will need to insert them into your tracking snippet manually. +## Advanced tracking recipes -| Extension | Explanation | -|--------------------------|----------------------------------------------------------------------------------------------------| -| script.compat.js | Compatibility mode for [tracking users on Internet Explorer](#scriptcompatjs) (≥IE11) | -| script.local.js | Allow analytics to track on localhost too which is useful in hybrid apps | -| script.manual.js | [Don't trigger pageviews automatically](#scriptmanualjs). Also allows you to [specify custom locations](custom-locations.md) to redact URLs with identifiers. You can also use it to track [custom query parameters](custom-query-params.md)| +### Tracking 404 error pages -### How to manually change the tracking snippet +See guide for [tracking 404 error pages](error-pages-tracking-404.md) -For example, the default script name in our snippet is `script.js`. If your website is on a localhost and you'd like to track those visits, you have the option of loading the script with a different extension: `script.local.js`. +### Tracking custom events -In this case, the snippet you need to insert into your site is as follows (make sure to change the data-domain attribute to the domain you added to Plausible): +See guide for [tracking custom events such as link clicks or any other HTML element clicks](custom-event-goals.md) -```html - -``` +### Attaching custom properties -You can mix and match, and combine these extensions any way that you wish. For instance, if you want to use both our hash-based routing and our outbound link click tracking, you can combine them as follows: `script.hash.outbound-links.js`. +See guide for [attaching custom properties](/custom-props/introduction) (also known as custom dimensions in Google Analytics) when sending a pageview or custom event to create custom metrics. -In this case, the snippet you need to insert into your site is as follows (make sure to change the data-domain attribute to the domain you added to Plausible): +### Ecommerce revenue -```html - -``` +See guide for [assigning dynamic monetary values](ecommerce-revenue-tracking.md) to custom events and track revenue attribution -Or say you want to use our `script.revenue.js` extension to track ecommerce revenue and our `script.local.js` extension to track localhost traffic, your snippet should look like this: +### Manual pageviews -```html - -``` +By default, the Plausible script triggers a pageview when it's first loaded. It also attaches listeners to the History API and will automatically trigger pageviews when you use `history.pushState`. This is useful for most websites but we also allow disabling `autoCapturePageviews` in case you want full control over when pageviews are triggered on your website. -And you only need to insert that one snippet into your site, no need for anything else. +One of the use-cases for this is when you use [Turbo](https://turbo.hotwired.dev/) (formerly [Turbolinks](https://github.com/turbolinks/turbolinks)). In that case, you want to manually trigger Plausible pageviews on the `turbo:load` or `turbolinks:load` browser event depending which library you use. -### script.compat.js +To do so, add update `plausible.init` to disable `autoCapturePageviews`: `plausible.init({ autoCapturePageviews: false })` -The default Plausible script won't work on Internet Explorer because it uses the [document.currentScript](https://caniuse.com/document-currentscript) API to read configuration options. You can run Plausible in compatibility mode by including the `script.compat.js` extension and defining `id="plausible"` on the script tag so that it can find itself. Note that this works only on ≥ IE11. Here's how it should look like: +Additionally, add a javascript listener that triggers pageviews on turbolinks navigation: -```html - -``` - -### script.manual.js - -By default, the Plausible script triggers a pageview when it's first loaded. It also attaches listeners to the History API and will automatically trigger pageviews when you use `history.pushState`. This is useful for most websites but we also offer a manual mode in case you want full control over when pageviews are triggered on your website. - -One of the use-cases for this is when you use [Turbo](https://turbo.hotwired.dev/) (formerly [Turbolinks](https://github.com/turbolinks/turbolinks)). In that case, you want to manually trigger Plausible pageviews on the `turbo:load` or `turbolinks:load` browser event depending which library you use. Here's how you can do that: - -```html - - - - - ``` -When using turbolinks, you should make sure that the Plausible script isn't loaded and executed during turbo navigation. You may need to move the script to the `` section of your website or use the `data-turbo-eval="false"` attribute to do so. - -:::note -When using manual.js every script call with `'pageview'` results in a separate pageview being counted even if called on the same page +:::note +Every script call with `'pageview'` results in a separate pageview being counted even if called on the same page ::: #### Specify custom locations for your page URLs -Additionally, the manual script extension allows you to provide a special option named `u` with your events. This allows you to specify the URL of the page and can be used to specify custom locations. +Triggering pageviews manually allows you to provide a special option named `url` with your events. This allows you to specify the URL of the page and can be used to specify custom locations. It's especially helpful to redact and aggregate multiple pages whose URLs contain identifiers that are specific to users. [Learn more about specifying custom URLs in your events](custom-locations.md). + #### Track custom query parameters for complete page URLs -By default, Plausible strips all query parameters for privacy purposes [except for](top-referrers.md) `ref`, `source`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` and `utm_term`. +By default, Plausible strips all query parameters for privacy purposes [except for](top-referrers.md) `ref`, `source`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` and `utm_term`. This means that pages like `yoursite.com/blog/index.php?article=some_article&page=11` will be reported as `yoursite.com/blog/index.php` in the "**Top Pages**" report of your Plausible dashboard. @@ -119,5 +92,3 @@ By using the manual script extension, you can also track custom query parameters :::tip Want to track outbound link clicks or file downloads cloaked with pretty URLs? See these [step-by-step instructions](custom-automatic-link-tracking.md) for how to do that. ::: - -
diff --git a/docs/script-update-guide.md b/docs/script-update-guide.md new file mode 100644 index 00000000..7e370d95 --- /dev/null +++ b/docs/script-update-guide.md @@ -0,0 +1,116 @@ +--- +title: Upgrade your Plausible script +--- + +In July 2025, Plausible released a new version of their tracking script. This document outlines +the differences from the old script and how to migrate. + +## Why a new script? + +Our previous approach with various script extensions could be uncomfortable to Plausible users +to manage. A new script also allows Plausible developers to build out new features. + +## Getting the new snippet + +You can see the new snippet within the "**Site Installation**" area of the "**General** section in your [site settings](website-settings.md). + +Your Plausible tracking snippet should be inserted into [the Header (``) section of your site](plausible-script.md). Place the tracking script within the ` … ` tags. + +## What has changed? + +This section outlines what has changed in the new snippet and how to adjust your setup.1 + +### 1. Each site has a unique snippet + +As a result, selecting new optional enhanced measurements no longer requires updating the snippet. + +### 2. New feature: Form submission tracking + +Tracking form submissions can now be toggled on and off in **Site Installation** settings. + +### 3. Changed: Custom properties + +If you were using data-attributes for custom properties, you will need to add `customProperties` option with your custom properties + +```javascript +plausible.init({ + customProperties: { + author: "John Doe" + } +}) +``` + +Read more about custom properties in [custom pageview properties](/custom-props/for-pageviews) documentation. + +### 4. Changed: Custom tracking endpoint + +The new script no longer supports the `data-api` attribute to send events to a custom endpoint. Set `endpoint` option instead: + +```javascript +plausible.init({ + // Replace with your custom endpoint + endpoint: "https://plausible.io/api/event" +}) +``` + +### 5. Changed: custom file download types + +To track file downloads only for certain file types, you will need to set `fileDownloads` option: + +```javascript +plausible.init({ + fileDownloads: { + fileExtensions: ["pdf"] + } +}) +``` + +By default, plausible tracks the following file types: 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, dmg + +### 6. Changed: Hashed page paths + +If you were previously using a hash based routing and had a `.hash` in your script path, you will need to set `hashBasedRouting` option: + +```javascript +plausible.init({ + hashBasedRouting: true +}) +``` + +See also [Hashed page paths guide](/hash-based-routing.md) + +### 7. Changed: Tracking pageviews manually + +If you were previously using the `manual` extension to track pageviews manually, you will need to set `autoCapturePageviews` option to `false`: + +```javascript +plausible.init({ + autoCapturePageviews: false +}) +``` + +See also [Custom locations guide](/custom-locations). + +### 8. Changed: Tracking on localhost + +If you were previously using `local` extension to track events on localhost, you will need to set `captureOnLocalhost` option to `true`: + +```javascript +plausible.init({ + captureOnLocalhost: true +}) +``` + +### 9. Changed: Custom events and revenue features are automatically enabled + +If you were already using these features, no additional steps are required. Documentation links: +- [Custom events](/custom-event-goals) +- [Ecommerce revenue and attribution tracking](docs/ecommerce-revenue-tracking.md) + +### 10. Removed: `data-exclude` + +The new script no longer supports the `data-exclude` and `data-include` attributes. See [alternative guide](/excluding.md) instead. + +### 11. Removed: multiple domain support + +The new script does not support sending stats to multiple dashboards at once anymore. Keep using the old script for this functionality. diff --git a/docs/shopify-integration.md b/docs/shopify-integration.md index b689771a..17cf0bd8 100644 --- a/docs/shopify-integration.md +++ b/docs/shopify-integration.md @@ -8,7 +8,7 @@ Here's how to add Plausible Analytics to your Shopify store and set up the track ## Add Plausible snippet to Shopify -* Log in to your Shopify account and click on Sales Channels > Online Store > Themes in the left-hand side menu. +* Log in to your Shopify account and click on Sales Channels > Online Store > Themes in the left-hand side menu. * Click on the icon with three dots next to your current theme and choose "**Edit code**" from the drop-down menu. @@ -22,7 +22,7 @@ Here's how to add Plausible Analytics to your Shopify store and set up the track ## Track checkouts and revenue attribution -Even after having added the Plausible snippet into your `theme.liquid` file, checkout pages such as `/checkouts/cn/:id/review` or `/checkouts/cn/:id/thank-you` will not be tracked yet. That's because they're not using the same theme layout. To enable pageview tracking on checkout pages, you need to create a custom pixel. The same pixel can also be used for tracking Shopify's customer events (e.g. `"product_added_to_cart"`, `"checkout_completed"`, etc...) with revenue attribution and custom properties. +Even after having added the Plausible snippet into your `theme.liquid` file, checkout pages such as `/checkouts/cn/:id/review` or `/checkouts/cn/:id/thank-you` will not be tracked yet. That's because they're not using the same theme layout. To enable pageview tracking on checkout pages, you need to create a custom pixel. The same pixel can also be used for tracking Shopify's customer events (e.g. `"product_added_to_cart"`, `"checkout_completed"`, etc...) with revenue attribution and custom properties. To create the custom pixel, follow these steps: @@ -77,7 +77,7 @@ Track pageviews on checkout page paths such as: // Track pageviews on checkout pages analytics.subscribe('page_viewed', async (event) => { const loc = event.context.document.location; - + // This "if" condition makes sure only checkout paths are tracked. // The "page_viewed" customer event is also fired for other pages, // but those should be tracked by the global snippet installed in @@ -90,7 +90,7 @@ analytics.subscribe('page_viewed', async (event) => { You can then group all visits to checkout pages into one set of pages in your Plausible dashboard to better analyze your marketing campaigns and performance. -Click on the "**Filter**" button on the top right of your dashboard and then choose "**Page**". Here you can combine URLs to analyze them as one group. Filter by "**contains**" `thank_you` to combine all the purchase confirmations or by "**contains**" `checkouts` to group all the checkouts. +Click on the "**Filter**" button on the top right of your dashboard and then choose "**Page**". Here you can combine URLs to analyze them as one group. Filter by "**contains**" `thank_you` to combine all the purchase confirmations or by "**contains**" `checkouts` to group all the checkouts. Doing this will segment your dashboard by the traffic that went through the checkout process and successfully placed orders. You'll be able to see the referral sources and landing pages that drove the most conversions. You'll also be able to see the location and device details of the buyers too. @@ -100,14 +100,14 @@ If you'd like to see these grouped order confirmations or checkout page visits p ### Track started checkouts -Send a custom event called "**Begin Checkout**" to Plausible every time the checkout process is started. The total price of the shopping cart will be recorded under this event. +Send a custom event called "**Begin Checkout**" to Plausible every time the checkout process is started. The total price of the shopping cart will be recorded under this event. ```javascript // Track started checkouts analytics.subscribe('checkout_started', async (event) => { const amount = event.data.checkout.totalPrice.amount; const currency = event.data.checkout.currencyCode; - + plausible('Begin Checkout', { revenue: {amount: amount, currency: currency}, u: event.context.document.location.href @@ -121,14 +121,14 @@ In order to see this information on your Plausible dashboard, you should: ### Track payment info added during checkout -Send a custom event called "**Add Payment Info**" to Plausible every time payment information is submitted by a customer during the checkout. The total price of the shopping cart will be recorded under this event. +Send a custom event called "**Add Payment Info**" to Plausible every time payment information is submitted by a customer during the checkout. The total price of the shopping cart will be recorded under this event. ```javascript // Track payment info added during checkout analytics.subscribe('payment_info_submitted', async (event) => { const amount = event.data.checkout.totalPrice.amount; const currency = event.data.checkout.currencyCode; - + plausible('Add Payment Info', { revenue: {amount: amount, currency: currency}, u: event.context.document.location.href @@ -142,14 +142,14 @@ In order to see this information on your Plausible dashboard, you should: ### Track completed checkouts (purchases) -Send a custom event called "**Purchase**" to Plausible every time a checkout is completed. The total amount paid by the customer will be recorded under this event. +Send a custom event called "**Purchase**" to Plausible every time a checkout is completed. The total amount paid by the customer will be recorded under this event. ```javascript // Track completed checkouts analytics.subscribe('checkout_completed', async (event) => { const amount = event.data.checkout.totalPrice.amount; const currency = event.data.checkout.currencyCode; - + plausible('Purchase', { revenue: {amount: amount, currency: currency}, u: event.context.document.location.href @@ -250,7 +250,7 @@ The `plausible` function takes two arguments: 1. an event name which can be whatever you like - just make sure to [set up a goal](/custom-event-goals#step-4-create-a-custom-event-goal-in-your-plausible-account) with the same name to see it on your dashboard. 2. an object where a few options can be passed: -* [Object] `revenue` - allows you to attribute a monetary value to your Plausible event. The object needs to contain two keys: `amount` and `currency`. Note that you can only attribute a single monetary value to one event. The revenue option is ignored until you've [set up a revenue goal](ecommerce-revenue-tracking#step-3-add-a-new-custom-event-and-specify-the-currency-of-your-choice) in your Plausible dashboard. That's because currency conversion into your desired reporting currency happens at the time of receiving the event. +* [Object] `revenue` - allows you to attribute a monetary value to your Plausible event. The object needs to contain two keys: `amount` and `currency`. Note that you can only attribute a single monetary value to one event. The revenue option is ignored until you've [set up a revenue goal](ecommerce-revenue-tracking#step-3-add-a-new-custom-event-and-specify-the-currency-of-your-choice) in your Plausible dashboard. That's because currency conversion into your desired reporting currency happens at the time of receiving the event. * [Object] `props` - here you can pass any value under any key you'd like. The key you choose will become the name of the custom property that you need to [configure in your site settings](/custom-props/props-dashboard#1-configure-custom-properties-in-your-site-settings). Note that you are responsible for ensuring that no [personally identifiable information](/custom-props/introduction#personally-identifiable-information) is tracked. * [String] `u` - this field stands for the `url` of the page where this customer event happened. You will most likely want to just keep it the same as in the example. It's important to always pass this option because otherwise the url will become the location of the pixel which has nothing to do with the real location where the event happened. @@ -264,25 +264,17 @@ The `plausible` function takes two arguments: Here's how you can track particular form submissions and button clicks on your Shopify site: -### 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). - -### 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. - -### 3. Find the ID attribute of the form or button you want to track +### 1. Find the ID attribute of the form or button you want to track Your form or button element should have an ID attribute assigned by default. You can find this ID by selecting the element you want to track (do make sure you select your form element and not just the "Submit" button) and clicking on the settings gear. Shopify form ID -### 4. Trigger custom events with JavaScript on your site +### 2. Trigger custom events with JavaScript on your site Here's the code you will need to insert in the `` section of the page where the element ID that you want to track is located. You can do this the same way as you've inserted the Plausible snippet into your site. -Make sure to change the `elementId` line in the code below to include the ID attribute of the element you want to track (`ContactForm` in our example). +Make sure to change the `elementId` line in the code below to include the ID attribute of the element you want to track (`ContactForm` in our example). Also do change the `classes` line to include the goal name in this format: `plausible-event-name=Goal+Name`. The goal name is completely up to you. It's the name under which the goal conversions will appear in your Plausible dashboard. We've used `Form+Submit` goal name in our example. @@ -314,7 +306,7 @@ To represent a space character in goal names, you can use a `+` sign. For exampl Do click on the "**Save**" button to save your changes. -### 5. Create a custom event goal in your Plausible account +### 3. Create a custom event goal in your Plausible account When you send custom events to Plausible, they won't show up in your dashboard automatically. You'll have to configure the goal for the conversion numbers to show up. @@ -328,9 +320,9 @@ So in our example where we added a goal name `plausible-event-name=Form+Submit` Add your custom event goal -Next, click on the "**Add goal**" button and you'll be taken back to the Goals page. +Next, click on the "**Add goal**" button and you'll be taken back to the Goals page. -### 6. Your goal should now be ready and tracking +### 4. Your goal should now be ready and tracking Your goal should now be set up. When you navigate back to your Plausible Analytics dashboard, you should see the number of visitors who triggered the custom event. Goal conversions are listed at the very bottom of the dashboard. The goal will show up in your dashboard as soon as it has been completed at least once. @@ -347,7 +339,7 @@ If you want to trigger multiple custom events on the same site, you don't need t }, { elementId: 'button-ID', - classes: 'plausible-event-name=Button+Click' + classes: 'plausible-event-name=Button+Click' } ] diff --git a/docs/stop-tracking-utm-tags.md b/docs/stop-tracking-utm-tags.md index c315c882..b5b64f14 100644 --- a/docs/stop-tracking-utm-tags.md +++ b/docs/stop-tracking-utm-tags.md @@ -4,53 +4,27 @@ title: Stop tracking UTM tags and other query parameters By default, Plausible strips all query parameters for privacy purposes [except for](top-referrers.md) `ref`, `source`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content` and `utm_term`. If you prefer to stop tracking these parameters as well, please follow these instructions: -## 1. Add the `manual` script extension +## Set `transformRequest` option in `plausible.init` -You should use [our manual script extension](script-extensions.md). To do so, please change your Plausible script snippet `src` attribute from `https://plausible.io/js/script.js` to `https://plausible.io/js/script.manual.js`. +The easiest way to stop tracking parameters is to use `transformRequest` to update the URL property sent to Plausible and prevent the tracking of UTM tag. -The new snippet will look like this (make sure to change the `data-domain` attribute to the domain you added to your Plausible account): +To do so, in your Plausible tracking snippet, add the following: -```html - -``` -Do this on all the pages where you want to stop tracking UTM tags and other query parameters. - -## 2. Trigger the pageview event with a custom `u` attribute - -Once you've started using the manual extension, the `pageview` event won't be sent automatically. This means that the stats won't be tracked anymore by default. You'll have to trigger the events to be counted manually. - -To trigger events manually, you need to add the following script after your regular Plausible tracking snippet: +```javascript +function queryStrippedUrl() { + return location.href.split('?')[0] +} -```html - - -``` - -Once that's done, you can create another script in which you will trigger your pageview event. This is where you can override the URL property sent to Plausible and prevent the tracking of UTM tags. To do so, add the following snippet: - -```html - - -``` +function transformRequest(payload) { + // Sets url for the event manually + payload.u = queryStrippedUrl() + return payload +} -At this point, your entire setup should look like this: - -```html - - - - - +// At the end, update plausible.init call: +plausible.init({ + transformRequest: transformRequest +}) ``` That's it! You're now no longer tracking any UTM tags or other parameters. We will use the [referrer header](top-referrers.md) to display the sources of the traffic instead. If the referring site doesn't send any referrer header, the traffic will fall within the "**Direct / None**" source. diff --git a/docs/top-pages.md b/docs/top-pages.md index 0035ed4f..df8d9181 100644 --- a/docs/top-pages.md +++ b/docs/top-pages.md @@ -53,6 +53,6 @@ Plausible Analytics records the URL path of each page view as the visitors are b * Do you see identical page paths with and without a trailing slash (`/some_article` and `/some_article/`) in your pages report? This points to a duplicate content issue on the site and can be solved [with a 301 redirect](https://ahrefs.com/blog/trailing-slash/) -* If your website is a single-page application with `pushState` routing, Plausible Analytics will track page views automatically with no extra work. If you're using a frontend framework that uses the URL hash for routing, we also have a special [hash-based script](hash-based-routing.md) +* If your website is a single-page application with `pushState` routing, Plausible Analytics will track page views automatically with no extra work. If you're using a frontend framework that uses the URL hash for routing, you can enable [hash-based routing in our script](hash-based-routing.md) P.S. You can learn more about using this information as a site owner [here](https://plausible.io/blog/analyzing-landing-pages#how-to-use-this-information-as-a-site-owner). diff --git a/docs/troubleshoot-integration.md b/docs/troubleshoot-integration.md index 96fd5d18..856fdc94 100644 --- a/docs/troubleshoot-integration.md +++ b/docs/troubleshoot-integration.md @@ -8,7 +8,7 @@ After you've [added the Plausible snippet to your site](plausible-script.md), th If you see the dashboard with graphs and numbers, it means everything is working and we've counted your first visitor. Congrats! Plausible is now tracking your website statistics while preserving the privacy of your visitors. -Do you keep seeing a blinking green dot screen instead of the dashboard? The blinking green dot indicates that we’re listening for incoming visits in real-time but haven't recorded any yet. +Do you keep seeing a blinking green dot screen instead of the dashboard? The blinking green dot indicates that we’re listening for incoming visits in real-time but haven't recorded any yet. Our testing tool will launch automatically from the blinking green dot screen to send test traffic to your site. This test traffic won't be recorded in the dashboard but you'll see a status message indicating whether Plausible Analytics has been installed correctly. @@ -20,35 +20,29 @@ Did our testing tool detect an issue with your integration? Or is there somethin We've put together [many integration guides](integration-guides.md) that cover popular website builders and content management systems (CMS) such as WordPress and Ghost. Thanks to the members of our community, there are also community integrations and plugins for several frameworks such as Hugo and GatsbyJS. These can help you set up and start counting your site visitors in no time. -## Have you added the correct data-domain attribute in the Plausible snippet? - -View the source code of your site. You can right-click anywhere on your page and click "View Page Source" (the wording may be slightly different depending on your web browser). Then press Command+f on a Mac or ctrl+f on Linux and Windows to search. Type "**data-domain**" to search for the Plausible snippet. - -Does the snippet look as expected? Is the data-domain attribute within the snippet an exact match to the site as you've added it to your Plausible account? The data-domain must be an exact match for the stats to be recorded. - ## Have you cleared the cache of your site? If you are using caching on your site, the latest version of your site where our snippet is integrated may not be showing to all your visitors yet. Do purge the cache to ensure that you're presenting the latest version of your site to all your visitors. -## Have you implemented Plausible using Google Tag Manager? +## Have you implemented Plausible using Google Tag Manager? GTM strips the `data-*` attributes by default which can break the tracking. Please follow [our GTM guide](google-tag-manager.md) for instructions on how to integrate Plausible using GTM. -## Does your site use a Content Security Policy (CSP)? +## Does your site use a Content Security Policy (CSP)? If it does, you would need to add our domain name (plausible.io) specifically to the allowed domains list in order for the script to work. [More info here](https://github.com/plausible/docs/issues/20). -## Are you running on localhost? +## Are you running on localhost? -Our script automatically disables itself when running on localhost as most people don't want those stats to be counted. In the `script.js` script, `window.location.hostname` is used to verify that. If you do want to track stats on localhost, you can [use our extension](script-extensions.md). +Our script automatically disables itself when running on localhost as most people don't want those stats to be counted. In the `script.js` script, `window.location.hostname` is used to verify that. If you do want to track stats on localhost, [see configuration guide](script-extensions.md). -## Are you running a Google AMP page? +## Are you running a Google AMP page? To track Google AMP pages with Plausible, you need to declare an AMP-analytics object on your AMP pages. [See the instructions here](https://github.com/plausible/analytics/discussions/220#discussioncomment-904022). ## Did you insert multiple Plausible snippets into your site? -This may affect the accuracy of the tracking and can result in the stats being counted twice. Please make sure to only insert one snippet. +This may affect the accuracy of the tracking and can result in the stats being counted twice. Please make sure to only insert one snippet. ## Are you using an older version of our script? @@ -63,11 +57,11 @@ If you're using [our WordPress plugin](https://plausible.io/wordpress-analytics- This ensures the changes are fully applied and the latest version of our script is properly loaded. -## Has some other plugin altered our snippet? +## Has some other plugin altered our snippet? -Are you using WP Rocket, SiteGround Optimizer or other performance optimization plugins? Or some type of consent banner plugin that determines which scripts can run when? These plugins may affect our tracking as they try to optimize our script. If you're on WordPress, we recommend you use [our official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) to avoid these issues as we've built-in resolutions to the most common plugin conflicts. +Are you using WP Rocket, SiteGround Optimizer or other performance optimization plugins? Or some type of consent banner plugin that determines which scripts can run when? These plugins may affect our tracking as they try to optimize our script. If you're on WordPress, we recommend you use [our official WordPress plugin](https://plausible.io/wordpress-analytics-plugin) to avoid these issues as we've built-in resolutions to the most common plugin conflicts. -Do you experience an issue even when using our plugin? Do check your integration manually using the steps below to identify which plugin is in question. Then please whitelist our script location and our domain name in the settings of the individual plugin to stop it from altering our snippet. +Do you experience an issue even when using our plugin? Do check your integration manually using the steps below to identify which plugin is in question. Then please whitelist our script location and our domain name in the settings of the individual plugin to stop it from altering our snippet. ## Have you placed our script behind the GDPR consent banner? @@ -117,9 +111,9 @@ In some cases, our automated testing tool may not be able to check your site. In A simple way to verify if Plausible is working is to view the source code of your site and look for the Plausible snippet. Here's how: -1. Visit your home page or any other page on your site where Plausible is installed. -2. View the source code of your site. You can right-click anywhere on your page and click "**View Page Source**" (the wording may be slightly different depending on your web browser). Alternatively, use a keyboard shortcut to view the source code (`Option+Command+u` on a Mac or `ctrl+u` on Linux and Windows). -3. Press `Command+f` on a Mac or `ctrl+f` on Linux and Windows to search the source code. Type `data-domain` to search for the Plausible snippet. +1. Visit your home page or any other page on your site where Plausible is installed. +2. View the source code of your site. You can right-click anywhere on your page and click "**View Page Source**" (the wording may be slightly different depending on your web browser). Alternatively, use a keyboard shortcut to view the source code (`Option+Command+u` on a Mac or `ctrl+u` on Linux and Windows). +3. Press `Command+f` on a Mac or `ctrl+f` on Linux and Windows to search the source code. Type `plausible.initp` to search for the Plausible snippet. 4. Do you see our snippet? Ensure that the snippet is correct and that there are no unintended modifications compared to the snippet we provided you with. If you see our snippet in your source code and it is exactly the same snippet as the one we provided, it means Plausible is installed. @@ -130,10 +124,10 @@ If you see our snippet in your source code and it is exactly the same snippet as You can also use your browser's developer tools to look for the Plausible script or any errors related to your Plausible integration. -1. Visit your home page or any other page on your site where Plausible is installed. +1. Visit your home page or any other page on your site where Plausible is installed. 2. Right-click anywhere on your page and click "**Inspect**" (the wording may vary depending on your web browser) to open the developer tools. Alternatively, press the key `F12` on Firefox or Chrome or `Option+Command+i` on Safari. 3. Look into the "**Console**" tab in the developer tools for any errors related to Plausible. It may give you some insights into what's going on through the error code it provides. If you see an error related to the Plausible script, it means that something's not right with your implementation. -4. Then click on the "**Network**" tab in the developer tools. It will be empty, so you would need to reload your page. After you refresh the page, you will start seeing some data in the "**Network**" tab. You should see the `script.js` script from the Plausible domain `plausible.io` in the list. The Plausible script should display status 200. +4. Then click on the "**Network**" tab in the developer tools. It will be empty, so you would need to reload your page. After you refresh the page, you will start seeing some data in the "**Network**" tab. You should see the a script from the Plausible domain `plausible.io` in the list, starting with `s-`. The Plausible script should display status 200. Ensure that the Plausible Analytics script is loading in the 'Network' tab diff --git a/docs/webflow-integration.md b/docs/webflow-integration.md index 7f568e3f..7e5a341b 100644 --- a/docs/webflow-integration.md +++ b/docs/webflow-integration.md @@ -6,7 +6,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; Here's how to add Plausible Analytics to your Webflow site and set up the tracking of custom events such as button clicks and form submissions. -## How to add Plausible to your Webflow website +## How to add Plausible to your Webflow website * On your project's page, click on the Webflow logo ("**W**") in the left-hand side menu and choose "**Project Settings**". @@ -56,25 +56,17 @@ Your goal should now be set up. When you navigate back to your Plausible Analyti ## Tracking button clicks and other links on your Webflow site -### 1. Enable "Custom events" for your site +### 1. Set an ID to the element you want to track -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). - -### 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. We display your snippet during the process of adding a new site to your account. You can also see the snippet within the "**Site Installation**" area of the "**General** section in your [site settings](website-settings.md). - -### 3. Set an ID to the element you want to track - -In Webflow, link and button elements don't have a default ID. You'll need to assign an ID by selecting the element and clicking on the settings gear. In the **"Designer View"**, you'll be able to set the ID. +In Webflow, link and button elements don't have a default ID. You'll need to assign an ID by selecting the element and clicking on the settings gear. In the **"Designer View"**, you'll be able to set the ID. Add an ID to link and button elements in Webflow -### 4. Trigger custom events with JavaScript on your site +### 2. Trigger custom events with JavaScript on your site Here's the code you will need to insert in the `` section of the page where the element ID that you want to track is located. You can use the "**Custom Code**" feature to do this similarly to how you've inserted the Plausible snippet into your site. -Make sure to change the `elementId` line in the code below to include the ID attribute of the element you want to track (`button-click` in our example). +Make sure to change the `elementId` line in the code below to include the ID attribute of the element you want to track (`button-click` in our example). Also do change the `classes` line to include the goal name in this format: `plausible-event-name=Goal+Name`. The goal name is completely up to you. It's the name under which the goal conversions will appear in your Plausible dashboard. We've used `Button+Click` goal name in our example. @@ -106,11 +98,11 @@ For example: `plausible-event-name=Form+Submit` will display as `Form Submit` in Do click on the "**Save Changes**" button and then "**Publish**" your changes. -### 5. Create a custom event goal in your Plausible account +### 3. Create a custom event goal in your Plausible account When you send custom events to Plausible, they won't show up in your dashboard automatically. You'll have to configure the goal for the conversion numbers to show up. -To configure a goal, go to [your website's settings](website-settings.md) in your Plausible account and visit the "**Goals**" section. +To configure a goal, go to [your website's settings](website-settings.md) in your Plausible account and visit the "**Goals**" section. Click on the "**+ Add goal**" button to go to the goal creation form. Select `Custom event` as the goal trigger and enter the name of the custom event you are triggering. The name must be an exact match to the one you added to your site for the conversions to show up in your dashboard. @@ -118,9 +110,9 @@ So in our example where we added a goal name `plausible-event-name=Button+Click` Add your custom event goal -Next, click on the "**Add goal**" button and you'll be taken back to the Goals page. +Next, click on the "**Add goal**" button and you'll be taken back to the Goals page. -### 6. Your goal should now be ready and tracking +### 4. Your goal should now be ready and tracking Your goal should now be set up. When you navigate back to your Plausible Analytics dashboard, you should see the number of visitors who triggered the custom event. Goal conversions are listed at the very bottom of the dashboard. The goal will show up in your dashboard as soon as it has been completed at least once. @@ -133,11 +125,11 @@ If you want to trigger multiple custom events on the same site, you don't need t var toTag = [ { elementId: 'link-click', - classes: 'plausible-event-name=Link+Click' + classes: 'plausible-event-name=Link+Click' }, { elementId: 'button-click', - classes: 'plausible-event-name=Button+Click' + classes: 'plausible-event-name=Button+Click' } ] diff --git a/static/img/onboarding-enable-custom-events-tracking.png b/static/img/onboarding-enable-custom-events-tracking.png deleted file mode 100644 index 7e4d2653..00000000 Binary files a/static/img/onboarding-enable-custom-events-tracking.png and /dev/null differ diff --git a/static/img/onboarding-enable-custom-props.png b/static/img/onboarding-enable-custom-props.png deleted file mode 100644 index d93e7e27..00000000 Binary files a/static/img/onboarding-enable-custom-props.png and /dev/null differ diff --git a/static/img/onboarding-enable-hash-based-tracking.png b/static/img/onboarding-enable-hash-based-tracking.png deleted file mode 100644 index 4060585f..00000000 Binary files a/static/img/onboarding-enable-hash-based-tracking.png and /dev/null differ diff --git a/static/img/onboarding-enable-revenue-tracking.png b/static/img/onboarding-enable-revenue-tracking.png deleted file mode 100644 index 9be69b0a..00000000 Binary files a/static/img/onboarding-enable-revenue-tracking.png and /dev/null differ