Skip to content

Commit bd0b211

Browse files
johannschopplichjohannschopplich
committed
feat: tracking of outbound links, file downloads, and form submissions (closes #41)
1 parent 6630636 commit bd0b211

File tree

1 file changed

+65
-30
lines changed

1 file changed

+65
-30
lines changed

‎README.md‎

Lines changed: 65 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,14 @@
44

55
[![npm version](https://img.shields.io/npm/v/@nuxtjs/plausible?color=a1b858&label=)](https://www.npmjs.com/package/@nuxtjs/plausible)
66

7-
Native integration of [Plausible Analytics](https://plausible.io/sites) for [Nuxt](https://nuxt.com).
7+
Native integration of [Plausible Analytics](https://plausible.io) for [Nuxt](https://nuxt.com).
88

99
## Features
1010

1111
- 🌻 No configuration necessary
1212
- 📯 Track events and page views manually with [composables](#composables)
13-
- 🔀 Optional API proxy to avoid ad-blockers
13+
- 📊 Automatic tracking of outbound links, file downloads, and form submissions
14+
- 🔀 Optional API proxy to avoid ad blockers
1415
- 📂 [`.env` file support](#configuration)
1516
- 🧺 Sensible default options
1617
- 🦾 SSR-ready
@@ -35,7 +36,7 @@ export default defineNuxtConfig({
3536
Done! Plausible will now run in your application's client.
3637

3738
> [!TIP]
38-
> By default, `@nuxtjs/plausible` will use `window.location.hostname` for the Plausible `domain` configuration key, which should suit most use-cases. If you need to customize the domain, you can do so in the [module options](#module-options).
39+
> By default, `@nuxtjs/plausible` will use `window.location.hostname` for the Plausible `domain` configuration key, which should suit most use cases. If you need to customize the domain, you can do so in the [module options](#module-options).
3940
4041
## Configuration
4142

@@ -68,9 +69,9 @@ With this setup, you can omit the `plausible` key in your Nuxt configuration.
6869

6970
### Proxy Configuration
7071

71-
The module provides a proxy API feature that allows you to route Plausible events through your Nitro server instead of sending them directly to Plausible's servers. This is useful if you want to prevent ad blockers from blocking requests to Plausible's domain. When proxy is enabled, the tracker will automatically route requests through the current origin.
72+
The module provides a proxy feature that routes Plausible events through your Nitro server instead of sending them directly to Plausible's servers. This is useful to prevent ad blockers from blocking requests to Plausible's domain.
7273

73-
To enable the proxy API, set the `proxy` option to `true`:
74+
To enable the proxy, set the `proxy` option to `true`:
7475

7576
```ts
7677
export default defineNuxtConfig({
@@ -85,28 +86,61 @@ export default defineNuxtConfig({
8586
> [!NOTE]
8687
> When enabled, all Plausible events will be sent to your server first, which then forwards them to Plausible's API. The default proxy endpoint is `/_plausible`, but you can customize the path using the `proxyBaseEndpoint` module option.
8788
89+
### Enhanced Tracking
90+
91+
The module supports automatic tracking of outbound link clicks, file downloads, and form submissions – all powered by the [official Plausible tracker](https://github.com/plausible/analytics/tree/master/tracker).
92+
93+
```ts
94+
export default defineNuxtConfig({
95+
modules: ['@nuxtjs/plausible'],
96+
97+
plausible: {
98+
autoOutboundTracking: true,
99+
fileDownloads: true,
100+
formSubmissions: true,
101+
},
102+
})
103+
```
104+
105+
By default, file download tracking covers common file types (pdf, xlsx, docx, zip, etc.). You can customize which file extensions are tracked:
106+
107+
```ts
108+
export default defineNuxtConfig({
109+
modules: ['@nuxtjs/plausible'],
110+
111+
plausible: {
112+
fileDownloads: { fileExtensions: ['pdf', 'zip', 'csv'] },
113+
},
114+
})
115+
```
116+
117+
> [!NOTE]
118+
> These features require the corresponding goals to be configured in your [Plausible dashboard](https://plausible.io/docs/custom-event-goals). Outbound link clicks are tracked as `Outbound Link: Click`, file downloads as `File Download`, and form submissions as `Form: Submission`.
119+
88120
## Module Options
89121

90-
| Option | Type | Default | Description |
91-
| ---------------------- | ---------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
92-
| `enabled` | `boolean` | `true` | Whether the tracker shall be enabled. |
93-
| `hashMode` | `boolean` | `false` | Whether page views shall be tracked when the URL hash changes. Enable this if your Nuxt app uses the `hashMode` router option instead of the default history mode. |
94-
| `domain` | `string` | `'window.location.hostname'` | The domain to bind tracking event to. |
95-
| `ignoredHostnames` | `string[]` | `['localhost']` | Hostnames to ignore when tracking events. |
96-
| `ignoreSubDomains` | `boolean` | `false` | Ignore the hostname if it is a subdomain of `ignoredHostnames`. |
97-
| `apiHost` | `string` | `https://plausible.io` | The API host where the events will be sent to. |
98-
| `autoPageviews` | `boolean` | `true` | Track the current page and all further pages automatically. Disable this if you want to manually manage pageview tracking. |
99-
| `autoOutboundTracking` | `boolean` | `false` | Track all outbound link clicks automatically. If enabled, a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) automagically detects link nodes throughout the application and binds `click` events to them. |
100-
| `logIgnoredEvents` | `boolean` | `false` | Log events to the console if they are ignored. |
101-
| `proxy` | `boolean` | `false` | Whether to proxy the event endpoint through the current origin. |
102-
| `proxyBaseEndpoint` | `string` | `'/_plausible'` | The base endpoint to proxy the Plausible event endpoint through. |
122+
| Option | Type | Default | Description |
123+
| ---------------------- | ------------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
124+
| `enabled` | `boolean` | `true` | Whether the tracker shall be enabled. |
125+
| `hashMode` | `boolean` | `false` | Whether page views shall be tracked when the URL hash changes. Enable this if your Nuxt app uses hash-based routing. |
126+
| `domain` | `string` | `'window.location.hostname'` | The domain to bind tracking events to. |
127+
| `ignoredHostnames` | `string[]` | `['localhost']` | Hostnames to ignore when tracking events. |
128+
| `ignoreSubDomains` | `boolean` | `false` | Also ignore subdomains of `ignoredHostnames`. |
129+
| `apiHost` | `string` | `'https://plausible.io'` | The API host where events will be sent to. |
130+
| `autoPageviews` | `boolean` | `true` | Track page views automatically. Disable this if you want to manually manage pageview tracking. |
131+
| `autoOutboundTracking` | `boolean` | `false` | Track outbound link clicks automatically. |
132+
| `fileDownloads` | `boolean \| { fileExtensions: string[] }` | `false` | Track file downloads automatically. Pass an object to customize tracked file extensions. |
133+
| `formSubmissions` | `boolean` | `false` | Track form submissions automatically. |
134+
| `logIgnoredEvents` | `boolean` | `false` | Log ignored events to the console. |
135+
| `proxy` | `boolean` | `false` | Proxy the event endpoint through the current origin. |
136+
| `proxyBaseEndpoint` | `string` | `'/_plausible'` | The base endpoint path for the proxy. |
103137

104138
## Composables
105139

106140
As with other composables in the Nuxt ecosystem, they are auto-imported and can be used in your application's components.
107141

108142
> [!NOTE]
109-
> Since the Plausible instance is available in the client only, executing the composables on the server will have no effect.
143+
> Since the Plausible instance is only available on the client, executing the composables on the server will have no effect.
110144
111145
### `useTrackEvent`
112146

@@ -117,8 +151,7 @@ Track a custom event. Track your defined goals by passing the goal's name as the
117151
```ts
118152
function useTrackEvent(
119153
eventName: string,
120-
options?: EventOptions,
121-
eventData?: PlausibleOptions,
154+
options?: PlausibleEventOptions,
122155
): void
123156
```
124157

@@ -128,25 +161,31 @@ function useTrackEvent(
128161
// Tracks the `signup` goal
129162
useTrackEvent('signup')
130163
131-
// Tracks the `Download` goal passing a `method` property.
164+
// Tracks the `Download` goal passing a `method` property
132165
useTrackEvent('Download', { props: { method: 'HTTP' } })
133166
```
134167

135168
### `useTrackPageview`
136169

137170
Manually track a page view.
138171

139-
Pass optional event data to be sent with the `eventData` argument. Defaults to the current page's data merged with the default options provided during the Plausible initialization.
140-
141172
**Type Declarations**
142173

143174
```ts
144175
function useTrackPageview(
145-
eventData?: PlausibleOptions,
146-
options?: EventOptions,
176+
options?: PlausibleEventOptions,
147177
): void
148178
```
149179

180+
**Example**
181+
182+
```ts
183+
useTrackPageview()
184+
185+
// Track with a custom URL
186+
useTrackPageview({ url: '/virtual-page' })
187+
```
188+
150189
## 💻 Development
151190

152191
1. Clone this repository
@@ -155,10 +194,6 @@ function useTrackPageview(
155194
4. Run `pnpm run dev:prepare`
156195
5. Start development server using `pnpm run dev`
157196

158-
## Credits
159-
160-
- [@Barbapapazes](https://github.com/Barbapapazes) for his [Plausible tracker rewrite](https://github.com/Barbapapazes/plausible-tracker)
161-
162197
## License
163198

164199
[MIT](./LICENSE) License © 2022-PRESENT [Johann Schopplich](https://github.com/johannschopplich)

0 commit comments

Comments
 (0)