How to Install Userpilot and Ship Your First In-App Guide
Userpilot is a product adoption platform that combines onboarding flows, in-app guides, NPS surveys and feature analytics in one subscription. The free plan covers 50 monthly active users; Growth starts around $249/month. Installation is a single snippet, and your first guide can go live the same afternoon.
What do you need before installing Userpilot?
Three things: an app with logged-in users, a way to identify those users, and a decision about which 3 screens your onboarding will cover. Do not install first and plan later — untargeted tours on the wrong page are how teams end up disabling the tool two weeks in.
The one hard requirement is a stable user ID. Userpilot targets by attributes, and if your app only exposes an anonymous session, every guide becomes a session-based guess.
How do you install the Userpilot snippet?
- In Userpilot, open Settings → Install. Copy the JS snippet.
- Paste it into your app’s base HTML template, just before the closing body tag, so it loads on every authenticated page.
- Ship to staging first, not production.
- Load the app, open the browser console, and confirm the Userpilot iframe is present.
- Only then promote to production.
Step 2 is where most React and Next.js apps trip. If your app uses client-side routing, the snippet loads once and never re-evaluates on route change. The fix is to call userpilot.reload() after navigation, or mount the snippet at the root layout so it survives route transitions.
If you use a tag manager instead of editing templates, the snippet must fire before your app’s hydration completes. Tag managers often fire on DOM ready, which is late. Verify with a refresh on a deep link, not just the homepage.
How do you identify users so targeting works?
After the snippet loads, call the identify method with at least an ID and your key plan attributes:
userpilot.identify("user_4821", {
name: "Ada",
email: "ada@example.com",
created_at: "2026-03-02",
plan: "growth",
account_seats: 12
});
created_at and plan are the two attributes that unlock useful targeting later — new user vs old user, trial vs paid. Add them now. Backfilling attributes across a year of accounts is a manual job nobody wants.
What should your first guide actually be?
Pick one flow. Mine would be: a 3-step tour of the main dashboard for users who signed up less than 24 hours ago, ending on the action you most want them to take — usually creating their first project.
Keep it to three steps. Userpilot’s editor defaults to more; audit every step and ask whether it teaches something or just narrates the UI. A tour that explains the sidebar is a tour people close.
Audience settings to set before publishing:
- Page URL — the specific app route, not the whole app.
- User attribute —
created_atwithin the last day. - Frequency — once per user, ever. Not once per session.
That last one matters. Re-showing the same tour every visit trains users to dismiss by reflex.
Where does Userpilot disappoint?
Frequency capping and advanced segmentation live behind Growth and above. The free tier at 50 MAU is genuinely useful for validating a flow, less so for running onboarding on a real cohort. And if you already pay for PostHog for analytics, you are buying overlapping event tracking — budget for the duplication before you sign.
Teams that need deep session replay and heatmaps will end up keeping a second tool anyway. Userpilot’s analytics is functional, not best-in-class.
Is Userpilot the right size for your team?
For a seed-to-Series-B SaaS with one person owning onboarding, yes. The pricing undercuts Pendo and Appcues at entry, and the editor does not require engineering time per flow.
For an enterprise with a product ops team, no. You will hit the segmentation ceiling and want the deeper data plans that Pendo sells. Compare Appcues if tours are the only thing you need.
Key Takeaways
- Userpilot installs via a single JS snippet in your base layout; free plan covers 50 monthly active users, Growth starts near $249/month.
- Client-side routing needs
userpilot.reload()or a root-layout mount, or guides only fire on the first page load. - Identify users with
created_atandplanfrom day one — targeting depends on them. - Ship one 3-step tour to users created in the last 24 hours, shown once ever.
- Advanced segmentation and frequency capping require paid tiers.
