> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/plausible/analytics/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript Tracker Integration
> Learn how to integrate the Plausible Analytics tracker script into your website for privacy-focused analytics
## Overview
The Plausible Analytics tracker is a lightweight JavaScript snippet that enables privacy-focused web analytics on your website. It automatically captures pageviews and can be configured to track custom events, file downloads, outbound links, and more.
## Installation Methods
There are two primary ways to integrate Plausible Analytics into your website:
Add the Plausible script to your website's `` section:
```html theme={null}
```
Replace `yourdomain.com` with your actual domain name as configured in your Plausible account.
The `defer` attribute ensures the script loads asynchronously without blocking page rendering.
Install the official NPM package for modern JavaScript applications:
```bash theme={null}
npm install @plausible-analytics/tracker
```
Then initialize the tracker in your application:
```javascript theme={null}
import { init } from '@plausible-analytics/tracker'
init({
domain: 'my-app.com'
})
```
This library only works in browser environments. When using server-side rendering (SSR), ensure `init` and `track` functions are only called on the client side.
## Configuration Options
The tracker accepts various configuration options to customize its behavior:
### Script Attributes
When using the script tag method, configure behavior through data attributes:
| Attribute | Description | Example |
| -------------- | ------------------------------------ | ---------------------------------------------------- |
| `data-domain` | **Required** - Your site's domain | `data-domain="example.com"` |
| `data-api` | Custom API endpoint for proxying | `data-api="https://analytics.example.com/api/event"` |
| `data-exclude` | Exclude specific pages from tracking | `data-exclude="/admin/**"` |
| `data-include` | Only track specific pages | `data-include="/blog/**"` |
### NPM Configuration
When using the NPM package, pass configuration options to the `init` function:
```javascript theme={null}
import { init } from '@plausible-analytics/tracker'
init({
domain: 'my-app.com',
endpoint: 'https://plausible.io/api/event',
autoCapturePageviews: true,
hashBasedRouting: false,
outboundLinks: false,
fileDownloads: false,
formSubmissions: false,
captureOnLocalhost: false,
logging: true,
bindToWindow: true
})
```
### Configuration Reference
Your site's domain, as declared in your Plausible account settings.
The URL of the Plausible API endpoint. See the [proxy guide](https://plausible.io/docs/proxy/introduction) for custom endpoints.
Whether to automatically capture pageviews. Set to `false` for manual pageview tracking.
Enable for single-page applications using hash-based routing (e.g., `#/page`). Read more in the [hash-based routing docs](https://plausible.io/docs/hash-based-routing).
Automatically track clicks on outbound links.
Track file downloads. Can be `true` or an object with custom file extensions:
```javascript theme={null}
fileDownloads: { fileExtensions: ['pdf', 'zip', 'csv'] }
```
Automatically track form submissions.
Enable event capture on localhost for testing.
Log warnings when events are ignored.
Binds `track` function to `window.plausible` for verification and debugging.
## Advanced Usage
### Manual Initialization
For advanced control, you can manually initialize the tracker with custom settings:
```html theme={null}
```
### Proxying the Tracker
To avoid ad-blockers, proxy the Plausible script through your own domain:
```html theme={null}
```
See the [proxy documentation](https://plausible.io/docs/proxy/introduction) for setup instructions.
### Excluding Pages
Exclude specific pages from tracking using wildcard patterns:
```html theme={null}
```
Supported wildcard patterns:
* `*` - matches any characters except forward slashes
* `**` - matches any characters including forward slashes
## Verification
After installing the tracker, verify it's working correctly:
Open your browser's developer console and look for any Plausible-related warnings or errors.
Type `window.plausible` in the console. If the tracker is loaded, you should see a function.
Navigate your site and check the Network tab for requests to `/api/event` with status code 202.
Visit your Plausible dashboard and check the real-time visitor count.
## Opt-out
Users can opt out of tracking by setting a localStorage flag:
```javascript theme={null}
localStorage.setItem('plausible_ignore', 'true')
```
The tracker will not send events if `localStorage.plausible_ignore` is set to `"true"`.
More information: [Excluding with localStorage](https://plausible.io/docs/excluding-localstorage)
## Next Steps
Track custom goals and user interactions
Add metadata to your events
Server-side event tracking
Integration guides for popular frameworks