Goals

A goal is an outcome you want users to reach, with a condition that says when they have. Docent is goal-driven rather than tour-driven: there is no script to author, and the guide works out its own route to the outcome.

Declaring one

Console, Goals, and a goal carries:

Keys are unique per app.

Done conditions

Event. Your app calls track with that string. This is the one to use for anything that happens on your server or in your state, which is most outcomes.

Anchor. The user sees an element with that data-guide name. Useful for "reached the billing page" outcomes that have no event of their own.

Completing a goal from your app

'use client'

import { useDocentTrack } from '@usedocent/react'

export const NewProjectForm = () => {
  const track = useDocentTrack()

  const onCreated = (projectId: string) => {
    track('project_created', { projectId })
  }

  // ...
}

useDocentTrack returns a function that is safe to call before the guide has mounted. A host firing track('project_created') in the same tick a page mounts would otherwise hit a null handle and silently drop the event that completes the goal.

The string you pass and the key in the Console are the same string. The payload is optional and is yours.

Outside React, the handle has the same method:

docent.track('project_created', { projectId })

When one completes

The mascot celebrates for a moment, and the mount emits a goal_done event carrying the key:

<Docent
  // ...
  onEvent={(event) => {
    if (event.type === 'goal_done') analytics.track('docent_goal', { key: event.goalKey })
  }}
/>

What the Console shows

The dashboard counts declaring goals as one of four setup steps, alongside an app and environment, a publishable key and knowledge. Until all four are done it names the next one.

Analytics reads the rest from live sessions: guided sessions, how many used voice, turns, p50 turn latency, the opt-in rate, the median time from session start to the first goal done, pointing accuracy, and the mute and dismiss rates.

A goal nobody completes and a goal your app never fires look identical from here, which is the argument for wiring track in the same change that declares the goal.

One thing to check

useDocentTrack reads React context, so it only works under <Docent>. A guide rendered as a sibling of your app rather than wrapping it gives you a working mascot and a track that does nothing at all. See the Next.js guide for where the component belongs.