v5.4.0

Important

This release requires a database migration for existing self-hosted installations. Please read the upgrade instructions at the bottom of these release notes. If you're upgrading from v5.2.x, please also read the v5.3.0 release notes first.

🔥 Major updates

Visitor identification & profile traits

You can now identify visitors with your own user IDs. Call identify() from the tracking script and Swetrix links the visitor's anonymous activity to a persistent usr_ profile, so you can look up a specific user in your dashboard and see their sessions, page flow and events across visits and devices. Activity recorded before someone signs in is merged into their identified profile automatically.

You can also attach traits (arbitrary key/value metadata like email or plan) to identified profiles, and they're displayed in the profile view.

Identification is supported in swetrix-js v4.5.0 and @swetrix/node v3.3.1. Learn more.

Stats API v2

We've added a new versioned read API for your analytics data. It provides per-dimension endpoints (pages, referrers, countries, UTMs and so on), summary and chart data, live visitors, and covers experiments and goals too. The dashboard itself now runs on the v2 API. Learn more.

Journeys

User journeys have been reworked. Step percentages are now calculated correctly, multi-step journeys no longer produce misleading numbers, and the chart itself got a cleaner design with tooltip and layout fixes. The legacy "User flow" feature has been removed in favour of journeys.

Live visitors over time

The chart can now visualise how many visitors were on your site at the same time, so you can see concurrency spikes rather than just a single "live visitors" number. Learn more.

IP whitelist

You can now whitelist IP addresses to bypass bot protection. This is useful if your own infrastructure, uptime monitors or office network were being filtered out as automated traffic.

🙂 Minor changes

• Added a one-click Railway deploy option for the Community Edition. Thanks to @dillonstreator for the contribution!
• Sessions and profiles now display ISP details.
• Custom events: dropdowns are now searchable, and event metadata can be viewed directly in the regular panel view instead of only in the details modal.
• Added infinite scroll to the details modal.
• Added browser detection for TikTok and Twitter in-app browsers.
• The self-hosted API URL setting now displays its default value.
• Updated the tracking script to v4.5.0, which uses keepalive requests, so events fired right before a page closes are no longer lost.
• Analytics dashboard performance improvements.
• Improved mobile UI and accessibility across the dashboard.

🔧 Fixes

• Fixed password-protected dashboards not working when embedded as an iframe.
• Fixed the summary cards overcounting pageviews for custom date ranges in non-UTC timezones.
• Fixed a page crash when opening sessions containing custom events in the profile inspector.
• Fixed client IP detection behind reverse proxies: X-Forwarded-For is now preferred over X-Client-IP-Address, so proxied visitors are no longer misclassified as datacenter traffic by bot protection.
• Fixed missing panel loading indicators and page layout shifts while panels load.
• Fixed inflated average session duration due to how we calculated sessions start / end. Now, a session ends after 30 minutes of inactivity, and if user visits again after that time period - it will be counted as a separate session.
• Security hardening: added SSRF protections for outbound requests and stricter validation on analytics endpoints.

Upgrading to Swetrix CE v5.4 from v5.3.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

Update your compose.yaml file to use the latest Swetrix CE v5.4 images:

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

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 scripts from your selfhosting directory:

docker compose exec swetrix-api node migrations/clickhouse/selfhosted_2026_07_12_ip_whitelist.js
docker compose exec swetrix-api node migrations/clickhouse/2026_07_17_profile_aliases.js
docker compose exec swetrix-api node migrations/clickhouse/2026_07_28_profile_traits.js
docker compose exec swetrix-api node migrations/clickhouse/2026_08_01_session_id.js

If the commands finish without any Query ERROR messages, the migration completed successfully. Fresh installations don't need to run these - the database initialiser creates everything automatically.

3. Restart Swetrix

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