Skip to content

Update custom domain certificate documentation #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
simple-analytics-ai wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update custom domain certificate documentation #52

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 11 additions & 9 deletions _docs/30_features/20_bypass.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Bypass ad-blockers
category: features
permalink: /bypass-ad-blockers
last_modified_at: 2022-04-14
last_modified_at: 2026-09-10
---

Simple Analytics never collects any personal identifiable information. Ad-blockers see us just any other analytics company and some of the ad-blockers are blocking our domain as a result. To prevent your stats being blocked as a result we allow you to setup a bypass. This basically hides Simple Analytics' server name from the browser by redirecting a subdomain to our domain.
Expand All @@ -17,25 +17,27 @@ We cannot stress this enough, if you want the best ad-blocker bypass, set up [ou

You only need access to your DNS to set this up. Add a CNAME record to your DNS pointing to `simpleanalyticsexternal.com` and fill in your full domain in [your website settings](https://simpleanalytics.com/select-website/settings#bypass-ad-blockers). We advise to choose a domain like `api.example.com` instead of `track.example.com` _(tracking, analytics, collect, and similar keywords are usually blocked)_.

You will need to enable the record in [your website settings](https://simpleanalytics.com/select-website/settings#bypass-ad-blockers) on Simple Analytics. We need to know this to request a certificate with <a href="https://letsencrypt.org/" target="_blank">Let's Encrypt</a>. This means your analytics will travel safe via HTTPS to our servers.
Add the CNAME record before you save the domain in [your website settings](https://simpleanalytics.com/select-website/settings#bypass-ad-blockers). We check that the record points to `simpleanalyticsexternal.com` and show a warning if it does not. If you see the warning, check the CNAME target, wait for the DNS change to propagate, and save the domain again to retry the check. DNS changes can take a few minutes to propagate.

<img class="border" src="https://assets.simpleanalytics.com/docs/instructions/custom-domain-cloudflare-dns.png" alt="Add Simple Analytics custom domain to CloudFlare DNS">
Existing CNAME records pointing to `external.simpleanalytics.com` or `external.simpleanalytics.io` are also supported.

> If you are using <img src="https://cdn.simpleanalytics.com/images/cloudflare-icon.png" style="height: 10px; margin: 0 3px;" alt=""> CloudFlare, make sure to disable the orange cloud.
<img class="border" src="https://assets.simpleanalytics.com/docs/instructions/custom-domain-cloudflare-dns.png" alt="Add Simple Analytics custom domain to Cloudflare DNS">

> If you are using <img src="https://cdn.simpleanalytics.com/images/cloudflare-icon.png" style="height: 10px; margin: 0 3px;" alt=""> Cloudflare, set the record to **DNS only** (the gray cloud). Proxied records hide the CNAME target, so our check cannot verify it.

## Check if SSL works

After you save the domain and the DNS check passes, we automatically make an HTTPS request to your custom domain to start certificate issuance with <a href="https://letsencrypt.org/" target="_blank">Let's Encrypt</a>. Certificates are issued on the first HTTPS connection that needs one, so this first request can take a few seconds. This keeps your analytics traffic encrypted via HTTPS.

Check if your custom domain page shows at `https://custom.domain.com`. It should show something like this:

<img class="border" src="https://assets.simpleanalytics.com/docs/custom-domain/custom-domain-page.png" alt="Placeholder page for custom domain">

If you get an SSL error, please hit refresh in your [website settings](https://simpleanalytics.com/select-website/settings#bypass-ad-blockers):

<img class="border" src="https://assets.simpleanalytics.com/docs/custom-domain/check-ssl-certificate.png" alt="Check SSL certificate in website settings">

@adriaandotcom adriaandotcom Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why does it delete this image?

If you get an SSL error, try opening the domain again after a few seconds. You can inspect the certificate with our [SSL checker](https://simpleanalytics.com/check-ssl), also linked as **Check SSL certificate** in your website settings. If the error persists, verify your DNS record and save the domain again in your website settings to retry.

## Update your script

Include these two lines at the end of your `<body>` (or anywhere else):
Replace your existing Simple Analytics script with this script at the end of your `<body>` (or anywhere else):

<!-- prettier-ignore -->
```html
Expand All @@ -46,4 +48,4 @@ Make sure to replace `custom.domain.com` with your own custom domain.

## Multiple websites

You can use one custom subdomain for all your websites. Make sure to link it to at least one domain via [your website settings](https://simpleanalytics.com/select-website/settings#bypass-ad-blockers). If you add the custom domain to one website we know which SSL certificates need renewal and which ones we can delete. Using one custom domain for multiple websites does not effect performance. It will be running through the same infrastructure.
You can use one custom subdomain for all your websites. Keep it linked to at least one website via [your website settings](https://simpleanalytics.com/select-website/settings#bypass-ad-blockers) so we can authorize certificate issuance for that domain. Certificates are renewed automatically. Using one custom domain for multiple websites does not affect performance. It will be running through the same infrastructure.
4 changes: 3 additions & 1 deletion _docs/31_integrations/00_react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Install Simple Analytics with React
hidden: true
category: integrations
permalink: /install-simple-analytics-with-react
last_modified_at: 2026-06-24
last_modified_at: 2026-09-10
---

Add Simple Analytics to React apps with our official React package.
Expand Down Expand Up @@ -39,6 +39,7 @@ Most React component options map directly to Simple Analytics script settings. B
The script is injected once. Add these options when you render `<SimpleAnalytics />`; changing them after the script has loaded will not reconfigure the existing script.
For example, you can collect visits from browsers with Do Not Track enabled, ignore a few metrics, and allow extra URL parameters:

{% raw %}
```tsx
<SimpleAnalytics
collectDnt
Expand All @@ -49,6 +50,7 @@ For example, you can collect visits from browsers with Do Not Track enabled, ign
allowParams={["product-id", "article-slug"]}
/>
```
{% endraw %}

### Available options

Expand Down