Docs

Getting started

Pick one way to install, then copy the key for each product you use.

Keys

Keys are public identifiers, not secrets — they appear in your page source. What limits where they work is the Allowed domain you set on each project or campaign.

These values are built into your site when it is compiled. Set them for Production and Preview in your host (Vercel, Netlify...) and redeploy after changing them. With npm, host is required: without it the package logs an error and starts nothing — your site keeps working.

Analytics

Pageviews, visitors, referrers, devices and countries — plus clicks, recordings and friction signals when you turn them on.

Recorded automatically

• •Pageviews, with referrer and UTM parameters, time on page and scroll depth.
• •Route changes in single-page apps — links, back and forward, and redirects to a new path (router.replace).
• •Link and button clicks, with “Track link and button clicks” on in the project settings.
• •Clicks on links leaving your site, with “Track outbound link clicks” on.
• •Rage clicks, errors after a click, abandoned forms and load times, with “Detect friction signals” on.

Settings that change what is sent

• •Allowed domain — the tracker only runs on that domain (and its www. form).
• •Exclude paths — nothing is recorded on matching pages, custom events included.
• •Honor browser Do Not Track — visitors with it on are not tracked at all.

Not seeing data?

Add data-debug="1" to the script tag, or debug: true to the analytics options of init(). The tracker then logs each request and the server’s reply to the browser console.

Custom events

Record the moments that matter — a signup, a plan choice, an invite. Every name you send becomes a funnel step. Needs analytics installed.

Properties

Optional. Up to 20 keys, strings trimmed at 200 characters. Strings, numbers and true/false only. Funnels match on the event name, not on properties.

// Optional. Strings, numbers and true/false only -
// nested objects and arrays are dropped on save.

window.userlily.track('plan_selected', {
  plan: 'pro',
  seats: 5,
  trial: false
})

Naming

• •Use the same name every time — matching is exact and case-sensitive, so signup_completed and Signup_Completed are two different events.
• •No spaces at the start or end. They are kept exactly as sent, and a name with a stray space can never match a funnel step.
• •Lowercase with underscores reads best and avoids the case trap: checkout_started, plan_selected, invite_sent.
• •Keep the name fixed. Anything that varies per visitor — an id, an email, a price — belongs in the properties, not in the name.
• •At most 100 characters, and not one of the tracker's own names (click, outbound_click, rage_click, error_click, form_abandon, page_performance). Either is dropped, with a warning in your browser console.

Already sent for you

Recordings & privacy

Session replays use the analytics install — no extra code. Turn on “Enable session recordings” in the project settings and choose a sample rate.

What is hidden

• •“Mask input values” — typed values are replaced with blocks. On by default.
• •“Mask all text” — every word on the page is replaced with blocks.
• •“Custom mask selectors” — mask only the elements you list.
• •“Discard recordings shorter than” and “Maximum recording length” bound what is stored.

Keep an element out entirely

<!-- Never captured: replaced by an empty box
     of the same size in every recording -->
<div data-userlily-block>
  Account number, medical details...
</div>

Feedback widget

A floating Feedback button that opens your campaign’s form — with optional screenshots. Fields, colour and position are set on the campaign.

Or share a link

Every campaign also has a hosted feedback page — nothing to install.

https://dev.userlily.com/f/YOUR_CAMPAIGN_KEY

Review badge

A live rating badge built from your campaign’s reviews. Switch on “Enable syndication” and pick a style on the campaign’s Syndication page.

Web push

Send notifications to visitors who opt in. Two steps, and both are needed before anyone can subscribe.

1. Host the service worker on your own domain

Browsers only register a service worker served from the page’s own domain, so this one file lives on your server — whichever way you install. Each rule below fails silently if it is not met:

• •At your site root: https://your-site/userlily-sw.js.
• •Served as JavaScript (Content-Type text/javascript).
• •No redirect. Sign-in middleware (Next.js, Clerk, NextAuth) is the usual cause — exclude /userlily-sw.js from it.
• •Over HTTPS. Plain http only works on localhost.

https://dev.userlily.com/v1/userlily-sw.js

npx --no userlily copy-sw public

2. Add it to every page

<script defer
  data-project="YOUR_PROJECT_KEY"
  src="https://dev.userlily.com/v1/broadcast.js"></script>

3. Choose when visitors are asked

Set on the project’s Settings page, under “When to ask”:

• •As soon as the page loads
• •After a delay
• •After scrolling down the page
• •Only when your own code asks

To ask from your own code, keep the prompt switched on and choose “Only when your own code asks”:

var button = document.querySelector('#notify-me')
button.addEventListener('click', function () {
  // Exists once broadcast.js has started, and only
  // when "When to ask" is "Only when your own code asks".
  if (window.userlilyBroadcast) window.userlilyBroadcast.prompt()
})

Public roadmap

Show your roadmap with voting, comments and idea submissions. Turn on “Enable public roadmap” in Roadmap → Settings, then use Share on the board.

<iframe
  data-userlily-roadmap
  src="https://dev.userlily.com/r/YOUR_ROADMAP_KEY?embed=1"
  title="Product roadmap"
  style="width:100%;height:720px;border:0"
  loading="lazy"
></iframe>
<script>
(function () {
  window.addEventListener("message", function (event) {
    if (event.origin !== "https://dev.userlily.com") return;
    var data = event.data;
    if (!data || data.type !== "userlily:roadmap:height") return;
    var frame = document.querySelector("iframe[data-userlily-roadmap]");
    if (frame && data.height > 0) frame.style.height = data.height + "px";
  });
}());
</script>

https://dev.userlily.com/r/YOUR_ROADMAP_KEY

Surveys

Surveys are shared as a link — open your survey and use Share. There is no embed or npm step.

https://dev.userlily.com/s/YOUR_SURVEY_KEY

Frameworks and languages

A complete setup for your stack — where the keys go, the one file that starts userlily, and every product.

Logos are trademarks of their owners and are shown only to indicate compatibility.

@userlily/js reference

Everything the package exports. It never throws into your app unless you ask it to, and does nothing during server rendering.

init(options)

Returns { ok: true, skipped: [] }. A product configured without its key is skipped with a warning and listed in skipped while the rest start. When nothing can start it returns { ok: false, reason } with one of missing_host, invalid_host, host_mismatch or server. Calling it again is safe — a running product is never started twice.

Other exports

Troubleshooting

Most problems announce themselves in the browser console with a [userlily] prefix.