What are the two guide types?
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.
Guide content renders as plain text only — the widget never interprets HTML, so a guide can’t inject markup into your page.
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).
?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. The field searches up to 100 event names seen in the last 30 days and shows each event’s count; TinyAnalytics leaves its internalguide_* 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, 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. 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.
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_started, guide_step_completed, guide_completed, and so on) that you can explore in the events explorer 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, 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 flow — deleting a user deletes their guide progress too.Frequently asked questions
Why isn't my guide showing on my site?
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.
Do I need to add code to my site to run a guide?
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 you already installed. Task auto-completion reuses the custom events you already send.
What happens when I edit a guide that people are partway through?
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.
Do guides work in single-page apps?
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.
Can I preview a guide without publishing it?
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.What happens to a visitor's progress when they log in?
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.
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, 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.
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:
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.
Related
Surveys
Ask visitors targeted questions with the same delivery chassis.
Custom events
The events that auto-complete checklist tasks.
Identify users
Give visitors a stable ID so progress follows them across devices.
Events explorer
Explore the guide interaction events your widget emits.
Install the tracking script
The one snippet that powers guides, surveys, and analytics.