When to Use What in Userpilot
This guide helps you choose the right Userpilot feature for your use case.Content Type Selection
Flow vs Spotlight vs Banner vs Checklist
| Use Case | Best Choice | Why |
|---|---|---|
| Multi-step onboarding | Flow | Guide users through sequences |
| Feature announcement | Banner | Non-intrusive, persistent visibility |
| Highlight single element | Spotlight | Draws attention without interrupting |
| Onboarding tasks | Checklist | Tracks progress, user-driven pace |
| Important alert | Modal (Flow) | Demands attention, blocks interaction |
| Contextual hint | Tooltip (Spotlight) | Appears on hover, non-disruptive |
| In-app help center | Resource Center | Self-service, always accessible |
Modal vs Slideout vs Tooltip
| Situation | Use |
|---|---|
| Critical information user must see | Modal |
| Longer content that doesn’t block UI | Slideout |
| Quick tip about specific element | Tooltip |
| Step-by-step walkthrough | Tooltip sequence (Flow) |
| Announcement with dismiss option | Modal or Slideout |
NPS vs Survey vs Flow Form
| Goal | Use |
|---|---|
| Measure overall satisfaction | NPS |
| Detailed feedback on specific feature | Survey |
| Collect info during onboarding | Flow with form fields |
| Quick rating (1-5 stars) | Survey with rating question |
| Open-ended feedback | Survey with text question |
SDK vs API
When to use JavaScript SDK
| Scenario | Method |
|---|---|
| Browser-based web app | userpilot.identify() |
| User interacts with UI | userpilot.track() |
| Real-time content display | SDK required |
| Single-page application | SDK with reload() |
When to use HTTP API
| Scenario | Method |
|---|---|
| Server-side user creation | POST /v1/identify |
| Backend event tracking | POST /v1/track |
| Bulk data import | Import API |
| Data export for analytics | Export API |
| Update users without page load | HTTP API |
| Mobile app (native) | Mobile SDK or HTTP API |
When to use both
| Scenario | Approach |
|---|---|
| User signs up via backend | API to create user, SDK to display content |
| Server-side event + UI update | API to track, SDK to trigger content |
| Historical data + real-time | Import API for history, SDK ongoing |
Targeting Decisions
Segment vs Direct Targeting
| Situation | Use |
|---|---|
| Reusable audience | Create Segment |
| One-time targeting | Direct targeting rules |
| Complex AND/OR logic | Segment |
| Simple property match | Direct targeting |
| Target across multiple content | Segment |
User Property vs Event-based
| Goal | Target By |
|---|---|
| Users on specific plan | User property (plan) |
| Users who completed action | Event (completed_action) |
| Users who haven’t done something | Event NOT performed |
| Users with certain attributes | User properties |
| Users based on behavior patterns | Events + properties combined |
Page Targeting Options
| Goal | Method |
|---|---|
| Exact URL | Exact match |
| All pages in section | Contains or starts with |
| Dynamic URLs | Regex pattern |
| Multiple specific pages | Multiple URL rules (OR) |
| Exclude certain pages | NOT contains rule |
Trigger Timing
When to use each trigger
| Trigger | Best For |
|---|---|
| Page load | Welcome messages, page-specific tips |
| After delay | Non-urgent info, avoid overwhelming |
| Element click | Contextual help, on-demand guidance |
| Custom event | Action completion, behavioral triggers |
| Manual (API) | Backend-triggered, external conditions |
| Scroll depth | Long pages, engagement-based |
Frequency settings
| Setting | Use When |
|---|---|
| Only once | Onboarding, announcements |
| Every time | Contextual tips that stay relevant |
| Once per session | Session-specific reminders |
| Until dismissed | Important recurring notices |
| Until completed | Required acknowledgments |
Installation Scenarios
Which installation method
| Scenario | Method |
|---|---|
| Full control, engineering available | JavaScript snippet |
| Already using Segment | Segment integration |
| Marketing needs to install | Google Tag Manager |
| Need to bypass ad blockers | Custom domain hosting |
| iOS native app | iOS SDK |
| Android native app | Android SDK |
| React Native app | React Native SDK |
| Flutter app | Flutter SDK |
Analytics Decisions
Which report to use
| Question | Report |
|---|---|
| How do users move through steps? | Funnel |
| What do users do before/after X? | Path |
| Do users come back over time? | Retention |
| How is metric trending? | Trends |
| Where do users drop off? | Funnel |
| Which features are used together? | Path |
Dashboard vs Custom Report
| Need | Use |
|---|---|
| Quick overview of standard metrics | Pre-built Dashboard |
| Specific metric tracking | Trends Report |
| Custom KPI monitoring | Custom Dashboard |
| Share with stakeholders | Dashboard + sharing |
| Deep dive investigation | Individual Reports |
Integration Decisions
CRM sync
| Goal | Integration |
|---|---|
| Sync user data to CRM | HubSpot or Salesforce |
| Trigger Userpilot from CRM | Webhooks + API |
| Sync NPS/survey responses | Native integration |
Analytics sync
| Goal | Integration |
|---|---|
| Already using Segment | Segment source |
| Send events to analytics | Amplitude, Mixpanel, GA |
| Unified event tracking | Segment as hub |
Data warehouse
| Goal | Method |
|---|---|
| Raw event export | Data Sync (BigQuery, Snowflake, S3) |
| One-time export | Export API |
| Custom analysis | Data Sync + BI tool |