Skip to content

Commit 95b8ff3

Browse files
macobomacobo
committed
Rewrite GTM template guide
1 parent 07fc413 commit 95b8ff3

File tree

1 file changed

+28
-148
lines changed

1 file changed

+28
-148
lines changed

‎docs/google-tag-manager.md

Lines changed: 28 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,164 +1,44 @@
11
---
22
title: How to add the script to your site using Google Tag Manager
33
---
4+
This document walks through how you can set up Plausible Analytics using Google Tag Manager.
45

5-
import useBaseUrl from '@docusaurus/useBaseUrl';
6+
## Google Tag Manager Template
67

7-
You can use "**Google Tag Manager**" to add Plausible Analytics tracking code to your website.
8+
In order to make the process easier, we have published a template that makes setting up Plausible Analytics with Google Tag Manager simple and code free. (You can find the source code for the Google Tag Manager template used [here](https://github.com/plausible/plausible-gtm-template))
89

9-
* In your Google Tag Manager account, add a new tag
10-
11-
<img alt="Add new tag" src={useBaseUrl('img/add-new-tag.png')} />
10+
The simplest way to install the custom template is to locate it in the [Google Tag Manager template gallery](https://tagmanager.google.com/gallery/#/) where you can install it directly from your Google Tag Manager dashboard.
1211

13-
* Edit the tag configuration
12+
Once you’ve installed the template, you should create a new Tag that uses it. To do this:
13+
* In the main Google Tag Manager dashboard, browse to Tags and click New to create a new tag
14+
* From the list of available tag templates, choose the Plausible Analytics tag template you just installed
15+
* The only mandatory field in the tag configuration is the Script ID that can be found in the Plausible Analytics dashboard under Site Settings > Site Installation > Google Tag Manager (other optional configuration options are described below in the section Tag Configuration)
16+
* For the tag trigger, you should select All Pages - Page View, which will ensure that Plausible will capture data on all pages
1417

15-
<img alt="Choose tag type" src={useBaseUrl('img/choose-type-to-begin.png')} />
18+
## Tag Configuration
1619

17-
* Choose "**Custom HTML**" for the tag type
18-
19-
<img alt="HTML tag" src={useBaseUrl('img/custom-html-tag.png')} />
20+
The tag has the following optional configuration options:
2021

21-
* Paste your Plausible JavaScript tracking snippet in the "**HTML**" field within the "**Custom HTML**" section. Do note that Plausible will automatically detect that you're using Google Tag Manager and will present you a GTM-dedicated snippet that you need to use. We will display your snippet during the process of adding a new site to your account. If you've already added the site to your Plausible account, you can see the snippet within the "**Site Installation**" area of the "**General** section in your [site settings](website-settings.md).
22+
| **Optional Configuration** | **Explanation** |
23+
|---------------------------|-----------------|
24+
| **File Downloads** | Automatically [track file downloads](/docs/file-downloads-tracking) (enabled by default) |
25+
| **Form Submissions** | Whether to [track form submissions](/docs/form-submission-tracking.md) (enabled by default) |
26+
| **Outbound Links** | Automatically [track clicks on outbound links](/docs/outbound-link-click-tracking) (enabled by default) |
27+
| **Hash Based Routing** | Automatically track page paths that use a `#` in the URL, [described here](/docs/hash-based-routing) (disabled by default) |
28+
| **Custom Properties** | Allows you to attach [custom properties](/docs/custom-props/introduction) (also known as custom dimensions in Google Analytics) when sending a pageview event. These can be configured using Google Tag Manager variables. |
2229

23-
<img alt="Paste Plausible script" src={useBaseUrl('img/paste-plausible-script.png')} />
30+
<details>
31+
<summary>Advanced configuration options</summary>
2432

25-
* After pasting the snippet, add a trigger to make this tag fire
33+
| **Optional Configuration** | **Explanation** |
34+
|---------------------------|-----------------|
35+
| **Auto Capture Pageviews** | Whether to automatically capture pageviews (enabled by default) |
36+
| **Capture on Localhost** | Whether to capture events on localhost (disabled by default) |
37+
| **Logging** | Whether to log to console on ignored events (enabled by default) |
2638

27-
<img alt="trigger to fire script" src={useBaseUrl('img/add-tag-trigger.png')} />
2839

29-
* Select the "**All Pages**" and filter "**Page View**" as the trigger if you want to count all your pages
30-
31-
<img alt="Tag trigger" src={useBaseUrl('img/trigger-tag.png')} />
40+
</details>
3241

33-
:::note
34-
Be careful about extras you enable such as tag firing priority, tag sequencing, consent checks etc as they all may affect when and how our script loads
35-
:::
42+
## Troubleshooting
3643

37-
* Give your tag a name
38-
39-
<img alt="Name tag" src={useBaseUrl('img/name-your-tag.png')} />
40-
41-
* Click on the "**Save**" button
42-
43-
* Click "**Submit**" to submit your changes
44-
45-
* Then click on the "**Publish**" button
46-
47-
That's it! Now you can go to your website and verify whether Plausible Analytics script has been added and to your Plausible Analytics account to see whether the stats are being tracked. See here [how to verify the integration](troubleshoot-integration.md).
48-
49-
## Track 404 error pages
50-
51-
* 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). After you enable 404 error pages tracking, we will automatically add a new goal called `404` to your site
52-
53-
<img alt="Enable 404 tracking during onboarding" src={useBaseUrl('img/onboarding-enable-404-tracking.png')} />
54-
55-
* The tracking snippet will change after your selection of "**404 error pages**" as an optional measurement. Do ensure to paste the newest snippet into your "**Custom HTML**" tag for all tracking to work as expected
56-
57-
* Create a new GTM Variable
58-
59-
<img alt="Create new GTM Variable " src={useBaseUrl('img/GTM-create-new-variable.png')} />
60-
61-
* Name the new variable "**Page Not Found**" and set the type to "**Custom JavaScript**"
62-
63-
<img alt="New GTM variable name and type" src={useBaseUrl('img/GTM-variable-name-and-type.png')} />
64-
65-
* Create a new GTM Trigger
66-
67-
<img alt="Create new GTM trigger" src={useBaseUrl('img/GTM-create-trigger.png')} />
68-
69-
* Name the new trigger "**Page Not Found Trigger**" and set the type to "**Page View**" and "**DOM Ready**"
70-
71-
<img alt="New GTM trigger name and type" src={useBaseUrl('img/GTM-trigger-name-and-type.png')} />
72-
73-
* Add the following function to the trigger's field
74-
75-
```javascript
76-
function() {
77-
return typeof pageNotFound === 'undefined' ? 0 : pageNotFound;
78-
}
79-
```
80-
81-
<img alt="New GTM trigger code" src={useBaseUrl('img/GTM-variable-code.png')} />
82-
83-
* Make sure that the "**Page Not Found Trigger**" only fires on "**Some DOM Ready Events**" where "**Page Not Found**" variable is "**greater than equal to 1**"
84-
85-
<img alt="New GTM trigger references" src={useBaseUrl('img/GTM-trigger-fire.png')} />
86-
87-
* Add the following line within the `body` section of your website's 404 page template. For instance, if you're using WordPress, your 404 page template will be called `404.php` and it will be located within your theme files
88-
89-
```javascript
90-
<script type="text/javascript">
91-
var pageNotFound = true;
92-
</script>
93-
```
94-
95-
5. Create a new GTM Tag called "**Page Not Found Tag**" of type "**Custom HTML**" and paste the following code:
96-
97-
```javascript
98-
<script type="text/javascript">window.plausible("404");</script>
99-
```
100-
101-
6. Publish all changes.
102-
103-
## Track custom events
104-
105-
* 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)
106-
107-
* The tracking snippet will change after your selection of "**Custom events**" as an optional measurement. Do ensure to paste the newest snippet into your "**Custom HTML**" tag for all tracking to work as expected
108-
109-
* You then need to tag individual elements of your site by following our [custom events guide](custom-event-goals.md).
110-
111-
## Track custom properties
112-
113-
* 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)
114-
115-
* The tracking snippet will change after your selection of "**Custom properties**" as an optional measurement. Do ensure to paste the newest snippet into your "**Custom HTML**" tag for all tracking to work as expected
116-
117-
* To track custom properties on the pageview level, you need to manually change your Plausible snippet to send the properties using the `script.setAttribute`
118-
119-
```html
120-
<script>
121-
var script = document.createElement('script');
122-
script.defer = true;
123-
script.dataset.domain = "yourdomain.com";
124-
script.dataset.api = "https://plausible.io/api/event";
125-
script.src = "https://plausible.io/js/script.pageview-props.js";
126-
127-
script.setAttribute("event-author", "John Doe");
128-
script.setAttribute("event-logged_in", "true");
129-
// ... add a new line like above for each property
130-
131-
document.getElementsByTagName('head')[0].appendChild(script);
132-
</script>
133-
```
134-
135-
For more details on custom properties, do check out the [custom properties guide](custom-props/introduction.md).
136-
137-
## Plausible containers for Google Tag Manager
138-
139-
If you prefer to get up and running with Plausible as quickly as possible, we have two Google Tag Manager containers that require minimal edits. Do right click the links below to download the linked files:
140-
141-
- [Plausible Integration](https://raw.githubusercontent.com/plausible/docs/master/static/files/Plausible-GTM-Integration.json) - For the default tracking snippet
142-
- [Plausible Full Integration](https://raw.githubusercontent.com/plausible/docs/master/static/files/Plausible-GTM-full-integration.json) - For tracking snippet that includes our optional enhanced measurements, custom properties and 404 error page tracking
143-
144-
### How to import Plausible's GTM containers
145-
146-
* Navigate to the **Admin** section of your container's workspace
147-
148-
<img alt="GTM admin" src={useBaseUrl('img/GTM-admin.png')} />
149-
150-
* Click on **Import Container**
151-
152-
<img alt="GTM import container" src={useBaseUrl('img/GTM-import-container.png')} />
153-
154-
* Select the downloaded .json file we provided and make sure to select **merge**
155-
156-
<img alt="Select container and merge" src={useBaseUrl('img/GTM-import-merge-container.png')} />
157-
158-
* If you chose the default tracking snippet container, make sure to edit the new Plausible Analytics tag and change **yourdomain.com** to the name of your dashboard
159-
160-
<img alt="GTM container change domain" src={useBaseUrl('img/GTM-change-domain.png')} />
161-
162-
* If you chose the full integration container that includes our optional enhanced measurements, make sure to change **yourdomain.com** to the name of your dashboard as well as to delete the script extensions that you don't need and to add the custom properties that you'd like to track as described above
163-
164-
<img alt="GTM container change domain extensions and props" src={useBaseUrl('img/GTM-change-domain-extensions-props.png')} />
44+
You can test that everything is working as expected by using Google Tag Manager’s Preview mode. You can enter Preview mode by clicking the blue Preview button in the Google Tag Manager dashboard. This opens a new tab with your website running the GTM container where you can see if Plausible Analytics is running and capturing data properly. In the Tag Assistant Preview tab, you can see additional information about the events that trigger the tag and the data that is being sent.

0 commit comments

Comments
 (0)