Skip to content
awesome-tour

Type to search every page.

    BAnalyticsContents

    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,
    });
    Analytics funnel
    Loopworknight-drive.lwp
    001.1.1

    Mixer

    4 channels
    Drums
    80%
    Bass
    35%
    Keys
    60%
    Vox
    50%

    Bounce

    8 bars · 0:21
    Renders the loop to one file.

    Run the tour a few times — finish it once, close it early once, bounce once — to fill the funnel.

    AnalyticsDemo.tsx
    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 primitives

    Each takes { name?, properties? } to rename events or reshape their properties. More recipes in the analytics reference.