v5.3.1

Important

If you're updating to this version from v5.2.x, please read the release notes for the v5.3.0 release as it contains important migrations you'll need to do.

🔧 Fixes

• Fix failing backend build

v5.3.0

Warning

This release includes breaking changes for self-hosted installations.

If you are upgrading from Swetrix CE v5.2.x, you must update your configuration and run the database migration below. Please read the upgrade instructions carefully before starting, otherwise your installation will not work correctly.

🔥 Major updates

SEO analytics

1. Added position analytics, including an impressions-by-position breakdown and an organic positions time series, available as two new SEO chart panels.

2. Added the ability to compare SEO stats against previous or custom periods.

CAPTCHA

1. Added Auto mode, which dynamically selects the challenge difficulty using privacy-safe risk signals, such as short-lived project traffic spikes, country-level spikes, replay attempts, and more. Learn more.

2. Instead of only tracking successful CAPTCHA completions, we now track the full CAPTCHA lifecycle, including events like generated, passed, failed, validation failed, replay, and more. These events are visible on the main chart in your CAPTCHA dashboard:

We also added more dashboard metrics, including Challenge status, CAPTCHA difficulty, and Average solve time, so you can understand how your CAPTCHA is performing and adjust it based on real data:

Profiles & Sessions

The Profiles and Sessions tabs have been fully redesigned to present data in a cleaner, more useful way. Inspecting user profiles is now easier too: the profile view now includes expandable session dropdowns, so you can view each session’s page flow and navigate directly to it.

Experiments

1. Added a Hypothesis field, a planning metrics calculator, and launch guardrails to help you estimate experiment metrics before starting.
2. Completed experiments now automatically select the time period from start to end. Previously, if an experiment completed 3 months ago and you selected the last 7 days, the results could incorrectly show a 50/50 split.
3. Added UI improvements, including a better completion flow, linked-flag badges, a cleaner experiments list, and more.

🙂 Minor changes

• Added a new UI language: 🇧🇷 Brazilian Portuguese.
• Unified saved segments and filters across tabs. If you apply a filter that is not supported by another tab, such as filtering by UTMs on the Traffic tab and then switching to the Performance tab, you will now see an indicator showing that the filter is not currently used.
• Added the collapsed option to dashboard embedded mode.
• Improved Feature Flags with scheduling, kill-switch overrides, richer statuses, staleness reasons, and a cleaner UI.
• Rework "Project reset" feature - now it's easier to delete spam traffic by specific filters or patterns
• Displayed the last used authentication method on the sign-in page.
• Added support for comparing against the previous period in the Performance view.
• Requiring the current password is now mandatory when changing your password in user settings.
• Added filter support for Goals and Funnels.
• Goals now display conversion insights, such as "From session start" and "From first page", in addition to the conversion chart.
• Added session drilldown to Performance and Errors charts. You can click any point on the chart to view the sessions from that period.
• Added weekdays to day-bucket chart tooltips, for example, "Tue, 26 May".
• Funnels now reuse the same design patterns as Goals. They are displayed as cards on the same page, and each funnel can be opened by clicking its card.
• The <noscript> tracking endpoint now calculates the visited page from the referrer when available.
• Changed the bounce rate calculation formula to single-page sessions / total sessions * 100.
• Added app-wide UI and UX improvements, including autosaving settings on change, better inputs and selectors, infinite scroll, and more.
• Improved the Umami importer mapper, including ie -> Internet Explorer, better OS version detection, and more.
• Reduced project code dependencies.

🔧 Fixes

• Fixed password-protected projects showing empty dashboards to unauthorised people using project passwords.
• Fixed experiment exposure percentages showing 100% only when exposures were greater than 0.
• Fixed fresh sessions sometimes being marked as "Unknown user" on the Sessions list page.
• Fixed Plausible Analytics imports crashing or getting stuck in a permanent "Pending" status.
• Fixed timezone bucket alignment in session drilldown.
• Fixed incorrect sorting behaviour in Analytics reports > Panels.

Upgrading to Swetrix CE v5.3 from v5.2.x

Important

This upgrade requires a database migration.

Before running the migration, make sure you have a recent backup of your data. This helps prevent data loss if something goes wrong during the upgrade.

1. Update your Swetrix services

Before running the migration, update your compose.yaml file to use the latest Swetrix CE v5.3 images:

• frontend: swetrix/swetrix-fe:v5.3.1
• backend: swetrix/swetrix-api:v5.3.1

Also make sure your compose.yaml includes the latest self-hosting dependency versions from this release, including the updated ClickHouse image.

Then pull and start the updated services from your selfhosting directory:

docker compose pull
docker compose up -d

2. Run the database migration

Once the updated containers are running, execute the migration script from your selfhosting directory:

docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_05_05_experiments.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_05_20_captcha_auto_difficulty.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_05_20_goal_conditions.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_05_24_feature_flag_operations.js
docker compose exec swetrix-api node migrations/clickhouse/2026_06_03_session_replays.js

If the command finishes without any Query ERROR messages, the migration completed successfully. Please don't worry if the migration takes long to execute - it depends on how much data you have accumulated.

3. Restart Swetrix

After the migration has completed, restart your services:
docker compose restart

Swetrix CE v5.3 should now be ready to use.

That's it, enjoy self-hosting Swetrix! Join our Discord community for updates and discussions.

tracker-js@4.4.0

🔥 Major updates

• Improved Session Replay reliability in startSessionReplay.
  Replays can now stay continuous across page loads and navigations by using the backend-provided replay ID and next chunk index.

• Optimised Session Replay capture size and upload behaviour.
  Added byte-based replay limits with maxBytesPerChunk and maxBytesPerEvent, safer default rrweb sampling, and slimmer DOM capture defaults to reduce large replay payloads.

• Added new Session Replay privacy controls.
  You can now use maskAllText to mask text outside of total privacy mode, and recordIframes to explicitly opt into iframe recording when needed.

Fixes

• Fixed Session Replay chunk ordering after navigation or reload.
• Reduced the chance of oversized replay events being uploaded.

tracker-js@4.3.0

🔥 Major updates

• Added Session Replay support via startSessionReplay.
  You can now record and replay user sessions to better understand user behavior, debug UX issues, and investigate how visitors interact with your product.

🙂 Minor changes

• Updated dependencies

captcha@2.3.0

🔥 Major updates

• Swetrix Captcha now can be installed & used via NPM. Learn more.

🙂 Minor changes

• Add Hungarian language support (thanks to @AndrisBorbas)

🔧 Fixes

• fix: Remove some logs that were always printed in console

v5.2.2

🔧 Fixes

• fix: Frontend crashes on 2FA QR-code generation (thanks to @Sturdzza for contributing)
• fix: Sessions view is empty when there are custom events applied as filters

v5.2.1

Important

If you're updating to this version from v5.1.x, please read the release notes for the v5.2.0 release as it contains important migrations you'll need to do.

🔧 Fixes

• Fix failing frontend build

v5.2.0

Warning

This release includes breaking changes for self-hosted installations.

If you are upgrading from Swetrix CE v5.1.x, you must update your configuration and run the database migration below. Please read the upgrade instructions carefully before starting, otherwise your installation will not work correctly.

🔥 Major updates

Import historical data from 3rd party analytics services

Swetrix allows you to import historical analytics data from other platforms so you can switch without losing your history. Imported data appears alongside your live-tracked data in dashboards, charts, and reports. It's tagged internally so it can be identified and, if needed, removed later without affecting your live-tracked data.

In this release, the following providers are supported for import:

• Google Analytics 4
• Fathom Analytics
• Plausible Analytics
• Simple Analytics
• Umami

👉 Learn more about this feature on our Data Import documentation page.

Shout out to @prohtex for the suggestion.

SEO insights & Google Search Console integration

The SEO dashboard gives you a complete view of your website's search engine performance, powered by your the Google Search Console integration. It combines GSC data with your referral analytics to show search queries, top pages, branded traffic, and optimisation opportunities - all in one place.

👉 Learn more about the SEO dashboard, and the set-up instructions for Swetrix CE.

Experiments (A/B testing)

Experiments (A/B Testing) allow you to test different variations of your application to see which one performs better. You can use experiments to optimize conversion rates, user engagement, and other key metrics.

👉 Learn more about Experiments.

Bot blocking controls

Swetrix automatically filters out automated traffic so the numbers in your dashboard reflect real visitors. In previous versions we've offered basic bot protection that worked by utilising user-agent matching against common crawlers & bots.

This release introduces Strict level bot protection, that does additional checks against the following attack vectors:

• User-Agent checks: We match the User-Agent header against a comprehensive list of known bots (Googlebot, Bingbot, AhrefsBot, curl, headless tools, etc.) maintained by the isbot project.
• Headless browser fingerprint: Headless and automation frameworks like HeadlessChrome, Puppeteer, Playwright, etc.
• Suspicious headers checks: Real browsers always send Accept, Accept-Language, and Accept-Encoding headers. If two or more of these are missing on a pageview, custom event, error, or heartbeat request, the request is treated as a bot.
• Vulnerability-scan paths (probe paths): Ignore crawlers that search for hidden dotfiles (/.env, /.git/config, etc.), server internals, build / config leaks or common scanner probes.
• Referrer spam checks: We maintain a snapshot of the matomo-org/referrer-spam-list (~2,300 known spam hosts). If the request's Referer (or Origin) matches any of those hosts, or is a subdomain of one, the request is dropped.
• Datacenter IP checks: Ignores traffic that comes from cloud / hosting providers (AWS, GCP, OVH, Hetzner, etc.) - since usually most of this traffic are bots or scrapers. This feature requires a paid IP Geolocation database to work on Swetrix CE. This feature is available to all Cloud customers.

Additionally to these checks, we've also added a per-project report of exactly how many requests were blocked and why.

👉 Learn more about the bot protection feature.

Improved funnels

Funnels now display Top sources and Top countries for every step, as well clearer conversion rates and drop off.

You can also click on any funnel step to see the sessions that got into this step, allowing you to investigate them further and understand why they dropped off.

Click on chart to see sessions of this period

Similarly to funnels, you can click on any data point on the main chart to pull up a detailed list of all sessions that occurred during that specific timeframe. This is an excellent way to drill down into the behavior of individual visitors on a given day or hour.

You can go further and click on any of those sessions to see how long it lasted, what pages were visited, error occured and why they dropped off.

🙂 Minor changes

• Stored 2FA recovery codes are now hashed
• New Swetrix logo
• User password is not required to delete the account
• [Swetrix CAPTCHA] Add Hungarian language support (thanks to @AndrisBorbas)
• In line with recent surge of NPM supply chain attacks, we've reduced the amount of non-essential dependencies
• Add password strength meter to the signup and user settings pages
• Migrate i18n from ?lng= query to /{lang}/ path-based URLs
• Reduce 'Direct / None' referrers by inferring it from UTMs as a backup
• Added 'Network intelligence' feature, which detects ISP, Usage type and similar metrics. Only available if you pass a custom paid IP geolocation model. Right now it's hidden in the UI.
• App-wide UI improvements - better colours, typography, accessibility. Made some components like sessions or error tracking UI more clean and minimal.

🔧 Fixes

• fix: HTTP exception when user applied custom event related filters on an All time period
• fix: Use cancellable billboard resize timer to avoid post-destroy errors
• fix: Analytics dashboard -> Details modal is hard to read on mobile
• fix: Shared project admins are not able to manage project members
• Feature flags evaluation fixes & improvements
• Stylistic fixes to the dashboard when it's rendered in embedded mode

Upgrading to Swetrix CE v5.2 from v5.1.x

Important

This upgrade requires a database migration.

Before running the migration, make sure you have a recent backup of your data. This helps prevent data loss if something goes wrong during the upgrade.

Important

Swetrix CE v5.2 also updates the self-hosting Docker configuration.

If you installed Swetrix by cloning the selfhosting repository, run git pull in your selfhosting directory to get the latest compose.yaml. If you maintain your own copy of the file, update the image versions manually.

Existing installations must also add a non-empty ClickHouse password to .env:

CLICKHOUSE_PASSWORD=your-random-password-here

The value can be any strong random password. Keep the same value in .env; Docker Compose passes it to both ClickHouse and the Swetrix API.

1. Update your Swetrix services

Before running the migration, update your compose.yaml file to use the latest Swetrix CE v5.2 images:

• frontend: swetrix/swetrix-fe:v5.2.1
• backend: swetrix/swetrix-api:v5.2.1

Also make sure your compose.yaml includes the latest self-hosting dependency versions from this release, including the updated ClickHouse image.

Then pull and start the updated services from your selfhosting directory:

docker compose pull
docker compose up -d

2. Run the database migration

Once the updated containers are running, execute the migration script from your selfhosting directory:

docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_03_31_data_import.js
docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_04_28_gsc.js
docker compose exec swetrix-api node migrations/clickhouse/2026_03_19_isp_network.js
docker compose exec swetrix-api node migrations/clickhouse/2026_03_31_import_id.js
docker compose exec swetrix-api node migrations/clickhouse/2026_04_26_bot_blocks.js
docker compose exec swetrix-api node migrations/clickhouse/2026_05_01_captcha_remove_manually_passed.js
docker compose exec swetrix-api node migrations/clickhouse/2026_05_01_unify_events.js

If the command finishes without any Query ERROR messages, the migration completed successfully. Please don't worry if the migration takes long to execute - it depends on how much data you have accumulated.

3. Restart Swetrix

After the migration has completed, restart your services:
docker compose restart

Then go to your Swetrix dashboard and make sure that your data is intact and that it's working properly.

If everything is looking good, please run the following migration:

docker compose exec swetrix-api node migrations/clickhouse/2026_05_04_drop_legacy_tables.j...

tracker-node@3.2.0

Changelog:

• Add a new query string (qs) parameter to trackViews and track methods, that's being used to properly identify referrers if they're not set (to reduce the amount of Direct / None you can see in the traffic sources of the dashboard). Learn more.

tracker-js@4.2.0

Changelog:

• Add a new query string (qs) parameter to trackViews and track methods, that's being used to properly identify referrers if they're not set (to reduce the amount of Direct / None you can see in the traffic sources of the dashboard). Learn more.