Skip to content
1337skills 1337skills

Plausible Cheat Sheet

Overview

Plausible is a lightweight, open-source web analytics tool designed with privacy as a core principle. It does not use cookies, does not collect personal data, and is fully compliant with GDPR, CCPA, and PECR out of the box. The script is under 1 KB in size, making it significantly faster than traditional analytics solutions.

Plausible can be used as a hosted cloud service or self-hosted using Docker. It provides essential metrics such as pageviews, visitors, bounce rate, visit duration, referral sources, and goal conversions without the complexity and privacy concerns of larger platforms. The dashboard is simple, focused, and shareable via public links.

Installation

Cloud Hosted

Sign up at plausible.io and add the tracking script to your site:

<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>

Self-Hosted with Docker

# Clone the hosting repository
git clone https://github.com/plausible/community-edition plausible-ce
cd plausible-ce

# Generate a secret key
openssl rand -base64 48

# Copy and edit the configuration
cp .env.example .env
nano .env
# Set BASE_URL, SECRET_KEY_BASE, and database credentials

# Start the services
docker compose up -d

# Check the running containers
docker compose ps

Proxy Setup with Nginx

location /js/script.js {
    proxy_pass https://plausible.io/js/script.js;
    proxy_set_header Host plausible.io;
}

location /api/event {
    proxy_pass https://plausible.io/api/event;
    proxy_set_header Host plausible.io;
}

Core Features

Script Variants

ScriptPurpose
script.jsDefault tracking script
script.hash.jsHash-based routing for SPAs
script.outbound-links.jsTrack outbound link clicks
script.file-downloads.jsTrack file downloads
script.tagged-events.jsCustom event tracking via CSS classes
script.revenue.jsRevenue and e-commerce tracking
script.pageview-props.jsCustom properties on pageviews
script.compat.jsIE compatibility mode

Combine extensions by chaining names:

<script defer data-domain="yourdomain.com"
  src="https://plausible.io/js/script.hash.outbound-links.file-downloads.js">
</script>

Custom Events via JavaScript

<script>
  // Track a custom event
  plausible('Signup', {props: {plan: 'premium', source: 'landing'}});

  // Track a purchase with revenue
  plausible('Purchase', {revenue: {currency: 'USD', amount: 29.99}});

  // Track a form submission
  document.getElementById('contact-form').addEventListener('submit', function() {
    plausible('Contact Form Submission');
  });
</script>

Custom Events via CSS Classes

<!-- With script.tagged-events.js -->
<a href="/signup" class="plausible-event-name=Signup+CTA+Click">Sign Up</a>
<button class="plausible-event-name=Download plausible-event-type=PDF">Download</button>

API Usage

Stats API

# Get aggregate stats for a time period
curl "https://plausible.io/api/v1/stats/aggregate?site_id=yourdomain.com&period=30d&metrics=visitors,pageviews,bounce_rate,visit_duration" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get time series data
curl "https://plausible.io/api/v1/stats/timeseries?site_id=yourdomain.com&period=6mo&metrics=visitors" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Breakdown by page
curl "https://plausible.io/api/v1/stats/breakdown?site_id=yourdomain.com&period=30d&property=event:page&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Breakdown by source with filters
curl "https://plausible.io/api/v1/stats/breakdown?site_id=yourdomain.com&period=30d&property=visit:source&filters=event:page==/blog/**" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sites API

# Create a new site
curl -X POST "https://plausible.io/api/v1/sites" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"newsite.com","timezone":"America/New_York"}'

# Delete a site
curl -X DELETE "https://plausible.io/api/v1/sites/newsite.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a shared link
curl -X PUT "https://plausible.io/api/v1/sites/shared-links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"yourdomain.com","name":"Public Dashboard"}'

Configuration

Environment Variables (Self-Hosted)

# Required
BASE_URL=https://analytics.yourdomain.com
SECRET_KEY_BASE=your-generated-secret-key
DATABASE_URL=postgres://plausible:password@db:5432/plausible
CLICKHOUSE_DATABASE_URL=http://clickhouse:8123/plausible_events

# Email (for reports and alerts)
MAILER_EMAIL=analytics@yourdomain.com
SMTP_HOST_ADDR=smtp.yourdomain.com
SMTP_HOST_PORT=587
SMTP_USER_NAME=analytics@yourdomain.com
SMTP_USER_PWD=your-smtp-password
SMTP_HOST_SSL_ENABLED=true

# Optional settings
DISABLE_REGISTRATION=invite_only
LOG_LEVEL=warn
MAXMIND_LICENSE_KEY=your-key-for-city-level-geolocation
GOOGLE_CLIENT_ID=your-id-for-search-console-integration
GOOGLE_CLIENT_SECRET=your-secret

Google Search Console Integration

# In .env for self-hosted
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

Then connect via Site Settings > Search Console in the dashboard.

Advanced Usage

404 Error Page Tracking

<!-- On your 404 page -->
<script>
  plausible('404', {props: {path: document.location.pathname}});
</script>

Single Page Application Tracking

// Manual pageview tracking for SPAs
// Use with script.manual.js variant
window.plausible = window.plausible || function() {
  (window.plausible.q = window.plausible.q || []).push(arguments);
};

// Call on route change
function trackPageview() {
  plausible('pageview');
}

// React Router example
useEffect(() => {
  trackPageview();
}, [location.pathname]);

Excluding Pages from Tracking

<script defer data-domain="yourdomain.com"
  data-exclude="/admin/**, /private/**"
  src="https://plausible.io/js/script.js">
</script>

Tracking Across Multiple Domains

<script defer data-domain="site1.com,site2.com,rollup.site.com"
  src="https://plausible.io/js/script.js">
</script>

Import from Google Analytics

Navigate to Site Settings > Imports & Exports > Import Data and connect your Google Analytics property to import historical data.

Troubleshooting

IssueSolution
Script blocked by ad blockersUse a proxy setup (serve script from your own domain)
No data appearingCheck browser console for script loading errors; verify data-domain matches exactly
Self-hosted not startingRun docker compose logs to check for database connection issues
Stats seem low vs GAPlausible counts unique visitors differently; ad-blocked users are not tracked
CSP errors in consoleAdd plausible.io (or your self-hosted domain) to script-src and connect-src
Email reports not sendingVerify SMTP configuration in .env and check docker compose logs plausible
ClickHouse disk usage growingSet up data retention policies or increase disk allocation
Google Search Console not connectingEnsure OAuth credentials are correct and redirect URI matches your BASE_URL