> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rydhm.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rydhm.ai/_mcp/server.

# Onboarding analytics

Everything the coach and the browser SDK see is recorded per person: page views, guides offered, started, completed or dismissed, steps done, announcements shown and clicked, tools used, page-map targets that went missing. The coach's **Insights** tab turns that into one view per expert, over the last 7, 30 or 90 days: **Overview** for the figures below, **People** for each person the coach met and their progress.

## What you see

| Part                | What it shows                                                                                                                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fixes**           | First: what the coach fixed by itself, what it is testing, and the few things that need you. See [The coach fixes itself](#the-coach-fixes-itself).                                                                                                      |
| **People**          | Active users in the window, how many were new, and how many were [signed](/engine/onboarding-coach-code#signed-users).                                                                                                                                   |
| **Conversations**   | Voice and typed conversations with the coach, and the voice minutes.                                                                                                                                                                                     |
| **Guides**          | A funnel per guide: people the nudge was shown to, who started, finished or dismissed it, and how many finished each step. Each guide is a cohort of the people who **started** it in the window, so the completion rate (finished ÷ started) is honest. |
| **Announcements**   | People (not views) who saw, clicked and dismissed each one, and the click rate.                                                                                                                                                                          |
| **Top pages**       | The pages viewed most, with views and people.                                                                                                                                                                                                            |
| **Missing targets** | Page-map entries the SDK couldn't find on the page, most first. Fix these first: the coach is pointing at something that moved.                                                                                                                          |

## The coach fixes itself

The coach reads its own conversations and finds what keeps going wrong: a button it couldn't find, a guide step that failed, a question it couldn't answer, a click people said was wrong. It fixes what it safely can, checks that each fix worked, and asks you only about the rest. It checks every 15 minutes; admins can select **Check now**.

**What counts.** A problem has to come up in 3 conversations with 2 different people within 7 days. Your own team's testing is left out:

* preview, Teach and Explorer links;
* automated browsers;
* people in your Rydhm workspace;
* one person with more than 40 conversations in a day.

Select **Include your team's tests** to see them anyway. "Gave up" and "asked again" are filed under the problem that caused them, not as problems of their own.

**What it fixes by itself:**

* **A button listed on the wrong pages.** The page-map entry is narrowed to the pages where the coach has actually seen it.
* **A button missing from the page map.** It is added when the coach has confirmed exactly one matching button on that page, with a stable selector.
* **A guide step pointing at a button by an old name.** The step is pointed at the matching page-map entry.
* **A question it couldn't answer, when your knowledge already covers it.** It adds a short knowledge note written from your own content.

Before a fix goes in, the coach checks that the button would be found on those pages. Then it watches new conversations:

* **The problem comes back:** the fix is undone automatically and the problem moves to **Needs you**.
* **5 clean conversations, or 7 days with at least one:** the fix is marked **Fixed**.
* **Too little traffic after 14 days:** the fix stays.

**What you see:**

| Section                 | What's in it                                                                                                                                                                                         |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Needs you**           | Fixes it tested but wants your OK for, each with **Approve**, **Edit** or **Not a problem**, plus fixes that came back or that you undid (with **Apply again**), and problems it can't fix by itself |
| **Testing now**         | Fixes being watched, with how many checks have passed                                                                                                                                                |
| **Fixed automatically** | What went wrong, what the coach changed, how many conversations confirmed it, and **Undo**                                                                                                           |
| **Rydhm is on it**      | Problems in Rydhm's own engine, which we fix: nothing for you to do                                                                                                                                  |

The **Insights** tab's number counts only **Needs you**. Each week the coach also sends admins a short summary in the bell: what it fixed, what it's testing and what needs you.

**What it never does by itself:**

* **Anything that isn't clear-cut.** It asks you instead when:
  * a fix isn't certain, for example two buttons could match;
  * a button looks destructive, such as delete;
  * a knowledge note would be about pricing, legal or security, or has gaps.
* **Delete anything,** or change the coach's instructions.
* **Re-apply a fix you undid, or one it put back.** You can: **Apply again** in **Needs you** checks the change against your app map first (it's refused, with the reason, if the button is no longer where the fix says), then watches it again like a new fix. **Undo** is refused if someone edited that entry since.
* **Keep fixing when your app may have changed.** When more than half of a page's buttons go missing at once, your app may have changed or be down: it pauses fixes on that page and tells you.

**Ask first instead.** In **Settings → App map**, under **When something keeps going wrong**, choose **Ask me first**. Fixes then wait in **Needs you** for **Approve**. The default is **Fix things automatically**.

## From your server

```typescript
import { Rydhm } from "@rydhm/sdk";
const rydhm = new Rydhm(); // a key with experts:read

const a = await rydhm.engine.analytics(expertId, { days: 30 });
for (const g of a.guides) {
  console.log(g.name, `${g.completed}/${g.started}`, g.completionRate);
  for (const s of g.steps) console.log("  ", s.title, s.completed);
}
console.log("Missing:", a.missingTargets.map((t) => `${t.name} (${t.count})`).join(", "));
```

```python
from rydhm import Rydhm

client = Rydhm()
a = client.engine.analytics(expert_id, days=30)
for g in a.guides:
    print(g.name, g.completed, g.started, g.completion_rate)
```

`days` is 7, 30 (the default) or 90. See `GET /v1/agents/{id}/onboarding/analytics` in the [API reference](/api-reference).

## People and their progress

The people the coach met are **end users**: your user id when it was signed, or `anon_` and an id for everyone else.

```typescript
// Most recently seen first; `for await` walks every page.
for await (const user of rydhm.engine.endUsers.list(expertId, { q: "acme" })) {
  console.log(user.externalId, user.signed, user.lastSeenAt);
}

const person = await rydhm.engine.endUsers.get(expertId, endUserId); // Rydhm's id: user.id
for (const p of person.progress) console.log(p.guideName, p.status, p.stepsDone);
for (const e of person.events) console.log(e.createdAt, e.type, e.name);
```

`endUserId` is Rydhm's id for the person (`id`), not your user id (`externalId`).

## Webhooks

Two events let your own systems react, signed like every [webhook](/developers/webhooks):

| Event              | When                                                                                     |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `end_user.created` | The coach met a new person: a new user id, or a new anonymous visitor (`signed: false`). |
| `guide.completed`  | Someone finished every step of a guide. Sent once per person and guide.                  |

Neither carries the person's name or traits: only ids, the guide and links. Use them to mark onboarding done in your CRM, or to send a follow-up email.