plausible/docs

Documentation for Plausible Analytics

Plausible Analytics

Simple Metrics | Lightweight Script | Privacy Focused | Open Source | Docs | Contributing

Plausible Analytics is an easy to use, lightweight (< 1 KB), open source and privacy-friendly alternative to Google Analytics. It doesn’t use cookies and is fully compliant with GDPR, CCPA and PECR. You can self-host Plausible Community Edition or have us manage Plausible Analytics for you in the cloud. Here's the live demo of our own website stats. Made and hosted in the EU 🇪🇺

We are dedicated to making web analytics more privacy-friendly. Our mission is to reduce corporate surveillance by providing an alternative web analytics tool which doesn’t come from the AdTech world. We are completely independent and solely funded by our subscribers.

Why Plausible?

Here's what makes Plausible a great Google Analytics alternative and why we're trusted by 12,000+ paying subscribers to deliver their website and business insights:

• Clutter Free: Plausible Analytics provides simple web analytics and it cuts through the noise. No layers of menus, no need for custom reports. Get all the important insights on one single page. No training necessary.
• GDPR/CCPA/PECR compliant: Measure traffic, not individuals. No personal data or IP addresses are ever stored in our database. We don't use cookies or any other persistent identifiers. Read more about our data policy
• Lightweight: Plausible Analytics works by loading a script on your website, like Google Analytics. Our script is 45x smaller, making your website quicker to load. You can also send events directly to our events API.
• Email or Slack reports: Keep an eye on your traffic with weekly and/or monthly email or Slack reports. You can also get traffic spike notifications.
• Invite team members and share stats: You have the option to be transparent and open your web analytics to everyone. Your website stats are private by default but you can choose to make them public so anyone with your custom link can view them. You can invite team members and assign user roles too.
• Define key goals and track conversions: Create custom events with custom dimensions to track conversions and attribution to understand and identify the trends that matter. Includes easy ways to track outbound link clicks, file downloads and 404 error pages.
• Search keywords: Integrate your dashboard with Google Search Console to get the most accurate reporting on your search keywords.
• SPA support: Plausible is built with modern web frameworks in mind and it works automatically with any pushState based router on the frontend. We also support frameworks that use the URL hash for routing. See our documentation.
• Smooth transition from Google Analytics: There's a realtime dashboard, entry pages report and integration with Search Console. You can track your paid campaigns and conversions. You can invite team members. You can even import your historical Google Analytics stats. Learn how to get the most out of your Plausible experience and join thousands who have already migrated from Google Analytics.

Interested to learn more? Read more on our website, learn more about the team and the goals of the project on our about page or explore the documentation.

Why is Plausible Analytics Cloud not free like Google Analytics?

Plausible Analytics is an independently owned and actively developed project. To keep the project development going, to stay in business, to continue putting effort into building a better product and to cover our costs, we need to charge a fee.

Google Analytics is free because Google has built their company and their wealth by collecting and analyzing huge amounts of personal information from web users and using these personal and behavioral insights to sell advertisements.

Plausible has no part in that business model. No personal data is being collected and analyzed either. With Plausible, you 100% own and control all of your website data. This data is not being shared with or sold to any third-parties.

We choose the subscription business model rather than the business model of surveillance capitalism. See reasons why we believe you should stop using Google Analytics on your website.

Getting started with Plausible

The easiest way to get started with Plausible Analytics is with our official managed service in the cloud. It takes 2 minutes to start counting your stats with a worldwide CDN, high availability, backups, security and maintenance all done for you by us.

In order to be compliant with the GDPR and the Schrems II ruling, all visitor data for our managed service in the cloud is exclusively processed on servers and cloud infrastructure owned and operated by European providers. Your website data never leaves the EU.

Our managed hosting can save a substantial amount of developer time and resources. For most sites this ends up being the best value option and the revenue goes to funding the maintenance and further development of Plausible. So you’ll be supporting open source software and getting a great service!

Can Plausible be self-hosted?

Plausible is open source web analytics and we have a free as in beer and self-hosted solution called Plausible Community Edition (CE). Here are the differences between Plausible Analytics managed hosting in the cloud and the Plausible CE:

	Plausible Analytics Cloud	Plausible Community Edition
Infrastructure management	Easy and convenient. It takes 2 minutes to start counting your stats with a worldwide CDN, high availability, backups, security and maintenance all done for you by us. We manage everything so you don’t have to worry about anything and can focus on your stats.	You do it all yourself. You need to get a server and you need to manage your infrastructure. You are responsible for installation, maintenance, upgrades, server capacity, uptime, backup, security, stability, consistency, loading time and so on.
Release schedule	Continuously developed and improved with new features and updates multiple times per week.	It's a long term release published twice per year so latest features and improvements won't be immediately available.
Premium features	All features available as listed in our pricing plans.	Selected premium features such as funnels and ecommerce revenue goals are not available as we aim to ensure a protective barrier around our cloud offering.
Bot filtering	Advanced bot filtering for more accurate stats. Our algorithm detects and excludes non-human traffic patterns. We also exclude known bots by the User-Agent header and filter out traffic from data centers and referrer spam domains.	Basic bot filtering that targets the most common non-human traffic based on the User-Agent header and referrer spam domains.
Server location	All visitor data is exclusively processed on EU-owned cloud infrastructure. We keep your site data on a secure, encrypted and green energy powered server in Germany. This ensures that your site data is protected by the strict European Union data privacy laws and ensures compliance with GDPR. Your website data never leaves the EU.	You have full control and can host your instance on any server in any country that you wish. Host it on a server in your basement or host it with any cloud provider wherever you want, even those that are not GDPR compliant.
Data portability	You see all your site stats and metrics on our modern-looking, simple to use and fast loading dashboard. You can only see the stats aggregated in the dashboard. You can download the stats using the CSV export, stats API or tools such as the Data Studio Connector.	Do you want access to the raw data? Self-hosting gives you that option. You can take the data directly from the ClickHouse database.
Premium support	Real support delivered by real human beings who build and maintain Plausible.	Premium support is not included. CE is community supported only.
Costs	There's a cost associated with providing an analytics service so we charge a subscription fee. We choose the subscription business model rather than the business model of surveillance capitalism. Your money funds further development of Plausible.	You need to pay for your server, CDN, backups and whatever other cost there is associated with running the infrastructure. You never have to pay any fees to us. Your money goes to 3rd party companies with no connection to us.

Interested in self-hosting Plausible CE on your server? Take a look at our Plausible CE installation instructions.

Plausible CE is a community supported project and there are no guarantees that you will get support from the creators of Plausible to troubleshoot your self-hosting issues. There is a community supported forum where you can ask for help.

Our only source of funding is our premium, managed service for running Plausible in the cloud.

Technology

Plausible Analytics is a standard Elixir/Phoenix application backed by a PostgreSQL database for general data and a Clickhouse database for stats. On the frontend we use TailwindCSS for styling and React to make the dashboard interactive.

Contributors

For anyone wishing to contribute to Plausible, we recommend taking a look at our contributor guide.

Feedback & Roadmap

We welcome feedback from our community. We have a public roadmap driven by the features suggested by the community members. Take a look at our feedback board. Please let us know if you have any requests and vote on open issues so we can better prioritize.

To stay up to date with all the latest news and product updates, make sure to follow us on X (formerly Twitter), LinkedIn or Mastodon.

License & Trademarks

Plausible CE is open source under the GNU Affero General Public License Version 3 (AGPLv3) or any later version. You can find it here.

To avoid issues with AGPL virality, we've released the JavaScript tracker which gets included on your website under the MIT license. You can find it here.

Copyright (c) 2018-present Plausible Insights OÜ. Plausible Analytics name and logo are trademarks of Plausible Insights OÜ. Please see our trademark guidelines for info on acceptable usage.

docs's Issues

docs.plausible.io no longer redirects to plausible.io/docs

We used to have all docs.plausible.io pages redirect to plausible.io/docs pages but this is no longer happening. We still use many of the old docs.plausible.io links around the site plus there's SEO value in those old URLs. Is there a way to return the redirect?

Here's what happens now: https://docs.plausible.io/self-hosting
While it used to 301 redirect automatically to: https://plausible.io/docs/self-hosting

@plausible/developers

Allow specifying environment variables as file paths

For self-hosted configuration with docker, configuration is provided with environment variables.
It would be nice to be able to use docker secrets in order to protect sensitive values, such as ADMIN_USER_PWD, SECRET_KEY_BASE, DATABASE_URL, etc.

The simplest way to achieve this would be to introduce corresponding variables suffixed with _FILE. e.g. ADMIN_USER_PWD_FILE, SECRET_KEY_BASE_FILE, DATABASE_URL_FILE, etc. These variables should take precedence over the existing ones, and would allow docker secrets to be used as shown below. I've copied this from the example here but have only shown the plausible service for brevity:

services:
  plausible:
    image: plausible/analytics:latest
    restart: always
    command: sh -c "sleep 10 && /entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh db init-admin && /entrypoint.sh run"
    depends_on:
      - plausible_db
      - plausible_events_db
      - mail
    ports:
      - 8000:8000
    environment:
      - ADMIN_USER_EMAIL=replace-me
      - ADMIN_USER_NAME=replace-me
      - ADMIN_USER_PWD_FILE=/run/secrets/plausible_admin_pwd
      - BASE_URL=replace-me
      - SECRET_KEY_BASE_FILE=/run/secrets/plausible_secret_key
    secrets:
      - plausible_admin_pwd
      - plausible_secret_key

secrets:
  plausible_admin_pwd:
    file: /secrets/plausible_admin_pwd
  plausible_secret_key:
    file: /secrets/plausible_secret_key

nginx caches plausible.io IP when domain is used directly in proxy_pass

Hi,

we deployed a plausible proxy which worked at first but broke two weeks later.

Turns out that nginx resolves plausible.io once on start and then uses that IP until it's restarted.

This is bad since you run behind a CDN.

We changed our config like this to force nginx to respect DNS TTLs:

    # Setting a variable forces nginx to resolve and respect DNS TTLs
    set $plausible "plausible.io";
    # Set to your own DNS resolver
    resolver 127.0.0.11 ipv6=off;

    location ~ ^/js/(.*)$ {
        proxy_pass https://$plausible/js/$1;
        proxy_set_header Host plausible.io;

        proxy_buffering on;
    }

    location = /api/event {
        proxy_pass https://$plausible/api/event;
        proxy_set_header Host plausible.io;
        proxy_buffering on;
        proxy_http_version 1.1;

        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
    }

Of course the resolver IP needs to be changed to the local environment and also IPv6 can be enabled if available.
We also proxy every request to /js/* since we need the other scripts you offer.

Maybe you can incorporate this into your documentation.

Add link to https://plausible.io/docs in Repo's About Section

Thank you for putting the docs together. What are your thoughts on adding a link to https://plausible.io/docs?

Thank you guys!

GitHub should have a thank you template for sending out love.

Been a beta user since (I think) the very start, and an almost daily user by now.

This is a great piece of software @ukutaht. Thank you so much!

Are X-Forwarded-Proto and X-Forwarded-Host headers used?

The proxying instructions for various platforms set three headers: X-Forwarded-For. X-Forwarded-Proto and X-Forwarded-Host. However the docs for event API mention only X-Forwarded-For.

Are the X-Forwarded-Proto and X-Forwarded-Host used somewhere else or is including them in proxying docs just a mistake?

Does Cloudfront subdirectory require Lambda Edge?

Hello. Thanks for the new instructions for Cloudfront proxying.

They say

In case of a subdirectory installation, you'll also need to add a data-api attribute to tell the script where the data should be sent.

My understanding of Cloudfront is that it does not strip matching paths when proxying. So if I have a subdirectory of subdirectory[1], this would proxy to plausible as plausible.io/subdirectory/js/script.js, which I believe is incorrect. I believe a Lambda-Edge component is required for this. My suspicion is that the extra sentence was added to the docs without considering this, and that the author doesn't use a subdirectory. But my understanding might be incorrect and I wanted to check before I invested the time into the Lambda-Edge.

Here is a StackOverflow question that I think is relevant.

Your advice would be appreciated :)

[1] (e.g. <script defer data-domain="yourdomain.com" data-api="/subdirectory/api/event" src="/subdirectory/js/script.js"></script>)

configuration of mailer email for self hosted version

I've updated my .env file with a custom email address, but the emails coming from plausible still show as from [email protected]. Am I missing a configuration step here?

improve steps for google search integration

i've been trying to figure out via this chapter how to add that particular integration, but have been frankly overwhelmed by the google dev console.

maybe it's possible to add a step by step guide here, in order to help through the myriade of options in the dev console.

Documentation - Place "data-analytics" code before </body>

On https://plausible.io/docs/custom-event-goals, there is the text: To be able to read the data-analytics you need to add the javascript below.

What are your thought on recommend that the code is loaded before the closing ?

Stats page not loading now

For some reason I'm getting this error when looking at a sites stats:

XHRGEThttps://stats.foobar.com/api/stats/foobar.com/sources?period=30d&date=2022-09-10&filters={}&show_noref=false
[HTTP/2 500 Internal Server Error 151ms]

XHRGEThttps://stats.foobar.com/api/stats/foobar.com/pages?period=30d&date=2022-09-10&filters={}
[HTTP/2 500 Internal Server Error 152ms]

XHRGEThttps://stats.foobar.com/api/stats/foobar.com/main-graph?period=30d&date=2022-09-10&filters={}
[HTTP/2 500 Internal Server Error 157ms]

Uncaught (in promise) ApiError: ** (FunctionClauseError) no function clause matching in Clickhousex.Codec.Values.to_iodata/4
    lo https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    r https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    r https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    o https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    bo https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    promise callback*bo/< https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    promise callback*bo https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    value https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    value https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    observer https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    value https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    cs https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    wl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    unstable_runWithPriority https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    Ko https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    xl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    sl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    nl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    ql https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    Xl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    cl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    Xl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    render https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    <anonymous> https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    <anonymous> https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    <anonymous> https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
dashboard-bf1db32678121078d82c8d8f4f323c64.js:2:604903
Uncaught (in promise) ApiError: ** (FunctionClauseError) no function clause matching in Clickhousex.Codec.Values.to_iodata/4
    r https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    r https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    o https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    bo https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    promise callback*bo/< https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    promise callback*bo https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    value https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    value https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    observer https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    value https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    cs https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    wl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    unstable_runWithPriority https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    Ko https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    xl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    sl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    nl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    ql https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    Xl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    cl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    Xl https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    render https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    <anonymous> https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    <anonymous> https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
    <anonymous> https://stats.foobar.com/js/dashboard-bf1db32678121078d82c8d8f4f323c64.js?vsn=d:2
dashboard-bf1db32678121078d82c8d8f4f323c64.js:2:604574
Uncaught (in promise) SyntaxError: JSON.parse: unexpected end of data at line 1 column 1 of the JSON data

If I manually go to:
https://stats.foobar.com/api/stats/graphicsfactory.com/sources?period=30d&date=2022-09-10&filters=%7B%7D&show_noref=false

I get:

{"error":"** (FunctionClauseError) no function clause matching in Clickhousex.Codec.Values.to_iodata/4"}

I've tried restarting Plausible but still the same problem. Any suggestions?

How to exclude on a custom domain?

The page at https://docs.plausible.io/excluding#block-the-plausible-analytics-script-on-your-domain provides instructions for excluding oneself from analytics using uBlock origin. However, in my experience this is not working for sites which have been set up using a custom domain following https://docs.plausible.io/custom-domain. I have also tried the obvious variation domain.org plausible_subdomain.domain.org * block, but this does not seem to work either.

I believe the instructions should be updated to include how to do this properly. If, for whatever reason, the instructions ought to work and my experience is user error, I would claim that it should be stated explicitly in the documentation that the same procedure should work for custom domains, as well.

Looking for a "0% cookie 100% privacy" branding/ribbon ?

I was looking for adding a "ribbon" of some sort for my site now fully without cookie (thanks to plausible :-)
but I couldn't find anything close to this "0% cookie 100% privacy" sort of.

May be with the need for more privacy/cookie free sites, it would be a good opportunity to reach/lead such a privacy "brand" ?

Any idea/inside/thought/link for this ??

Tracking page view via anchors instead of path

Hey,

i have a website built with a template that uses anchors '#about-me' for page navigation. Plausible now only tracks '/' as a page view. Can I somehow change it to evaluate anchors as page view?

Outbound link tracking JS "blocks" other event listeners on <a>

Prerequisites

• I have searched open and closed issues to make sure that the bug has not yet been reported.

Bug report

I'm using https://plausible.io/js/plausible.outbound-links.js to track outbound clicks on links with Plausible. This script appears to send a request to Plausible prior to directing the user to the link which was clicked (a sensible approach). This broke checkout on a landing page though, because the checkout links also uses document.location to redirect the user to checkout (after obtaining a checkout session asynchronously). It's an edge case; the checkout link goes through a subdomain. I don't think there's a better way to do this, because both event listeners on the tag are needed but do 'compete' with each other.

Expected behavior
I think this behavior should be noted/explained in the docs, so people are aware if they also have their own event listeners on tags. An additional alternative for the docs, would be to provide 1-2 examples of sending the same outbound click tracking request using vanilla JS or jQuery. (This is what I'll end up using, i.e. adding the same functionality in an existing script + excluding checkout links.)

Environment (If applicable): (Occurred on, but not limited to)

• OS: macOS Big Sur
• Browser Safari 14.0.1

Event Triggers via Tag Attribute

Just went over your guide, and I was surprised and somewhat disappointed that you don't feature a quick and easy way to track an event via simple attribute addition, for example:

<button data-pa-event="downloadClicked"> Download </button>

PS: You could transform the attr name (via npm package) or on-page load if you fear ad-blocking.

`Top Pages` statistics Can't load next pages

response error:

{"error":"** (ArithmeticError) bad argument in arithmetic expression"}

Can't get maxmind to work

Followed the docs here https://plausible.io/docs/self-hosting#1-maxmind-geolocation-database but it doesn't seem to work. The map is never populated and the countries tab shows No data yet.

• Added the Maxmind credentials in the geoip/geoip.conf
• Added the conf variable GEOLITE2_COUNTRY_DB=/geoip/GeoLite2-Country.mmdb
• started the stack using docker-compose -f docker-compose.yml -f geoip/docker-compose.geoip.yml up -d
• checked the docker logs for any possible errors, but nothing there

Any ideas?

Documentation Needed: Exporting Data

Many thanks for plausible. I just converted to an annual subscription :)

I am missing documentation on how to export data.

Specifically the two types:

1. The page views per day. This can be exported to CSV with the little "download" icon in the main graph. (Feedback: I found it hard to find this button.) This link does answer the question, but it is not in the "docs" for plausible.
2. How to export raw data, incl. referrers, country, etc.

Best regards, Christoph

Feature Request: View multiple properties in goal conversions

When viewing goal conversion stats it appears to only be possible to breakdown by 1 property at a time. Ideally i would like to be able to view all at once or at the minimum 2 at a time.

Vercel proxy documentation

The documentation for proxying through nextjs/vercel only covers nextjs however vercel supports a range of different frameworks.

Would it be possible to expand the docs a bit on how to proxy plausible through vercel for other frameworks, for example with a react SPA? Happy to put a PR on it if anyone can give some guidance. Otherwise I'd recommend removing "Vercel" from the title as the instructions work for any nextjs deployment.

Self hosting: invalid command to manually verify all users

First of all, your self-hosting docs are excellent. That said, there's a small bug in the command provided to verify accounts:

$ docker exec hosting_plausible_db_1 psql -U postgres -d plausible_db -c "UPDATE users SET email_verified = true;"
Error: No such container: hosting_plausible_db_1

Now, I'm using docker-compose v2.5.0. Here, the container names look like this:

$ docker-compose ps
NAME                            COMMAND                  SERVICE               STATUS              PORTS
hosting-mail-1                  "docker-entrypoint.s…"   mail                  running             25/tcp
hosting-plausible-1             "/entrypoint.sh sh -…"   plausible             running             0.0.0.0:8000->8000/tcp, :::8000->8000/tcp
hosting-plausible_db-1          "docker-entrypoint.s…"   plausible_db          running             5432/tcp
hosting-plausible_events_db-1   "/entrypoint.sh"         plausible_events_db   running             9009/tcp

Notice the hyphens versus underscores, there. A simple fix would be to simply change the docker command to use the proper container name:

$ docker exec hosting-plausible_db-1 psql -U postgres -d plausible_db -c "UPDATE users SET email_verified = true;"

That feels fragile, though. Are container name formats stable in docker-compose? I don't know, but it feels a little internal-API-ish. It seems like it would be better to use docker-compose itself for this:

$ docker-compose exec plausible_db psql -U postgres -d plausible_db -c "UPDATE users SET email_verified = true;"

[DOC] give a warning for CSP headers when using subdomain

This issues is backport from plausible/analytics#251 . Much better place for this.

When your site is using some Content Security Policy, you have to add plausible.io in order the .js to load and to work. I guess this is known if you manage your website's header with CSP.

But when you add statsforplausible.mydomain.com in order to go thru Adblock problems, do not forget to add this subdomain specifically to your CSP too.

May be you can add a small warning in the setup documentation page ? I didn't made a doc PR because i do not know your policy for that :-)
HTH.

Improve CSP instructions

Similar to #4, but CSP headers need to be added even if it's not served from a custom subdomain. I think these instructions should be much more upfront, maybe here: https://docs.plausible.io/plausible-script

In particular I think it would be helpful to note specifically which CSP policies need to be edited, and provide some examples. e.g.

Lax CSP (simple and future proof):

Content-Security-Policy: default-src 'self' *.plausible.io

Stricter CSP (more precise, but can break if the implementation is changed, like reporting back to a different subdomain) (the script-src and connect-src policies need to be merged with any other existing domains for those directives

Content-Security-Policy: default-src 'self'; script-src plausible.io; connect-src plausible.io

Thanks for your work on this, giving this service a try now with the hope of replacing GA.

Missing plausible-conf example file

The plausible-conf.env file is missing from the self-hosted setup docs.

Docs page --> https://plausible.io/docs/self-hosting#1-clone-the-hosting-repo

Url with the below 404 --> https://plausible.io/self-hosting-configuration

Search Console integration no longer working

I noticed that integration was working but now was broken. I disconnected the account and started again

Clicking on "Continue with Google" gives an error

Error 401: deleted_client
The OAuth client was deleted.

but I haven't changed anything in the console and it should be still setup correctly.

Cloudflare proxy example doesn't cache the /js/script.js file because Netlify origin returns cache-control: max-age=0

I've just integrated Plausible on Jobsort.com and got an alert from SEMrush that I'm serving uncached JS files which was surprising.

The example to create a Cloudflare worker from https://plausible.io/docs/proxy/guides/cloudflare#step-1-create-a-worker doesn't cache anything even though caches.default.put is used. If you look at the Cloudflare documentation https://developers.cloudflare.com/workers/learning/how-the-cache-works#cache-api they say:

Explicitly store a response in the cache using caches.default.put(..) and explicitly delete caches.default.delete(..). For example, say your origin is returning max-age:0 and you can’t figure out how to change that header at your origin. You can explicitly tell Cloudflare to cache this response by setting cache-control: max-age=1000 on the response passed into cache.put().

The Plausible origin returns cache-control: max-age=0 and in fact the cache is not used at all if using the documented example, as seen in the screenshot:

So, the example code from https://plausible.io/docs/proxy/guides/cloudflare#step-1-create-a-worker should be changed from:

async function getScript(event, extensions) {
    let response = await caches.default.match(event.request);
    if (!response) {
        response = await fetch("https://plausible.io/js/plausible." + extensions.join("."));
        event.waitUntil(caches.default.put(event.request, response.clone()));
    }
    return response;
}

to:

async function getScript(event, extensions) {
    let response = await caches.default.match(event.request);
    if (!response) {
        response = await fetch("https://plausible.io/js/plausible." + extensions.join("."));

      const cacheableResponse = new Response(response.body, response);

      // Must explicitly add cache age because the origin serves `max-age=0`.
      cacheableResponse.headers.set("cache-control", "max-age=31536000");

      event.waitUntil(caches.default.put(event.request, cacheableResponse.clone()));

      return cacheableResponse;
    }
    return response;
}

With the fix, the response is now cached:

The latency of serving the script file drops from ~400ms to ~40ms.

Question is, what's the story behind versioning the script if it actually gets cached with the above fix?
Also, why is Netlify configured to not allow client to cache the Plausible JS script? Thanks

List all configuration options

Like Google Integration.

I have no glue how this will be fetched from env https://github.com/plausible/analytics/blob/ead4a7d56099c9b0a63dcc574b3a7c889a862366/lib/plausible/google/api.ex#L143

Can't make it work with NuxtJS

Hello!

I have tried all official docs for nuxtjs and vue-meta, tried different combinations. Could you tell me where exactly I would need to attach the script? Before body tag? After? In the footer maybe? Thank you.

Hexo Integration

Hi!
I have built a plugin to integrate Plausible Analytic with Hexo.

This is the url: https://github.com/maaaaarco/hexo-plausible-analytics

Feel free to add it to your doc page.

Add Custom Event Goals example for ahref

I want to try Custom Goals for the links on my landing page but don't know the best practices for this kind of thing (If I did maybe I could add an example). How does this seem?

<head>
<script async defer data-domain="[MY_DOMAIN]" src="https://plausible.io/js/plausible.js"></script>
<script>
  window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }

  function OpenLink(self, e, name) {
    e.preventDefault();
    plausible(name)
    var href = $(self).attr("href");
    window.open(href);
    return false;
}
</script>
</head>

<body>
    <a href="https://plausible.com" onclick="return OpenLink(this, event, 'Test Event');">
</body>

Unreleased feature already in docs

I wanted to use this feature with my self-hosted plausible instance. It wasn't working so I checked the repo. Here I found, that this feature is in the "unreleased" section. A bit confusing maybe.

Provide easy code examples for popular custom events

To make it easy for those without JavaScript experience or without any development help to set up goals:

Text link clicks
Button clicks
Form submits

Proxy Plausible (selfhosted) with nginx not working

Hello!
I hope that this is the right place to ask for help/talk about the documentation.
I tried to use the described proxy method with nginx as described here: https://plausible.io/docs/proxy/guides/nginx

But when trying to open https://mydomain2.de/js/script.js I only get an 404 error - when trying to open the url with the url where my selfhosted plausible instance is running, it's working/the script will be shown.

I added the additional lines of Step 1.5, except the ones which are duplicated.

That's my current nginx config:

    location = /js/script.js {
        # Change this if you use a different variant of the script
        proxy_pass https://plausible.mydomain.de/js/script.js;
        proxy_set_header Host plausible.mydomain.de;
        proxy_ssl_name plausible.mydomain.de;
        proxy_ssl_server_name on;
        proxy_ssl_session_reuse off;

        # Tiny, negligible performance improvement. Very optional.
        proxy_buffering on;

        proxy_cache jscache;
        proxy_cache_valid 200 6h;
        proxy_cache_use_stale updating error timeout invalid_header http_500;

        # Optional. Adds a header to tell if you got a cache hit or miss
        add_header X-Cache $upstream_cache_status;
    }

    location = /api/event {
        proxy_pass https://plausible.mydomain.de/api/event;
        proxy_set_header Host plausible.mydomain.de;
        proxy_buffering on;
        proxy_http_version 1.1;

        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_ssl_name plausible.mydomain.de;
        proxy_ssl_server_name on;
        proxy_ssl_session_reuse off;
    }

Netlify redirect rules need to use status 200 instead of 202

I setup my netlify redirect/proxy rules as documented here https://github.com/plausible/docs/blob/master/docs/proxy/guides/netlify.md#step-1-add-url-rewrite-rules

My site has a custom 404.html page. Whenever sending a request to /api/event, the redirect rule did not get executed, instead I got served the 404.html page.

I noticed that the netlify docs are never mentioning 202 as a supported status code for proxying. Thus changing the redirect rule to use status code 200 and that fixed the redirect, which is now properly proxying to plausible.

Example for workaround when event function does not work

Hi guys,

uBlock origin is blocking plausible within firefox. No problem, but it would be cool if you could provide a fallback for the event function to get the callback triggered too.

https://plausible.io/docs/custom-event-goals

What you think about this?

<script async defer data-domain="<yourdomain.com>" src="https://plausible.io/js/plausible.js"></script>
<script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>

How can the last line be rewritten, so the callback get be triggered too?

Can't use file-downloads script along with manual scripts

I made changes to my plausible configuration to be able to use custom location along with file-downloads and outbound-links.

Everything is ok for outbound-links but I can't trigger file-downloads event when I download pdf on my website.

Is there something, I'm missing ?

BUG : extra 'docs/` in url cause wrong link for "edit this page" on doc site.

• The given url is : https://github.com/plausible/docs/edit/master/docs/docs/contribute.md
• Should be : https://github.com/plausible/docs/edit/master/docs/contribute.md

There is an extra docs

Uncached JavaScript and CSS files

Semrush reports uncached Javascript for https://plausible.io/js/plausible.js which pull down the SEO Score.

SMTP SSL Configuration needs clarity

On this page

https://plausible.io/docs/self-hosting-configuration

the default value of SMTP_HOST_SSL_ENABLED is mentioned as false. Which leads a person to believe that he needs to set the value as true for SSL to work. Which turned out to be wrong.

You need to set its value as 1 and not true to get the mails working. This needs to be clarified in the docs.

Add minimum or recommended hardware requirements.

The self-hosting docs currently do not list recommended (or minimum) hardware requirements in terms of RAM or vCPUs/CPU. This would be a nice addition for people like me who are too lazy to create and delete VPS servers while testing for the right amount of resources.

If anyone else is self-hosting Plausible, maybe you could chime in please? 🙂

Script tag inconsistency with `async`

Hi,

To me it's unclear whether to use the async attribute within the script tag. See this page: https://plausible.io/docs/plausible-script

The illustration includes the attribute, but the code snippet doesn't.

Kind regards,
Erik

Exclude the `$` when copying bash examples

Vercel setup

Hello,

I integrated the proxy for a static site (i.e. not Next) on Vercel yesterday.

It's a bit different as it uses a vercel.json file.

Do you want me to submit a new page to the docs?

API/SDK for non-web platforms?

Is there API documentation for implementing non-JS clients?

LICENSE of this repository?

I wanted to use the files given on the https://plausible.io/docs/excluding-localstorage page. So, I came here to check license of this repository. It will be good to have some license to this documentation repository, or explicitly mention the license of the HTML and CSS files given on the above page.

Search box in the top right of the docs doesn't work

Search box in the top right of the docs doesn't work. Nothing happens when clicked

Tracking form button submit events

I don't have control to add attributes to the submit buttons, but I can add attributes to the wrapper or parent element of the form on my website.

What can I change in the code for this to work?

<script>
  let buttons = document.querySelectorAll("button[data-analytics]");
  for (var i = 0; i < buttons.length; i++) {
      buttons[i].addEventListener('click', handleFormEvent);
      buttons[i].addEventListener('auxclick', handleFormEvent);
  }

  function handleFormEvent(event) {
      event.preventDefault();
      let attributes = event.target.getAttribute('data-analytics').split(/,(.+)/);
      let events = [JSON.parse(attributes[0]), JSON.parse(attributes[1] || '{}')];
      plausible(...events);
      setTimeout(function () {
          event.target.form.submit();
      }, 150);
  }
</script>

Add a "forum" link to discourse / docs / landing page

It should be favorable to help people navigate between the community forum : discourse and

• the documentation : doc
• the plausible dashboard
• the landing page

by adding similar links beside each other :

• add Forum link beside Github on docs.plausible.io/
• add Forum link beside Docs on my Dashbord page plausible.io/my_plausible_name
• add Forum link beside Docs on plausible.io landing page
• add Docs (and may be my dashbord ? not sure) links on plausible.discourse.group

[EDIT] changed name to forum to be in phase with the site vocabulary.

Sphinx extension

I've made a Sphinx extension for Plausible:
https://pypi.org/project/sphinx-plausible/

The existing instructions are more complex than they need to be, Sphinx has the ability to make an extension to insert custom scripts into the head with the required tags. Thus, this works for any theme with no modification. Reviews of the code welcome, it is very new!

By the way, do you know if <script defer="defer" ...> is equivalent to <script defer ...> in all practical cases? Only newer sphinx can do the second, but if I use the first, then I can make it support very old Sphinx versions, too.