Skip to content

Commit 146029a

Browse files
macoboapataukutaht
authored
WIP: Scriptv2 docs (#614)
* Update hash-based-routing reference in top-pages.md * Update plausible-script.md * Update custom events/custom props goals, removing snippet upgrade section * Link to upgrade guide in custom properties docs * Update hash-based-routing docs * Update custom-event-goals.md - add more information on tracking * Mostly complete update guide * Remove a now-invalid section from script-extensions.md * Update integration-guides wording * Update docs/custom-automatic-link-tracking.md * Update docs/file-downloads-tracking.md * Update docs/error-pages-tracking-404.md * Update docs/ecommerce-revenue-tracking.md, remove unneeded screenshot * Update docs/webflow-integration.md * docs/stop-tracking-utm-tags.md via transformRequest * docs/file-downloads-tracking.md * Rewrite docs/custom-locations.md * Update docs/custom-locations.md * Update docs/custom-query-params.md * Update hash-based-routing docs * Remove mentions of rollup * Update references * Update references * Update docs/custom-automatic-link-tracking.md code for custom link tracking * Remove mention of delay from custom event goals * Rewrite docs/script-extensions.md * Remove redundant instructions from docs/outbound-link-click-tracking.md * Add documentation on form submissions * Update docs/shopify-integration.md * Update troubleshoot-integration.md * Update s- -> pa- * Update docs for sites API * Mention NPM library in plausible-script.md * Enhance 404 tracking docs * Add note on svg elements * Rewrite apache guide * Updated cloudflare instructions * Update vercel guide * Update Caddy guide * Update Fresh guide * Fix vercel guide * Update Nginx guide * Deprecate some guides * Update proxy introduction.md * Update carrd guide * Rewrite GTM template guide * Add a note on google tag manager upgrade guide * Update discourse guide * Update outbound link wording * Remove redundant TODO * Typo * Update cloudflare docs * Typo * Add warnings to custom locations * Reduce cache time * Inform user that href is stored in full * Fix form submission page, update link to /form-submissions-tracking --------- Co-authored-by: Artur Pata <[email protected]> Co-authored-by: Uku Taht <[email protected]>
1 parent 431a760 commit 146029a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+867
-1366
lines changed

‎docs/carrd-integration.md‎

Lines changed: 20 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -4,31 +4,29 @@ title: Adding Plausible to Carrd (and tracking custom events)
44

55
import useBaseUrl from '@docusaurus/useBaseUrl';
66

7-
Here's how to add Plausible Analytics to your Carrd site and set up the tracking of custom events such as button clicks and form submissions.
7+
Here's how to add Plausible Analytics to your Carrd site and set up the tracking of custom events such as button clicks.
88

9-
## How to add Plausible to your Carrd website
9+
## How to add Plausible to your Carrd website
1010

11-
### Enable "Hashed page paths" for your site in your Plausible account
11+
### Get your site snippet
1212

13-
Carrd is a one-page website builder that doesn't support normal navigation. This means that 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).
14-
15-
<img alt="Enable hashed page paths tracking during onboarding" src={useBaseUrl('img/onboarding-enable-hash-based-tracking.png')} />
16-
17-
Plausible 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.
13+
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).
1814

1915
### Go to your Carrd website editor
2016

2117
* Go to the editor of your Carrd website and add an "**Embed**" component.
2218

2319
<img alt="Add embed element to Carrd" src={useBaseUrl('img/add-embed-element-to-carrd.png')} />
2420

25-
* In the element's settings make sure:
21+
* In the element's settings make sure:
2622

2723
- Type is set to "**Code**"
2824
- Style is set to "**Hidden**" and "**Head**"
2925

3026
* Then paste your Plausible tracking script in the **Code** field
3127

28+
* In the snippet, update `plausible.init()` to `plausible.init({ hashBasedRouting: true })`. This allows plausible to track hashed page paths that Carrd uses during navigation.
29+
3230
* Do click on the "**Done**" button and then "**Publish**" your changes. After you change the tracking snippet on your site, all the hash-based page paths on your Carrd website will start being tracked and will be displayed in the "**Top Pages**" report of your Plausible Analytics dashboard.
3331

3432
<img alt="Add Plausible Analytics script to Carrd" src={useBaseUrl('img/add-plausible-script-to-carrd.png')} />
@@ -41,97 +39,25 @@ Now you can go to your Carrd website and verify that Plausible script has been a
4139
As an alternative to custom events, check out [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.
4240
:::
4341

44-
### 1. Enable "Custom events" for your site
45-
46-
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).
47-
48-
### 2. Change the snippet on your site
49-
50-
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).
51-
52-
### 3. Trigger custom events with JavaScript on your site
53-
54-
Here's the code you will need to insert in the `<head>` 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.
55-
56-
Make sure to change the `elementId` line in the code below to include the ID attribute of the element you want to track (`form01` in our example). In Carrd forms have default IDs. Usually they're assigned IDs based on the order you've added them. If you only have one form on the page it has an ID of "**form01**". If you're on a higher plan, like Pro Plus, you'll be able to set these IDs yourself from the element's settings.
57-
58-
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.
59-
60-
:::tip To represent a space character in goal names, you can use a `+` sign
61-
For example: `plausible-event-name=Form+Submit` will display as `Form Submit` in your Plausible dashboard
62-
:::
63-
64-
```html
65-
<script>
66-
var toTag = [
67-
{
68-
elementId: 'form01',
69-
classes: 'plausible-event-name=Form+Submit'
70-
}
71-
]
72-
73-
document.addEventListener('DOMContentLoaded', function (_e) {
74-
toTag.forEach(function (tagObject) {
75-
var element = document.getElementById(tagObject.elementId)
76-
tagObject.classes.split(' ').forEach(function (className) {
77-
if (element) { element.classList.add(className) }
78-
})
79-
})
80-
})
81-
</script>
82-
```
83-
84-
<img alt="Modify Plausible script Carrd for form tracking" src={useBaseUrl('img/track-form-submissions-carrd.png')} />
85-
86-
Now you'll have to click on the form element to select it, click on the gear icon to access the form settings and then on "**Events**" tab. Add the same script as above in the "**On Success**" event box
87-
88-
```html
89-
<script>
90-
var toTag = [
91-
{
92-
elementId: 'form01',
93-
classes: 'plausible-event-name=Form+Submit'
94-
}
95-
]
96-
97-
document.addEventListener('DOMContentLoaded', function (_e) {
98-
toTag.forEach(function (tagObject) {
99-
var element = document.getElementById(tagObject.elementId)
100-
tagObject.classes.split(' ').forEach(function (className) {
101-
if (element) { element.classList.add(className) }
102-
})
103-
})
104-
})
105-
</script>
106-
```
107-
108-
<img alt="On success form tracking in Carrd" src={useBaseUrl('img/track-form-submissions-submit-carrd.png')} />
42+
You can enable form submission 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).
10943

11044
## Tracking button clicks and other links on your Carrd site
11145

112-
### 1. Enable "Custom events" for your site
113-
114-
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).
115-
116-
### 2. Change the snippet on your site
46+
### 1. Set an ID to the element you want to track
11747

118-
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).
48+
In Carrd buttons and links have default IDs. Usually they're assigned IDs based on the order you've added them. So first button or link has an ID of "**buttons01**"/"**links01**", second button or link has an ID of "**buttons02**"/"**links02**" and so on and so forth.
11949

120-
### 3. Set an ID to the element you want to track
50+
If you're on a higher plan, like Pro Plus, you'll be able to set these IDs yourself from the element's settings.
12151

122-
In Carrd buttons and links have default IDs. Usually they're assigned IDs based on the order you've added them. So first button or link has an ID of "**buttons01**"/"**links01**", second button or link has an ID of "**buttons02**"/"**links02**" and so on and so forth.
123-
124-
If you're on a higher plan, like Pro Plus, you'll be able to set these IDs yourself from the element's settings.
125-
126-
To be sure of your element's ID, you can use your browser's dev tool to inspect the element.
52+
To be sure of your element's ID, you can use your browser's dev tool to inspect the element.
12753

12854
<img alt="Confirm element ID in Carrd" src={useBaseUrl('img/confirm-element-id-carrd.png')} />
12955

130-
### 4. Trigger custom events with JavaScript on your site
56+
### 2. Trigger custom events with JavaScript on your site
13157

13258
Here's the code you will need to insert in the `<head>` 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.
13359

134-
Make sure to change the `elementId` line in the code below to include the ID attribute of the element you want to track (`buttons01` in our example).
60+
Make sure to change the `elementId` line in the code below to include the ID attribute of the element you want to track (`buttons01` in our example).
13561

13662
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.
13763

@@ -159,21 +85,21 @@ Also do change the `classes` line to include the goal name in this format: `plau
15985

16086
Do click on the "**Save Changes**" button and then "**Publish**" your changes.
16187

162-
### 5. Create a custom event goal in your Plausible account
88+
### 3. Create a custom event goal in your Plausible account
16389

16490
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.
16591

166-
To configure a goal, go to [your website's settings](website-settings.md) in your Plausible account and visit the "**Goals**" section.
92+
To configure a goal, go to [your website's settings](website-settings.md) in your Plausible account and visit the "**Goals**" section.
16793

16894
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.
16995

17096
So in our example where we added a goal name `plausible-event-name=Button+Click` to the Carrd site, the goal to add in the Plausible account is `Button Click` (plus is replaced by a space).
17197

17298
<img alt="Add your custom event goal" src={useBaseUrl('img/button-click-custom-event-goal-carrd.png')} />
17399

174-
Next, click on the "**Add goal**" button and you'll be taken back to the Goals page.
100+
Next, click on the "**Add goal**" button and you'll be taken back to the Goals page.
175101

176-
### 6. Your goal should now be ready and tracking
102+
### 4. Your goal should now be ready and tracking
177103

178104
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.
179105

@@ -186,11 +112,11 @@ If you want to trigger multiple custom events on the same site, you don't need t
186112
var toTag = [
187113
{
188114
elementId: 'buttons01',
189-
classes: 'plausible-event-name=Button+Click'
115+
classes: 'plausible-event-name=Button+Click'
190116
},
191117
{
192118
elementId: 'links01',
193-
classes: 'plausible-event-name=Link+Click'
119+
classes: 'plausible-event-name=Link+Click'
194120
}
195121
]
196122

‎docs/custom-automatic-link-tracking.md‎

Lines changed: 5 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -10,25 +10,17 @@ If you track link clicks, then these count towards your billable monthly pagevie
1010

1111
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.
1212

13-
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`.
13+
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`.
1414

1515
Instructions below can be used to start tracking every `<a>` (i.e. link) element on your site with some specified rules. It's very similar to our automated tracking of [outbound link clicks](outbound-link-click-tracking.md) and [file downloads](file-downloads-tracking.md) but you can choose based on the link URL (`href` attribute) which links to track.
1616

1717
Here's how to automatically track clicks on cloaked affiliate links and other pretty URLs:
1818

19-
:::tip Our WordPress plugin can track cloaked affiliate links automatically
19+
:::tip Our WordPress plugin can track cloaked affiliate links automatically
2020
On WordPress? Check out our WordPress plugin which can track cloaked affiliate links automatically. [See more here](https://plausible.io/wordpress-analytics-plugin).
2121
:::
2222

23-
## 1. Trigger custom events with JavaScript on your site
24-
25-
First, make sure your tracking setup includes the second line as shown below:
26-
27-
```html
28-
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>
29-
<script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>
30-
```
31-
## 2. Add the JavaScript that will be sending the link click events to Plausible
23+
## 1. Add the JavaScript that will be sending the link click events to Plausible
3224

3325
You need to add the following code to all of the pages where you want to track your links. You should insert the code below into your HTML page `<head>` section just under the custom event snippet.
3426

@@ -43,15 +35,6 @@ On the line that says `var toBeTracked = '/go/'` change `/go/` to what you want
4335
return link
4436
}
4537
46-
function shouldFollowLink(event, link) {
47-
// If default has been prevented by an external script, Plausible should not intercept navigation.
48-
if (event.defaultPrevented) { return false }
49-
50-
var targetsCurrentWindow = !link.target || link.target.match(/^_(self|parent|top)$/i)
51-
var isRegularClick = !(event.ctrlKey || event.metaKey || event.shiftKey) && event.type === 'click'
52-
return targetsCurrentWindow && isRegularClick
53-
}
54-
5538
var MIDDLE_MOUSE_BUTTON = 1
5639
5740
function handleLinkClick(event) {
@@ -62,26 +45,7 @@ On the line that says `var toBeTracked = '/go/'` change `/go/` to what you want
6245
if (link && shouldTrackLink(link)) {
6346
var eventName = 'Cloaked Link: Click'
6447
var eventProps = { url: link.href }
65-
return sendLinkClickEvent(event, link, eventName, eventProps)
66-
}
67-
}
68-
69-
function sendLinkClickEvent(event, link, eventName, eventProps) {
70-
var followedLink = false
71-
72-
function followLink() {
73-
if (!followedLink) {
74-
followedLink = true
75-
window.location = link.href
76-
}
77-
}
78-
79-
if (shouldFollowLink(event, link)) {
8048
plausible(eventName, { props: eventProps, callback: followLink })
81-
setTimeout(followLink, 5000)
82-
event.preventDefault()
83-
} else {
84-
plausible(eventName, { props: eventProps })
8549
}
8650
}
8751
@@ -109,7 +73,7 @@ If simply containing a substring is not enough to differentiate between links yo
10973

11074
where `\/` stands for a forward slash (escaped with `\`) and `.*` will match any (or empty) string in the middle. It will basically match anything that contains the format `products/<anything>/details`.
11175

112-
## 3. Create a custom event goal in your Plausible Analytics account
76+
## 2. Create a custom event goal in your Plausible Analytics account
11377

11478
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.
11579

@@ -119,6 +83,6 @@ Click on the "**+ Add goal**" button to go to the goal creation form.
11983

12084
Select `Custom event` as the goal trigger and enter this exact name: `Cloaked Link: Click`.
12185

122-
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.
86+
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.
12387

12488
That's it. You're now tracking all link clicks on your site with custom URL matching rules!

0 commit comments

Comments
 (0)