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

# Onboarding Checklists and Product Tours

> Guide new users with in-app checklists and step-by-step tours — tasks that auto-complete from your custom events, with per-step funnel analytics.

A guide walks your visitors through your product without sending them anywhere — a checklist of getting-started tasks, or a tour of tooltips anchored to elements on the page — using a widget TinyAnalytics shows inside your site. You build the guide in the dashboard. Delivery, targeting, and analytics all work off your existing [tracking snippet](/docs/install-tinyanalytics-tracking-script), so there's **no extra code to add**.

## What are the two guide types?

| Type          | What it is                                                      | Best for                                                                 |
| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Checklist** | a persistent launcher that opens a task panel                   | self-paced onboarding ("Create your first project", "Invite a teammate") |
| **Tour**      | a sequence of tooltips, each anchored to an element on the page | a guided walkthrough of one screen or flow                               |

A tour step carries a title, a body, an optional call-to-action button, and an optional CSS selector to anchor to. You pick a preferred placement (top, bottom, left, or right) and how the step advances: the **Next** button, or **clicking the anchored element** itself. If an anchor selector matches nothing on the page, the step renders as a centered modal instead, so a layout change never breaks the tour.

<Note>
  Guide content renders as **plain text only** — the widget never interprets HTML, so a guide can't inject markup into your page.
</Note>

## How do I turn guides on?

Enable guides for the site first under **Settings → Tracking**. Guides are **off by default** for a new site, and until you enable them, creating a guide alone won't put anything in front of visitors — the widget code never loads. This keeps the tracker lean for sites that don't use guides.

## How do I create a guide?

From the site's **Guides** page, choose **New guide**, pick **Checklist** or **Tour**, and build the steps in the editor dialog. Each guide can have up to 20 steps, and a site can have up to 20 active guides.

* **Tour steps** — title, body, optional CTA (an `https://` link), optional anchor selector, placement, and advance trigger. Without a selector, the step is centered and the editor disables the position and target-click controls.
* **Checklist tasks** — title, optional description, an optional link the task opens when tapped, and an optional custom event that completes the task automatically (below).

The editor shows a live preview of the widget as you build. To see the guide on your real site, choose **Preview on my site** in the editor (or the preview action on a guide's row) — it opens your site with `?ta_preview_guide=<id>` and renders that exact draft with a **Preview** badge. If the guide isn't saved yet, it's saved as a draft first. Preview mode records nothing: no events, no stored progress.

## How do tasks auto-complete from events?

A checklist task can name one of your [custom events](/docs/custom-event-tracking). The field searches up to 100 event names seen in the last 30 days and shows each event's count; TinyAnalytics leaves its internal `guide_*` interaction events out of the suggestions. You can still type a new name. An amber message tells you when that exact name has not appeared recently, but does not block you from saving it.

When a visitor has fired the named event, the task checks itself off — **no instrumentation beyond the event itself**, which you're usually sending already. The check works across devices for visitors you've [identified](/docs/user-identification-analytics), and looks back over the last 180 days of their events.

If you name an event that hasn't been sent yet, the task simply waits for it — you can build the checklist before the feature ships.

## How does the selector picker work?

Instead of hand-writing a CSS selector for a tour step, choose **Pick on my site** in the step editor. This opens your own site in picker mode (`?ta_pick_selector=1`): the page dims, elements highlight as you hover, and clicking one generates the selector for you to confirm. Choose **Use this selector** and it is sent straight back into the step editor. If the picker cannot return to the dashboard tab, use **Copy** as a fallback. Fragile selectors (ones likely to break on a redesign) are flagged.

The picker runs on your live site, so it needs your tracking snippet installed there and guides enabled for the site. Both the guides widget and the picker are served from the same TinyAnalytics host as your snippet.

## Who sees a guide, and when?

Guides use the same targeting conditions as [surveys](/docs/product-feedback-surveys). A guide can be limited by:

* **URL** — show it only on matching pages (exact, contains, does-not-contain, or regex).
* **CSS selector** — require a specific element to be present on the page.
* **Device type** — desktop, mobile, or tablet.
* **Wait period** — don't show it again to the same visitor for a number of days.

At most one tour and one checklist appear per page load — the first eligible of each wins — and a guide never stacks on top of an open survey. Guides evaluate once when the page loads; they don't re-appear on client-side navigation within a single-page app.

A visitor who finishes or dismisses a guide never sees it again. Dismissing a tour is final (the **Esc** key or the dismiss action); a checklist's **Esc** only collapses its panel — dismissing a checklist for good is the explicit **Dismiss** button.

## What do the guide analytics show?

The guide's results view reports over a rolling 30-day window:

* **Starts, completions, and dismissals** — unique runs through the guide, with the completion rate counted per person.
* **A per-step funnel** — how far visitors progress, step by step, so you can see exactly where a tour loses people.

Guide interactions also arrive as ordinary events (`guide_started`, `guide_step_completed`, `guide_completed`, and so on) that you can explore in the [events explorer](/docs/event-analytics) alongside everything else.

## What is the privacy posture?

Anonymous visitors' progress never leaves their browser — it's held in local storage on their device. Progress is stored server-side only for visitors your site [identifies](/docs/user-identification-analytics), keyed on the identified user ID you provided, so an identified user's checklist follows them across devices. Server-side progress is covered by the standard [GDPR erasure](/docs/resources/privacy-friendly-analytics-gdpr) flow — deleting a user deletes their guide progress too.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why isn't my guide showing on my site?">
    Guides are **off by default** for a new site, so check that guides are enabled under **Settings → Tracking**. Also check the guide's targeting rules — URL, CSS selector, device type, and wait period all limit who sees it — and that the visitor hasn't already completed or dismissed the guide, which is final.
  </Accordion>

  <Accordion title="Do I need to add code to my site to run a guide?">
    No. TinyAnalytics guides need **no extra code beyond your tracking snippet**. You build the guide in the dashboard, and the widget, targeting, and analytics all work off the [tracking snippet](/docs/install-tinyanalytics-tracking-script) you already installed. Task auto-completion reuses the custom events you already send.
  </Accordion>

  <Accordion title="What happens when I edit a guide that people are partway through?">
    In-progress runs keep going. A visitor resumes at their first incomplete step, and if an edit deleted the step they were on, they resume at the next sensible point instead of the tour breaking. A tour keeps its run identity across edits, so your funnel analytics stay continuous.
  </Accordion>

  <Accordion title="Do guides work in single-page apps?">
    Guides evaluate once per page load and don't re-evaluate on client-side navigation. A guide targeted at one SPA route appears when the visitor loads that route directly or reloads on it.
  </Accordion>

  <Accordion title="Can I preview a guide without publishing it?">
    Yes. Choose **Preview on my site** in the editor or from the guide's row. TinyAnalytics opens your site with `?ta_preview_guide=<id>` and renders that draft with a **Preview** badge — including archived or unpublished guides. An unsaved guide is saved as a draft first. Preview mode records no events and stores no progress.
  </Accordion>

  <Accordion title="What happens to a visitor's progress when they log in?">
    Identified users get server-side progress keyed on their identified ID, so their checklist and tour state follows them across devices and merges with what they did anonymously. Progress from two devices merges — completed tasks union together, and a dismissal on any device wins.
  </Accordion>
</AccordionGroup>

## Can I manage guides from the API or an AI agent?

Yes. Guides have full CRUD in the REST API and in the [MCP server](/docs/api-reference/mcp-server), so an agent (Claude Code, Cursor, Codex) or your own scripts can create, launch, and measure them. The key needs the **Guides** scope — **Read** for listing and stats, **Write** for creating and updating.

| Action                             | REST endpoint                              | MCP tool               |
| ---------------------------------- | ------------------------------------------ | ---------------------- |
| List guides                        | `GET /api/sites/:id/guides`                | `list_guides`          |
| Create a guide (starts as a draft) | `POST /api/sites/:id/guides`               | `create_guide`         |
| Update, launch, stop, or restore   | `PUT /api/sites/:id/guides/:guideId`       | `update_guide`         |
| Archive (soft delete, restorable)  | `DELETE /api/sites/:id/guides/:guideId`    | `delete_guide`         |
| Performance funnel                 | `GET /api/sites/:id/guides/:guideId/stats` | `get_guide_stats`      |
| Per-step drop-off                  | `GET /api/sites/:id/guides/:guideId/steps` | `get_guide_step_stats` |

There are no separate publish endpoints: `update_guide`'s lifecycle fields drive the state machine — set `startDate` to launch, `endDate` to stop, and `archived` to archive or restore. A minimal create body:

```json theme={null}
{
  "name": "Get started checklist",
  "type": "checklist",
  "steps": [
    { "id": "task-1", "title": "Invite your team" },
    { "id": "task-2", "title": "Create your first funnel", "eventName": "funnel_created" }
  ]
}
```

Step shapes differ by `type`: tours take `title` + `body` with an optional anchor `selector`, checklists take `title` with an optional auto-completing `eventName`. New guides always start as drafts, and visitors only see a launched guide once guides are enabled for the site under **Settings → Tracking**. Full request and response schemas live in the [API reference](/docs/api-reference/tinyanalytics-api).

## Related

<Columns cols={2}>
  <Card title="Surveys" icon="comment-dots" href="/docs/product-feedback-surveys">
    Ask visitors targeted questions with the same delivery chassis.
  </Card>

  <Card title="Custom events" icon="bolt" href="/docs/custom-event-tracking">
    The events that auto-complete checklist tasks.
  </Card>

  <Card title="Identify users" icon="user" href="/docs/user-identification-analytics">
    Give visitors a stable ID so progress follows them across devices.
  </Card>

  <Card title="Events explorer" icon="magnifying-glass-chart" href="/docs/event-analytics">
    Explore the guide interaction events your widget emits.
  </Card>

  <Card title="Install the tracking script" icon="code" href="/docs/install-tinyanalytics-tracking-script">
    The one snippet that powers guides, surveys, and analytics.
  </Card>
</Columns>


## Related topics

- [Realtime Analytics](/docs/realtime-analytics.md)
- [Install TinyAnalytics in 5 Minutes](/docs/tinyanalytics-quickstart.md)
- [Product Feedback and NPS Surveys](/docs/product-feedback-surveys.md)