2025

​

🚀 Usertour v0.4.6

​

✨ Highlights

• Builder save reliability improved (unsaved warnings, fast-click save fix)
• Launch rules UX optimized (auto-expand, checklist support)
• Analytics accuracy improved (step stats now keyed by cvid)
• WebSocket v2 hardened (throttling, validation, deadlock fixes)
• Environments now support Primary setting

​

🧩 Builder & UX

• Unsaved changes warning when navigating back
• Back button & auto-save behavior optimized
• Copy / duplicate content fixes
• Missing or invalid configs now show explicit errors
• SDK & Builder UI consistency fixes

​

🚀 Rules & Conditions

• Checklist supported in launch rules
• Rule selection now opens config immediately
• Rules evaluator rewritten with cache isolation
• Date conditions now support common presets

​

📊 Analytics

• Step funnel & completed step icon fixed
• Tooltip missing data issues resolved

​

🔌 SDK, Embed & WebSocket

• WebSocket throttling, param validation, and better logging
• Prevented potential WebSocket deadlocks

​

🔐 Auth & Infra

• Login flow improved with refresh token support
• Removed Google Analytics from app

​

✨ Improvements

• Enhanced Docker production environment
  • Added NODE_ENV=production environment variable by default, ensuring proper production mode operation.
  • Updated CMD instruction to shell form for proper stdout/stderr log flushing, improving container log visibility.
• Improved database migration reliability
  • Added automatic retry mechanism for database migrations with configurable attempts via DB_MIGRATE_RETRIES environment variable (default: 3 retries).
  • Migration failures now provide clearer error messages and graceful retry handling.
• Optimized Docker file structure
  • Reorganized startup scripts to /app/scripts/ directory for better maintainability.

​

🐛 Bug Fixes

• Fixed compatibility with numeric userId / companyId. The SDK now properly handles number types by converting them to strings automatically.

​

✨ Improvements

• Optimized exception handling in the SDK Improved error clarity and reliability across various SDK operations.
• Enhanced Docker experience
  • Added default PORT and NEST_SERVER_PORT environment variables in the Dockerfile, so most users no longer need to configure them manually.
  • Improved port handling and startup checks to avoid conflicts and provide clearer logs.

​

🐛 Bug Fixes

• Socket Reconnection Handling – Fixed an issue where the SDK would fail silently when the initial WebSocket connection failed. The SDK now waits for Socket.IO automatic reconnection instead of giving up on the first error, ensuring proper initialization after network recovery.
• Connection Promise Caching – Added connection promise caching to prevent duplicate connection attempts when identify() is called multiple times in quick succession for the same user.
• Timer Management – Unified all timer operations to use timerManager, ensuring proper cleanup when reset() is called and preventing memory leaks.

​

🐛 Bug Fixes

• Conditional Usertour Initialization – Added a check to ensure userTourToken exists before calling usertour.init() and usertour.identify(). This prevents initialization errors in environments where the Usertour token is not configured.

​

🛠 Dev & Infrastructure

• Multi-Architecture Docker Build Support – Docker images now support building for multiple architectures (x86_64, ARM64) without manual configuration.
• Dynamic Prisma Client Generation – Prisma Client is now generated at build time rather than relying on hardcoded binary targets, ensuring correct binaries for the target platform.
• Simplified Prisma Configuration – Removed binaryTargets from schema.prisma, allowing Prisma to auto-detect the correct platform during build.
• Improved Dockerfile – Added OpenSSL dependencies in the build stage for proper version detection; streamlined runtime dependencies.
• Cleaner docker-compose.yml – Removed platforms restriction and PRISMA_BINARY_PLATFORM environment variable for better cross-platform compatibility.

​

🚀 Core Architecture Upgrades

• Rewritten SDK & WebSocket Core – Usertour.js and the real-time layer have been fully rebuilt to better leverage Socket.IO, enabling more reliable real-time communication.
• Multi-Tab Sync – Launcher, flows, and UI state are now synchronized across browser tabs. Showing or closing content in one tab instantly reflects in others.
• Smarter Reconnect & Dedup Logic – Network reconnection and edge-case handling have been significantly improved to avoid repeated execution and inconsistent UI states.
• Centralized Timer Manager – Introduced a timerManager to manage all setTimeout, setInterval, and heartbeat checks in one place, improving performance and stability.

​

✅ Checklist & Launcher Improvements

• Always-Update Content – Checklist and Launcher now always load the latest published version. Once published, users see the newest content without manual refresh.
• Checklist Session Snapshots – Session details now include checklist snapshots (hidden, clicked, and completed states for each item).
• Auto Dismiss Countdown – When checklist auto-dismiss is enabled, a live countdown progress bar is now displayed.

​

🎨 Editor & Theme Fixes

• Fixed an issue where Backdrop opacity could not be edited.
• Fixed an issue where Highlight type changes were not saved correctly.

​

🔄 Flow & Versioning Behavior

• Smart Version Checking – When starting a flow, the system now compares the latest published version with the active session version. If they don’t match, a fresh session is created using the latest version.
• Improved Element Matching – Flow targeting rules are now more reliable when DOM elements change dynamically.

​

🛠 Dev & Infrastructure

• Added REDIS_USER to .env.example for clearer Redis configuration.
• Improved EMAIL_SENDER documentation for better setup clarity.
• Added detailed emit-with-ack timing logs to improve observability.
• Multiple UX improvements and internal refactors.

​

🐞 Bug Fixes

• Fixed issues related to published version updates.
• Fixed edge cases that could cause released versions to be overwritten.
• Fixed incorrect theme display behavior during rename operations.

• Remove the “Temporarily hide” feature from Launcher
• Rename Auto-start launcher if… → Show launcher if…
• Updated logic: Show the launcher if the user matches the given condition. If the user doesn’t match the condition, the launcher will not be displayed.
• Improved flow rule evaluation when elements change
• Optimized Launcher element detection — now uses the same mechanism as Flow, resulting in more accurate targeting

• Update env example by @winter100004 in https://github.com/usertour/usertour/pull/220
• Update .env.example by @winter100004 in https://github.com/usertour/usertour/pull/221
• Fix password error message by @winter100004 in https://github.com/usertour/usertour/pull/223
• Enhance docker-compose configuration with health checks by @winter100004 in https://github.com/usertour/usertour/pull/224

​

🚀 Usertour v0.3.1 — Smarter license support, better caching

​

✨ New Features

​

🛠 Improvements

​

✨ New Features

• Report WebSocket session metrics in real time
• Trace request flows across your system
• Easily integrate with Grafana, Prometheus, and more

​

🛠 Improvements

​

🐞 Bug Fixes

• No more duplicated analytics calls when using WebSocket events
• Stability improvements across all real-time interactions
• Edge case handling for license validation and missing keys

​

✨ New Features

• Conditional Variations by Theme Usertour now supports conditional content variations based on the active theme. You can target light vs dark modes, or use user traits and URL rules — perfect for adapting your experience visually.
• Smarter Content Refresh & Requests We’ve optimized how usertour.js fetches and syncs content:
  • Fewer network requests
  • Faster response between steps
  • Smoother transitions on click

​

🛠 Improvements

• WebSocket Performance Boost
  • Combined multiple fetches into one parallel call
  • Reduced response time on session analytics
  • Cleaner query syntax under the hood
• UI/UX Polishing
  • Better loading and disabled states after deletion actions
  • Fewer awkward moments when waiting for UI updates
• Developer Quality of Life
  • Avatar fallback fixes in environment switcher
  • Improved session navigation with wrapped links

​

🐞 Bug Fixes

• No more unnecessary listContents requests on SendEvent
• Segment filtering is now rock-solid

​

🙌 Shoutout

​

🚀 New Features

• Flexible Progress Bar Styles – You can now choose from 5 types of tooltip progress bars by setting the theme:
  • Narrow Progress Bar
  • Chain (Rounded or Squared)
  • Dots
  • Numbered (1 of 3) These options let you better match your product’s style and vibe.
• Auto Dismiss for Checklists – Add autodismiss to your checklist. When users complete all items, the checklist will auto-close — no clicks required.
• Smarter Flow Logic – Temporarily hidden content no longer blocks other flows from starting. This makes auto-started content more predictable and reliable.
• User & Company Session Lists – You can now view a user’s session history, and also see all members under a company. Super helpful for debugging or analytics.

​

🛠 Improvements

• Replaced all toast notifications with [Sonner](https://sonner.emilkowal.ski/) for a cleaner, more modern feel.
• Improved SDK component performance and animations.
• Loading states and spinners added for a smoother experience in detailed content views.
• Segment loading and filtering logic fully optimized.

​

🐞 Bug Fixes

• Fixed an issue where segment filtering caused incorrect results.
• Resolved bugs related to checklist progress bar display and default behavior.

​

🚀 New Features

• New Animations – Tooltips now include smooth docking transitions. Checklists come with a completion animation and will automatically expand when users complete an item, creating a more dynamic experience.
• Flow + Checklist = Infinite Logic – We’ve enhanced how flows and checklists can work together. You can now build complex, multi-branch onboarding logic using a mix of flows and checklists — flexible enough to cover almost any use case.
• Push-based Updates – Usertour.js no longer relies on polling to fetch content. Instead, we now use Socket.IO to push real-time updates to users — including modals, surveys, and checklists. It’s faster, lighter, and smarter.
• 🔁 Start From a Specific Step – When triggering a flow from inside another flow or checklist, you can now choose which step to start from — not just the first step. This gives you more flexibility in designing contextual onboarding.

​

🎨 UX & Interaction Improvements

• Improved all loading and debounce logic across the app for smoother data handling.
• Reworked several core components to drastically improve the interactive experience.
• Added confirmation modal when dismissing incomplete checklists (fully completed ones dismiss instantly).
• Fixed checklist launcher sizing issues.
• Optimized checklist item interactivity and launcher visuals.

​

🐞 Bug Fixes

• Fixed an issue where attribute selectors could make the page unclickable.
• Added try-catch around eval() usage to prevent runtime crashes caused by malformed logic.
• Fixed flow startup rule behavior when used with checklists and branching flows.

​

🚀 New Features

• Programmatic Flow Start – Added a start() method to trigger flows, checklists, or guides on demand. Great for custom triggers like a “Replay Tutorial” button in your app.
• Self-hosted Mode Member Invites – Now you can invite team members when using Usertour in self-hosted mode.

​

🐞 Bug Fixes

• Improved error handling on the startup rules page — invalid or missing rules won’t auto-save and now show clear error messages.
• Fixed flow activation and deactivation issues related to startup rules.
• Added exception handling to the list-content API to prevent crashes from misconfigurations.

​

🎨 Improvements

• Enhanced editor default placeholder text for a smoother editing experience.

​

🚀 New Features

• Project-level content support – Content is no longer tied to a single environment. Now, the same content (and its versions) can be published to different environments within the same project. This better matches a typical developer release workflow — for example: ➤ Publish to development → ➤ Verify in staging → ➤ Release to production. Content sessions, users, companies, segments, and analytics remain isolated per environment, so your data stays clean and separate.

​

🐞 Bug Fixes

• Fixed an issue where segment filtering could cause infinite request loops.
• Fixed the OpenAPI end session endpoint, which previously could not be used properly.

​

🔁 Removals

• Removed the “cross-environment content duplicate” feature, as it’s no longer necessary under the new project-level content model.

​

🚀 What’s New

• Flow session support in Usertour.js – Flows and checklists now remember where users left off. If they don’t finish, they can pick it up later—seamlessly.
• Cross-page flows – Start a tour on one page and continue it on another—even in a new browser tab.
• Hidden steps – Use invisible steps to create more dynamic flows while keeping the experience clean and focused.
• User data deletion – You can now fully delete user data, reset flow sessions, or dismiss flows for everyone with just a few clicks.

​

🎄 Improvements

• Major docs update! We rewrote most of the documentation and added video walkthroughs to help you get up and running faster.

​

🐞 Fixes

• Fixed company field handling in the SDK.
• Improved URL matching for better targeting accuracy.
• Survey limits now work as expected.
• Cleaned up and refactored code for improved clarity and performance.

​

📊 New Contributors

• Big thanks to @winter100004 for contributing across the board on this release!

​

🚀 New Features

• Launched the completed REST API, allowing you to synchronize your user data with Usertour and track events directly from your back-end application.
• Added company segment support in startup rules, enabling content display control based on the company.

​

🎄 Enhancements

• Added Prisma direct URL configuration, allowing support for PgBouncer and other Postgres proxies in production environments.
• Added WebSocket URI path configuration, allowing the use of a given wsUri to handle full URLs with protocol, just domain, and relative path.

​

🐞 Bug Fixes

• Fixed the spelling of “Acount” to “Account” in the admin user navigation.

​

📊 New Contributors

• @omari58 made their first contribution in [#71](https://github.com/usertour/usertour/pull/71)

• Added support for surveys (Multi Line Text, Single Line Text, Multiple Choice, Star Rating, Scale, NPS) by @winter100004 in #51
• Flow analytics now support surveys and session detail viewing by @winter100004 in #51

• Added height parameter by @devcodes9 in #43
• Added content type for duplication feature by @devcodes9 in #49
• Version updated to 0.1.9 with display height label in embed by @winter100004 in #45

• Fixed step trigger activation and jump behavior by @winter100004 in #39
• Fixed server hot reload issue by @devcodes9 in #50

• @devcodes9 for multiple contributions (#43, #49, #50)

• feat: Update sidebar icons and add new icons to shared package by @winter100004 in https://github.com/usertour/usertour/pull/26
• feat: Update theme configuration with new checklist and launcher styles by @winter100004 in https://github.com/usertour/usertour/pull/29
• refactor: Simplify registration page component structure by @winter100004 in https://github.com/usertour/usertour/pull/30
• fix(web): resolve authentication error for me query before login by @winter100004 in https://github.com/usertour/usertour/pull/31
• enhancement: targetEnvironment added by @devcodes9 in https://github.com/usertour/usertour/pull/33
• enhancement: make targetEnvironmentId optional and update permissions… by @winter100004 in https://github.com/usertour/usertour/pull/34

​

New Contributors

• @devcodes9 made their first contribution in https://github.com/usertour/usertour/pull/33

• Added redirect URL support for signup and login flows by @winter100004 in #15
• Introduced member-related features by @winter100004 in #24

• Refactored error handling mechanisms by @winter100004 in #21

• Improved word wrapping functionality by @winter100004 in #23

• Fixed issue where login configuration could not be obtained for Email, Google, etc. by @winter100004 in #17
• Updated README documentation by @dongfengtaoadmin in #18
• Updated docker-compose command in README by @winter100004 in #20

• @dongfengtaoadmin made their first contribution in #18

• v0.1.5…v0.1.6

• Implemented dynamic authentication provider rendering
• Added environment variables for authentication and file storage
• Supported Google login authentication

• Removed unnecessary logging in JWT strategy
• Migrated to a new environment configuration for API routing and authentication

• Enhanced user creation and project initialization during OAuth login
• Added GraphQL query to retrieve authentication provider configuration
• Integrated logging for GraphQL errors and JWT token extraction

• Fixed issue where login was not executed after creating a user in the server

• Integrated Biome and Husky for enhanced code quality management
• SDK version upgraded to 0.0.5
• Added placement documentation accessibility in Flow Builder

• Migrated from ESLint/Prettier to Biome for code formatting and linting
• Updated all codebase to comply with Biome standards

• Added direct documentation link for placement configuration in Flow Builder UI
• Enhanced development workflow with Husky git hooks
• Improved code consistency across the project with Biome integration

• Resolved formatting inconsistencies through Biome implementation
• Fixed code style issues across the codebase

​

🐞 Bug fix

​

🚀 Easy Onboarding: Build Flows Fast with Simple Integration and Smart Targeting

​

🚀 Built for professional workflows with version control and environments

​

🚀 Fully customizable appearance

​

🚀 Gain actionable insights with powerful analytics