Labeled Events (Visually/CSS) – Userpilot Knowledge Base

If you’ve ever tried to answer a simple product questionlike “Do people actually click the shiny new button?”you already know the
villain of the story: missing event tracking. One team swears users love the feature. Another team swears it’s invisible.
Engineering says, “Sure, we can add events… right after these 37 other priorities.” And somewhere in the distance, an analyst quietly
opens a spreadsheet and weeps.

Userpilot’s Labeled Events (Visually/CSS) exist to keep that drama from becoming your personality. With labeled events,
you can track key user interactions without writing code by selecting elements visually (point-and-click) or by using
CSS selectors. It’s a practical way to move faster, validate feature adoption, and trigger in-app experiences based on
real behaviorwithout needing a developer on speed dial.

What Are Labeled Events in Userpilot?

In Userpilot, labeled events are a way to track user interactions like clicks, text inputs, and form submissions by
“labeling” what you want to measureeither through the Visual Labeler or by entering a CSS selector.
You’re essentially telling Userpilot: “When users interact with that element, count it.”

This is different from a traditional developer-defined event (often called a “tracked” or “custom” event in analytics tools), where
an engineer manually instruments a tracking call in code. Userpilot supports multiple event approaches, and labeled events are the
sweet spot when you need reliable insight fast, but you don’t want to wait for a dev cycle.

Labeled vs. Tracked vs. Custom Events (Quick, Useful Distinction)

• Labeled Events: No-code or low-code event setup using the visual builder or CSS selectors. Great for front-end interactions.
• Tracked Events: Implemented via code (tracking method calls). Best when you need event properties/metadata or backend/offline events.
• Custom Events: A roll-up/combination of existing eventsuseful for simplifying reporting when multiple actions represent one outcome.

Why Labeled Events Matter (Beyond “Because Data”)

Labeled events are not just “analytics housekeeping.” They help you answer practical product questions and act on the answers quickly:

• Feature adoption: Are users finding and using new functionalityor just politely ignoring it?
• Friction points: Where do users rage-click, hesitate, or drop off in a flow?
• Behavior-based targeting: Trigger onboarding tips, checklists, or spotlights when users actually need them.
• Goal measurement: Measure whether in-app experiences change behavior (not just whether they were “shown”).

The real win: labeled events let non-technical teams move from “I have a hunch” to “I have evidence” without opening a Jira ticket that
will age like a fine cheese.

How Userpilot Captures Data for Labeled Events

Auto-Capture Is the Engine

For labeled events to collect data, Auto-Capture must be enabled in Userpilot’s settings. Auto-capture is what allows
Userpilot to observe and record interaction data from your web app so it can later be organized into labeled events.

Historical Data: The “Time Machine” Benefit

One standout benefit of labeled events is that they can display historical data captured before the event was labeled.
In other words, if Userpilot has been auto-capturing since installation, and you label an event today, you may see interaction history
that was already collected in the background.

There’s an important nuance: while historical data can appear in analytics/reporting views, behavior-based targeting (like segments and
content triggers) typically relies on activity collected after the event is labeled. That means labeling earlier is still
betterespecially if you plan to trigger in-app experiences based on the event.

Three Ways to Create Labeled Events in Userpilot

Userpilot supports three practical routes. Choose based on speed, precision needs, and how “selector-savvy” your team feels today.

1) Visual Labeler (Point-and-Click)

The Visual Labeler is the most approachable option: you enter your app through Userpilot’s builder/Chrome extension, click the element you
want to track, and save it as a labeled event. It’s ideal when you want fast setup and immediate validation.

Best for: Buttons, navigation items, key UI interactions, quick instrumentation.

2) CSS Selectors (Direct Input)

If you want more controlor if the visual selection grabs the wrong elementyou can define the event using a CSS selector.
This is powerful when your UI has repeated patterns (lists, cards, tables), or when you need a selector that stays stable across updates.

Best for: Complex UIs, repeated elements, fine-tuning what counts as “the event.”

3) Labeling Raw Events (From Auto-Captured Data)

Userpilot can auto-capture “raw events,” which helps you discover what users are already doing. You can then label the relevant raw events
so they become first-class events you can analyze and use across reporting.

Best for: Exploration, finding high-signal interactions, building a tracking plan grounded in reality.

CSS Selectors for Event Labeling: The Practical Guide (No PhD Required)

A CSS selector is simply a pattern that targets HTML elementsby ID, class, attribute, type, or position. In analytics and event labeling,
selectors act like a “pointer” that tells the tool what element you mean.

Selector Types You’ll Actually Use

• ID selector: #saveButton (specific, but not always available and sometimes overused)
• Class selector: .cta-primary (common, but can be fragile if classes are generated dynamically)
• Attribute selector: button[data-testid="invite-user"] (often the most stable for tracking)
• Element/type selector: button (too broad unless paired with something else)
• Combinators: relationships like descendant ( ) and child (>) to narrow down location in the DOM

Examples That Make Sense in a Product UI

Here are selector examples that are readable and typically stable (especially when using dedicated tracking attributes):

Notice what’s missing: overly complex “DOM spaghetti” selectors and brittle :nth-child() chains. Those can work, but they tend
to break the moment your UI shifts by one pixel or one div.

How to Choose Stable Selectors (So Your Events Don’t Quietly Die)

Most labeled-event problems aren’t “Userpilot problems.” They’re selector problems. The best selector is the one that stays the same when
your UI evolves.

Use Dedicated Tracking Attributes

If you can collaborate with engineering even a little, ask for a simple, stable attribute on key elements:
data-track, data-testid, or similar. Attribute selectors are powerful because they don’t depend on CSS classes that
may change when a design system or framework updates.

Avoid Dynamic Selectors When Possible

Some frameworks generate class names that change between builds. If your selector relies on those classes, your event can stop matching.
Userpilot addresses this by offering tooling like an Exclude List to reduce dynamic selector noise, and guidance for
reselecting elements after the exclude list is updated.

Be Careful With “Matches Everything” Selectors

Sometimes you want one event to count across multiple identical elements (for example, “Clicked Any Project Card”). That’s validand
Userpilot can support collecting data from multiple elements sharing the same selector, including an option to include all matches.
Just make sure you intended it, or your “Clicked Upgrade Button” event might also include clicking… literally any button that looks
button-ish.

Verification: How to Know Your Labeled Event Works

Once you create a labeled event, validate it like you would validate a parachute: before you need it.

• Trigger the interaction yourself in the app (click, input, submit).
• Check the Events area/dashboard to see whether occurrences appear as expected.
• Confirm the selector scope: if the event count seems too high or too low, the selector likely matches too broadly or too narrowly.
• Watch out for UI variants: A/B tests, responsive layouts, and role-based UI can produce different DOM structures.

Pro tip: treat event verification as part of your release checklistright next to “turn on the feature flag” and “remember to breathe.”

Event Naming and Governance: Make Your Data Friendly to Humans

Labeled events are easy to create. The hard part is creating them in a way that your future self won’t hate.
Naming conventions and a simple tracking plan prevent chaos like:
Clicked Button, Button Clicked, clicked_button, ClickButton2_FINAL.

A Simple Naming Framework That Scales

• Object + Action (past tense): Invite Sent, Report Exported, Billing Page Viewed
• Be consistent with capitalization: Decide once, then stick to it.
• Don’t bake dynamic values into names: Put specifics in properties/metadata when possible.

This approach helps teams analyze and segment confidently, and it aligns with how many analytics platforms recommend structuring events.

Meaningful Events Beat “Track Every Pixel”

It’s tempting to label everything that moves. But most teams get better results by tracking actions that signal progress:
completing onboarding steps, inviting teammates, activating key features, exporting reports, saving settingsthings that reflect outcomes.

Using Labeled Events to Trigger In-App Experiences

Once labeled events are in place, you can do more than stare lovingly at charts. You can trigger targeted experiences, such as:

• Onboarding nudges: Show a tooltip after Settings Opened but before Settings Saved.
• Feature discovery: If users never trigger Report Exported, guide them to the export feature.
• Activation flows: Build a checklist that only progresses when events occur.
• Goal measurement: Compare event frequency before/after launching an in-app campaign.

This is where labeled events become a growth lever: you’re not just measuring behavioryou’re responding to it.

Integrations and Operational Use

Events are most valuable when they don’t live in one silo. Many teams send key events to other systems (CRMs, automation tools, data platforms)
so sales, success, and marketing can act on product behavior.

In Userpilot’s ecosystem, labeled events can be routed through certain integrations (like HubSpot, Salesforce, and webhooks), which makes it
easier to connect product usage to downstream actions such as lifecycle messaging or account health workflows.

Privacy and Data Hygiene (Because “Oops” Is Not a Strategy)

Anytime you enable auto-capture and label interactions, you should be intentional about what you track. A few practical guardrails:

• Avoid capturing sensitive inputs: Don’t label events that record personal, financial, or credential-like fields.
• Use exclusion controls: If selectors include dynamic or sensitive elements, apply exclusion rules and reselect elements as needed.
• Track what you can explain: If an event shows up in a customer conversation, you should be able to describe it plainly.

Clean data isn’t about perfectionit’s about confidence. If people don’t trust the events, they stop using the insights. And then the spreadsheet
crying starts again.

Conclusion: Build Faster Feedback Loops With Labeled Events

Labeled Events (Visually/CSS) in Userpilot are a practical way to understand feature usage, reduce instrumentation bottlenecks, and trigger
in-app experiences based on what users actually do. Use the Visual Labeler when you want speed, use CSS selectors when you want precision,
and use raw events labeling when you want discovery. Pair that with stable selectors, consistent event naming, and simple governanceand you’ll
have analytics your whole team can rely on.

Real-World Experiences & Lessons Learned (500+ Words)

When teams first adopt labeled events, the early excitement is usually the same: “We can finally track things without waiting for engineering!”
That excitement is justifieduntil the second week, when someone asks why an event count doubled overnight and the room goes quiet. The most
common lesson teams report is that speed is easy; stability is earned.

One recurring experience is the “selector surprise.” A team labels what they believe is a single buttonsay, an “Upgrade” CTA in the top
navigation. A few days later, the event appears unusually high. After investigation, they realize the selector matched multiple CTAs across
the UI (header, sidebar, pricing banner). Nobody did anything “wrong”; the selector simply described a pattern, not a unique element.
The fix is usually straightforward: refine the selector, scope it to a container, or use a dedicated attribute. But the big takeaway is
cultural: teams learn to treat event setup like a mini QA process, not a one-click miracle.

Another common field lesson: dynamic front-ends fight back. Modern apps often ship UI updates frequently, and frameworks can
generate changing class names. Teams that rely heavily on classes (especially auto-generated ones) often notice events silently stop matching.
The “silent” part is what makes it painfulyou don’t get an error message; you just get fewer insights. Over time, teams adopt a rule of thumb:
if an event is important enough to drive decisions, it’s important enough to have a stable selector. In practice, that means collaborating
with engineering to add one or two tracking-friendly attributes to key elements. This is usually an easy ask because it doesn’t change user
experience, styling, or functionalityjust identification.

Teams also report that labeled events improve cross-functional alignmentwhen they’re named well. In the beginning, different stakeholders
label the same concept with different names (for example, Clicked Invite vs. Invite Button Clicked). The analytics tool
then looks like a junk drawer: technically useful, but emotionally unsettling. The teams that mature fastest adopt a simple naming convention
(object + past-tense action), write it down in a short tracking plan, and periodically prune or consolidate.

A surprisingly positive experience is how labeled events reduce debates in product meetings. Instead of arguing about whether a feature is
“being used,” teams check the event trend, segment by persona, and move to the real question: “Why do certain users adopt it and others don’t?”
That shiftfrom subjective opinion to observable behaviortends to improve prioritization and messaging.

Finally, teams learn to avoid “tracking as a hobby.” It’s easy to label dozens of events and still feel uncertain about outcomes. The better
approach is to label a small set of high-signal events that map to activation and retention, then expand as new questions appear. In other
words: use labeled events to build a feedback loop, not a museum of clicks. When teams treat labeled events as a living systemreviewed,
refined, and aligned to goalsthey consistently report faster experimentation, clearer onboarding triggers, and more confidence in what their
users actually value.