> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# When to Use What in Userpilot

> Decision guide for choosing the right Userpilot feature: flows vs spotlights vs banners, SDK vs API, segments vs targeting, and more.

# 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                 |