Analytics
Measure where users drop off with flat, tool-agnostic events.
The analytics plugin turns tour activity into flat events you can send to any tool.
import { analytics, createTour } from '@awesome-tour/react';
createTour({ id: 'onboarding', plugins: [analytics((event) => posthog.capture(event.type, event))], steps,});Mixer
4 channelsBounce
8 bars · 0:21Run the tour a few times — finish it once, close it early once, bounce once — to fill the funnel.
import { analytics, createStore, createTour, Tour, type TourAnalyticsEvent, useStoreSelector,} from '@awesome-tour/react';import { createLoopwork, LoopworkApp, parts } from '@loopwork';import { TourPopover } from '@/components/awesome-tour/tour';import { DemoFrame, StartButton } from './ui';
const $ = parts('bounce-funnel');const app = createLoopwork({ route: 'mix' });
const log = createStore<{ events: TourAnalyticsEvent[] }>({ events: [] });
const steps = [ { id: 'format', target: $('format'), title: 'Pick a format', description: 'WAV for the master, MP3 to send a sketch to a friend.', }, { id: 'bounce', target: $('bounce'), title: 'Bounce it', description: 'Renders the 8-bar loop to a single file.', meta: { label: 'bounce-cta' }, }, { id: 'share', title: 'That’s a release', description: 'Close this card early next time and watch the funnel drop.', },] as const;
const tour = createTour({ id: 'docs-analytics', version: 3, // What the tour is for. Counted even if the user closes the tour first and bounces later. goal: { name: 'first-bounce', signal: 'bounced' }, plugins: [ // In an app: analytics((e) => posthog.capture(e.type, e)) analytics((event) => log.setState((s) => ({ events: [event, ...s.events].slice(0, 200) }))), ], steps,});
app.on('bounced', () => tour.signal('bounced'));
/** Step-by-step funnel built from the events the plugin emits: views per step, then outcomes. */function Funnel() { const events = useStoreSelector(log, (s) => s.events); const starts = events.filter((e) => e.type === 'tour_started').length; const views = (id: string) => events.filter((e) => e.type === 'step_viewed' && e.stepId === id).length; const outcomes = { completed: events.filter((e) => e.type === 'tour_completed').length, dismissed: events.filter((e) => e.type === 'tour_dismissed').length, goals: events.filter((e) => e.type === 'tour_goal_reached').length, }; const rows = steps.map((step) => ({ id: step.id, label: step.title, count: views(step.id) })); return ( <section aria-label="Tour funnel" className="flex flex-col gap-2"> {starts === 0 ? ( <p> Run the tour a few times — finish it once, close it early once, bounce once — to fill the funnel. </p> ) : ( <> <ol className="flex flex-col gap-1.5"> {rows.map((row) => ( <li key={row.id} className="grid grid-cols-[9rem_1fr_3rem] items-center gap-3"> <span className="truncate text-ink">{row.label}</span> <span className="h-2.5 bg-paper-2" aria-hidden="true"> <span className="block h-full bg-ink transition-[width] duration-200" style={{ width: `${(row.count / starts) * 100}%` }} /> </span> <span className="text-right font-mono tabular-nums"> {Math.round((row.count / starts) * 100)}% </span> </li> ))} </ol> <p className="font-mono tabular-nums"> {starts} started · {outcomes.completed} completed · {outcomes.dismissed} closed early ·{' '} {outcomes.goals} bounced (goal) </p> </> )} </section> );}
export function AnalyticsDemo() { return ( <Tour.Root tour={tour}> <DemoFrame title="Analytics funnel" actions={<StartButton />} footer={<Funnel />}> <LoopworkApp scope="bounce-funnel" app={app} layout="routed" /> </DemoFrame> <TourPopover /> </Tour.Root> );}Events
type |
When |
|---|---|
tour_started |
The tour starts. |
step_viewed |
A step is shown — with direction, previousStepId and previousStepDurationMs. |
tour_completed |
The user finished the tour. |
tour_skipped |
The user opted out (skip()). |
tour_dismissed |
The tour was closed (close(), Escape, ✕). |
tour_paused / tour_resumed |
pause() / resume(). |
target_missing |
A step’s target wasn’t found — a sign the tour is out of date. |
tour_goal_reached |
The tour’s goal happened — with goal, outcome (how the run stood) and durationMs since the start. |
tour_error |
The tour stopped with an error. |
Every event carries tourId, tourVersion, stepId, stepIndex, totalSteps, timestamp, and
the step’s meta. End events add durationMs and stepDurationMs. Tours that are variants of an
experiment also carry experimentId and variant.
analytics(track, { includeData: false, // set true to attach tour.data (beware of PII) filter: (event) => event.type !== 'step_viewed', // drop what you don't need});Use step meta for labels your analytics team cares about:
{ id: 'bounce', target: '#bounce', meta: { funnel: 'activation', label: 'bounce-cta' } }Goals
“Completed the tour” is a vanity metric: people finish tours they ignored and skip tours they then
follow. A goal names the action the tour exists to cause, and counts it whenever it happens —
during the tour, or after it was finished, skipped or closed:
createTour({ id: 'first-session', goal: { name: 'first-bounce', signal: 'bounced', // tour.signal('bounced'), from your app // or: event: { type: 'click', target: '#bounce' }, route: '/mix', when: (ctx) => … within: 7 * 24 * 60 * 60_000, // stop watching after a week (default: while the page lives) }, steps,});The tour emits goal ({ name, stepId, status, afterMs }) once per run, and the analytics plugin
turns it into tour_goal_reached. With persist(), the run’s goal
survives reloads: a user who finishes the tour today and bounces tomorrow still converts (within
within), and is counted once. Without it, call tour.trackGoal(since) yourself. The demo above counts bounces next to the funnel.
Ready-made adapters
@awesome-tour/core/adapters turns the plugin’s events into calls to the usual tools. The
clients are typed structurally, so no SDK is bundled:
import { analytics } from '@awesome-tour/react';import { ga4Tracker, mixpanelTracker, posthogTracker, segmentTracker } from '@awesome-tour/core/adapters';
createTour({ id: 'onboarding', steps, plugins: [analytics(posthogTracker(posthog))] });// analytics(segmentTracker(window.analytics))// analytics(mixpanelTracker(mixpanel, { name: (e) => `Tour: ${e.type}` }))// analytics(ga4Tracker(gtag)) — params are flattened to primitivesEach takes { name?, properties? } to rename events or reshape their properties. More recipes
in the analytics reference.