Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions _docs/20_install-script/01_script.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,19 @@
title: How to add our script
category: install-script
permalink: /script
last_modified_at: 2026-10-29
last_modified_at: 2026-11-06
---

## Install with AI

Using Claude Code, Codex, Cursor or another AI agent? Let it install the script and check that it works. When you add a website in the dashboard, click **Copy AI instructions** and paste them into your agent. They have the right script for your website and let the agent check the installation. Or ask your agent:

```
Install Simple Analytics on example.com, follow https://docs.simpleanalytics.com/install.md
```

## Install manually

Include these two lines on every page at the end of your `<body>` (or anywhere else):

<!-- prettier-ignore -->
Expand Down Expand Up @@ -36,7 +46,12 @@ With Simple Analytics you don't need to manually trigger page views in SPA. We a

Some people like a very light script. All our scripts are heavily compressed and we have [an extra light](/light) version.

If you want to run the script on localhost, please use our dev (`https://scripts.simpleanalyticscdn.com/latest.dev.js`) version. Note the `.dev` part. You might want to [overwrite your hostname](/overwrite-domain-name) from localhost to something like `dev.example.com` (where `example.com` is your domain) to receive it in your dashboard. Make sure to remove the `.dev` part from the script on production.
To test the script on localhost or a preview URL, set `data-hostname` to the hostname of your website. Page views there then count for that website, so you can check the requests before your website is live. See [overwrite domain name](/overwrite-domain-name).

<!-- prettier-ignore -->
```html
<script async data-hostname="example.com" src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
```

We drop data from some shared preview and proxy domains, like `*.vercel.app`, `*.lovable.app`, and `*.translate.goog`, unless that exact hostname is added to your dashboard. To collect data on such a domain, add the hostname to your dashboard or [overwrite the hostname](/overwrite-domain-name).

Expand Down
27 changes: 3 additions & 24 deletions _docs/20_install-script/04_install.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Install Simple Analytics on other platforms
menu: Install on other platforms
category: install-script
permalink: /install-on-other-platforms
last_modified_at: 2026-10-17
last_modified_at: 2026-11-06
---

## Platform guides
Expand All @@ -12,16 +12,7 @@ We try to make installing Simple Analytics as simple as possible. We want privac

Read our guides on how to install Simple Analytics on:

- [Google Tag Manager](/install-simple-analytics-with-google-tag-manager) <small>(source on [GitHub](https://github.com/simpleanalytics/google-tag-manager#readme))</small>
- [Wordpress](/install-simple-analytics-on-wordpress) <small>(source on [GitHub](https://github.com/simpleanalytics/wordpress-plugin#readme))</small>
- [Ghost](/install-simple-analytics-on-ghost)
- [WIX](/install-simple-analytics-on-wix)
- [Squarespace](/install-simple-analytics-on-squarespace)
- [Webflow](/install-simple-analytics-on-webflow)
- [Jimdo Creator](/install-simple-analytics-on-jimdo-creator)
- [MailerLite](/install-simple-analytics-on-mailerlite)
- [GoDaddy](/install-simple-analytics-on-godaddy)
- [Netlify](https://app.netlify.com/extensions/simpleanalytics)
{% include install-platforms.md %}

Cloudflare has deprecated Cloudflare Apps, so you can no longer install our [Cloudflare App](/install-simple-analytics-on-cloudflare). Add [our script](/script) to your website instead.

Expand All @@ -36,18 +27,6 @@ For most frameworks, you can include the script. We magically track page views,

Get our official plugins for these frameworks:

- [React](/install-simple-analytics-with-react) <small>(package on [npm](https://www.npmjs.com/package/@simpleanalytics/react))</small>
- [Ruby on Rails](/install-simple-analytics-with-ruby-on-rails) <small>(source on [GitHub](https://github.com/simpleanalytics/rubyonrails-plugin#readme))</small>
- [Gatsby](/install-simple-analytics-with-gatsby) <small>(source on [GitHub](https://github.com/simpleanalytics/gatsby-plugin#readme))</small>
- [Vue](/install-simple-analytics-with-vue) <small>(source on [GitHub](https://github.com/simpleanalytics/vue-plugin#readme))</small>
- [VuePress](/install-simple-analytics-with-vuepress) <small>(source on [GitHub](https://github.com/simpleanalytics/vuepress-plugin#readme))</small>
- [Nuxt.js](/install-simple-analytics-with-nuxt) <small>(package on [npm](https://www.npmjs.com/package/@simpleanalytics/nuxt))</small>
- [Gridsome](/install-simple-analytics-with-gridsome) <small>(source on [GitHub](https://github.com/simpleanalytics/gridsome-plugin#readme))</small>
- [Django](/install-simple-analytics-with-django) <small>(source on [GitHub](https://github.com/simpleanalytics/django-plugin#readme))</small>
- [Analytics library](/install-simple-analytics-via-analytics-package) <small>(source on [GitHub](https://github.com/DavidWells/analytics/tree/master/packages/analytics-plugin-simple-analytics))</small>
- [Hugo](/install-simple-analytics-with-hugo) <small>(guide only)</small>
- [Next.js](/install-simple-analytics-with-next) <small>(package on [npm](https://www.npmjs.com/package/@simpleanalytics/next))</small>
- [Docusaurus](/install-simple-analytics-with-docusaurus) <small>(source on [GitHub](https://github.com/simpleanalytics/docusaurus-plugin#readme))</small>
- [Astro](https://github.com/simpleanalytics/astro-plugin) <small>(guide on GitHub)</small>
{% include install-frameworks.md %}

> Are you missing your favorite framework? [Let us know!](https://simpleanalytics.com/contact) Happy to create a plugin for you.
17 changes: 17 additions & 0 deletions _includes/install-frameworks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
- [React]({{ site.url }}/install-simple-analytics-with-react) <small>(package on [npm](https://www.npmjs.com/package/@simpleanalytics/react))</small>
- [Next.js]({{ site.url }}/install-simple-analytics-with-next) <small>(package on [npm](https://www.npmjs.com/package/@simpleanalytics/next))</small>
- [Vue]({{ site.url }}/install-simple-analytics-with-vue) <small>(source on [GitHub](https://github.com/simpleanalytics/vue-plugin#readme))</small>
- [Nuxt.js]({{ site.url }}/install-simple-analytics-with-nuxt) <small>(package on [npm](https://www.npmjs.com/package/@simpleanalytics/nuxt))</small>
- [VuePress]({{ site.url }}/install-simple-analytics-with-vuepress) <small>(source on [GitHub](https://github.com/simpleanalytics/vuepress-plugin#readme))</small>
- [Gatsby]({{ site.url }}/install-simple-analytics-with-gatsby) <small>(source on [GitHub](https://github.com/simpleanalytics/gatsby-plugin#readme))</small>
- [Gridsome]({{ site.url }}/install-simple-analytics-with-gridsome) <small>(source on [GitHub](https://github.com/simpleanalytics/gridsome-plugin#readme))</small>
- [Astro](https://github.com/simpleanalytics/astro-plugin) <small>(guide on GitHub)</small>
- [Docusaurus]({{ site.url }}/install-simple-analytics-with-docusaurus) <small>(source on [GitHub](https://github.com/simpleanalytics/docusaurus-plugin#readme))</small>
- [Hugo]({{ site.url }}/install-simple-analytics-with-hugo) <small>(guide only)</small>
- Jekyll <small>(add the script to the base layout, usually `_layouts/default.html`, just before `</body>`. With a theme gem, copy the theme's layout into `_layouts/` first)</small>
- Vite <small>(add the script to `index.html`, or add it with the [`transformIndexHtml`](https://vite.dev/guide/api-plugin.html#transformindexhtml) plugin hook)</small>
- [Ruby on Rails]({{ site.url }}/install-simple-analytics-with-ruby-on-rails) <small>(source on [GitHub](https://github.com/simpleanalytics/rubyonrails-plugin#readme))</small>
- [Django]({{ site.url }}/install-simple-analytics-with-django) <small>(source on [GitHub](https://github.com/simpleanalytics/django-plugin#readme))</small>
- [Laravel](https://github.com/simpleanalytics/laravel-package#readme) <small>(package on [Packagist](https://packagist.org/packages/simpleanalytics/laravel-package))</small>
- [Drupal](https://github.com/simpleanalytics/drupal-module#readme) <small>(source on GitHub)</small>
- [Analytics library]({{ site.url }}/install-simple-analytics-via-analytics-package) <small>(source on [GitHub](https://github.com/DavidWells/analytics/tree/master/packages/analytics-plugin-simple-analytics))</small>
15 changes: 15 additions & 0 deletions _includes/install-platforms.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
- [Google Tag Manager]({{ site.url }}/install-simple-analytics-with-google-tag-manager) <small>(source on [GitHub](https://github.com/simpleanalytics/google-tag-manager#readme))</small>
- [WordPress]({{ site.url }}/install-simple-analytics-on-wordpress) <small>(source on [GitHub](https://github.com/simpleanalytics/wordpress-plugin#readme))</small>
- [Ghost]({{ site.url }}/install-simple-analytics-on-ghost)
- [WIX]({{ site.url }}/install-simple-analytics-on-wix)
- [Squarespace]({{ site.url }}/install-simple-analytics-on-squarespace)
- [Webflow]({{ site.url }}/install-simple-analytics-on-webflow)
- [Framer](https://www.framer.com/marketplace/plugins/simple-analytics/) <small>(plugin on the Framer Marketplace)</small>
- [Jimdo Creator]({{ site.url }}/install-simple-analytics-on-jimdo-creator)
- [MailerLite]({{ site.url }}/install-simple-analytics-on-mailerlite)
- [GoDaddy]({{ site.url }}/install-simple-analytics-on-godaddy)
- [Netlify](https://app.netlify.com/extensions/simpleanalytics) <small>(turn it on per site, only for sites with a build step)</small>
- [Buttondown](https://buttondown.com/settings/integrations) <small>(turn on Simple Analytics under Integrations)</small>
- GitHub Pages <small>(add the script to the main template, like `_layouts/default.html` for Jekyll, see Jekyll below)</small>
- Google Sites <small>(limited: it runs the script in a sandbox, so page paths, referrers and UTM codes aren't tracked. Add it to every page with Insert, Embed, Embed code, with `data-hostname` set to a domain you added, because you can't add `sites.google.com`. Check each page sends a page view. To count every visit as `/`, [overwrite the path]({{ site.url }}/overwrite-path))</small>
- NodeBB <small>(drag an HTML widget with the script into the Global Footer, under Extend and Widgets)</small>
81 changes: 81 additions & 0 deletions install.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
layout: null
permalink: /install.md
sitemap: false
---
# Install Simple Analytics

How to add Simple Analytics, privacy-first analytics, to a website and check that it works. Written for AI agents, like Claude Code, Codex and Cursor, and for developers.

Came here from the Simple Analytics dashboard or its MCP tools? They gave you the hostname and the script for the website, use those.

## 1. Add the script

Add the script to every page, for example just before `</body>`. Replace `example.com` with the hostname of the website, as it's added in Simple Analytics:

```html
<!-- 100% privacy-first analytics -->
<script async data-hostname="example.com" src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
```

Always set `data-hostname`. Page views on localhost and on preview or staging URLs then count for the website, so you can test the script before the website is live. See [overwrite domain name]({{ site.url }}/overwrite-domain-name).

Does the website use a [custom domain]({{ site.url }}/bypass-ad-blockers) for Simple Analytics? Load the script from that domain instead: `https://<custom domain>/latest.js`.

Has the platform or framework a guide or plugin below? Use it instead of the script tag above, with the same hostname, so the script isn't added twice. Single-page apps don't need extra code, the script tracks page views when the URL changes. With hash routing (`/#/page`), add `data-mode="hash"`, see [hash mode]({{ site.url }}/hash-mode). Is the platform not listed? Add the script to the template or layout every page uses.

Hosted platforms:

{% include install-platforms.md %}

Frameworks:

{% include install-frameworks.md %}

All script settings, like `data-collect-dnt="true"`, are on [the script page]({{ site.url }}/script).

Is the website on the Free plan? It needs to show a [Simple Analytics badge]({{ site.url }}/free-plan-badge), in a footer on every page. Without it, we lock the dashboard data and API of the website after 14 days.

## 2. Content Security Policy

Does the website have a Content Security Policy? Add Simple Analytics to the directives it already has, also to `script-src-elem` when the policy has it. With `'strict-dynamic'`, hosts are ignored, so give the script tag the policy's nonce instead:

```
script-src https://scripts.simpleanalyticscdn.com;
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
connect-src https://queue.simpleanalyticscdn.com;
img-src https://queue.simpleanalyticscdn.com;
```

With a custom domain, allow that domain instead of both. The Free plan badge also needs `img-src https://simpleanalyticsbadges.com`. See [Content Security Policy]({{ site.url }}/csp).

## 3. Check that it works

1. Open a page with the script in a browser and find the `simple.gif` request, in DevTools or with the Chrome DevTools Protocol. Its `simple-analytics-feedback` response header says:
- `Thanks for sending this page view!`: page views work.
- `Thanks for sending this event!` or `Thanks for sending this additional data!` (sent when leaving a page): that request works, but also check the page view request.
- `Website not registered in Simple Analytics, dropping request`: the hostname that was sent isn't added to Simple Analytics, check `data-hostname`.
- `IP in excluded IP list for website`: the website settings exclude this IP address.
- Anything else explains what is wrong.
2. No `simple.gif` request? Check the console for `Simple Analytics:` warnings and Content Security Policy errors.
3. Never replay the `simple.gif` request with curl or other tools, it adds fake page views.

JavaScript on the page can't read this header. Server-side page views, like `trackPageview` in Next.js middleware, don't show up in the browser at all.

With access to Simple Analytics, through its MCP tools or a token the user approved, `check_installation` checks the live website and `get_recent_hits` shows the latest page views and events.

Headless browsers, like the ones AI agents use, count as robots. Simple Analytics stores robots but doesn't show them in the dashboard, so a test visit by an agent only shows up in the recent hits, marked as a robot.

If the recent hits show nothing, that doesn't mean the installation failed. A page view that got `Thanks for sending this page view!` is almost always stored, also when the website isn't added yet. Hits of new websites can take over an hour to show up.

## 4. Collect the right data

- **URL parameters:** we only keep UTM codes and `ref`. To collect another parameter, like `product-id`, add it to [`data-allow-params`]({{ site.url }}/allow-params) first. It's only collected from then on.
- **No personal data:** never put email addresses, names, user IDs or other personal data in paths, URL parameters, [events]({{ site.url }}/events) or [metadata]({{ site.url }}/metadata). It's not allowed, and the account might be suspended.
- **Missing data,** for example because of ad blockers? Set up a [custom domain]({{ site.url }}/bypass-ad-blockers), or even better the [proxy]({{ site.url }}/proxy).

## How the data works

- **Visitors are [unique pageviews]({{ site.url }}/explained/unique-visits),** not people. A page view is unique when it has no referrer or comes from another website. Simple Analytics uses no cookies or identifiers, so it needs no cookie banner. Other tools on the website might.
- **Each step of a [goal]({{ site.url }}/goals) counts the matching data on its own.** Visitors don't have to go through the earlier steps, so a later step can be higher than an earlier one.

Need help? See [our support channels](https://simpleanalytics.com/contact).
Loading