# Product analytics

URL: /systems/product-analytics · Id: `system:product-analytics`

> Product analytics turns the Visits and Events captured on every Domain and API into the conversion, activation and retention Metrics every Team reads.

Product analytics reads the [Events](/business/nouns/event) every [Verb](/business/nouns/verb) emits as trends, funnels, retention, paths and lifecycle. The definition is the tracking plan: a [Change](/business/nouns/change) that renames or removes an Event must map it for every reader, or it is refused.

## Summary
| Part | This System |
| --- | --- |
| Group | Data and insights |
| Status | Live |
| Shelf | Silent: it runs without being asked |

You can ask:

- “Where do visitors drop off?”
- “How many people signed up this week?”
- “Do users come back after the first week?”
- “Watch a recording of this session”

## What you get
| Part | This System |
| --- | --- |
| Starts | On for every Startup at creation, with nothing to install. |
| Built from | [Analytics](/systems/data-and-insights/analytics), [Event streams](/code/platform/event-streams), [Database](/code/platform/capabilities/database), [Functions](/code/platform/capabilities/functions) |

## Nouns it owns
| Noun | Definition |
| --- | --- |
| [Visitor](/business/nouns/visitor) | A Visitor is someone a Startup cannot name, known by an id scoped to that Startup. |
| [Visit](/business/nouns/visit) | A Visit is one span of a Visitor’s Events on a Startup’s Sites and Apps. |
| [Metric](/business/nouns/metric) | A Metric is a named measure computed from Events or Entries, always derived and never typed in. |
| [Acquisition](/business/nouns/acquisition) | An Acquisition is how a Visitor or Prospect first arrived, recorded on its first Event: the referrer kind, the Play, the campaign, and the medium. |
| [Recording](/business/nouns/recording) | A Recording is the replay of one Visit or one agent browser session, masked at capture. |
| [Audience](/business/nouns/audience) | An Audience is a saved query over Visitors, Leads, Prospects, or Customers, used to target Ads and Messages. |

## Verbs
| Verb | Object | Approval | Event |
| --- | --- | --- | --- |
| [Visit.list](/business/nouns/visit/list) | [Visit](/business/nouns/visit) | None | None. |
| [Metric.create](/business/nouns/metric/create) | [Metric](/business/nouns/metric) | None | `Metric.created` |
| [Metric.list](/business/nouns/metric/list) | [Metric](/business/nouns/metric) | None | None. |
| [Customer.activate](/business/nouns/customer/activate) | [Customer](/business/nouns/customer) | None | [`Customer.activated`](/business/events/Customer.activated) |
| [Event.capture](/business/nouns/event/capture) | [Event](/business/nouns/event) | None | [`Event.captured`](/business/events/Event.captured) |
| [Visitor.identify](/business/nouns/visitor/identify) | [Visitor](/business/nouns/visitor) | None | [`Visitor.identified`](/business/events/Visitor.identified) |
| [Visitor.merge](/business/nouns/visitor/merge) | [Visitor](/business/nouns/visitor) | None | [`Visitor.merged`](/business/events/Visitor.merged) |
| [Visitor.forget](/business/nouns/visitor/forget) | [Visitor](/business/nouns/visitor) | Asks first; waits 1 business hour | [`Visitor.forgotten`](/business/events/Visitor.forgotten) |
| [Metric.define](/business/nouns/metric/define) | [Metric](/business/nouns/metric) | None | [`Metric.defined`](/business/events/Metric.defined) |
| [Metric.query](/business/nouns/metric/query) | [Metric](/business/nouns/metric) | None | [`Metric.queried`](/business/events/Metric.queried) |
| [Metric.watch](/business/nouns/metric/watch) | [Metric](/business/nouns/metric) | None | [`Metric.watched`](/business/events/Metric.watched) |
| [Recording.list](/business/nouns/recording/list) | [Recording](/business/nouns/recording) | None | None. |

## Events
| Direction | Event | How |
| --- | --- | --- |
| Emits | `Metric.created` | By [Metric.create](/business/nouns/metric/create) |
| Emits | [`Customer.activated`](/business/events/Customer.activated) | By [Customer.activate](/business/nouns/customer/activate) |
| Emits | [`Event.captured`](/business/events/Event.captured) | By [Event.capture](/business/nouns/event/capture) |
| Emits | [`Visitor.identified`](/business/events/Visitor.identified) | By [Visitor.identify](/business/nouns/visitor/identify) |
| Emits | [`Visitor.merged`](/business/events/Visitor.merged) | By [Visitor.merge](/business/nouns/visitor/merge) |
| Emits | [`Visitor.forgotten`](/business/events/Visitor.forgotten) | By [Visitor.forget](/business/nouns/visitor/forget) |
| Emits | [`Metric.defined`](/business/events/Metric.defined) | By [Metric.define](/business/nouns/metric/define) |
| Emits | [`Metric.queried`](/business/events/Metric.queried) | By [Metric.query](/business/nouns/metric/query) |
| Emits | [`Metric.watched`](/business/events/Metric.watched) | By [Metric.watch](/business/nouns/metric/watch) |

## States
The lifecycle of a [Metric](/business/nouns/metric):

| State | Meaning | Moves to |
| --- | --- | --- |
| `draft` (first) | Its query is written and not compiled, so nothing reads it. | `defined` by [Metric.define](/business/nouns/metric/define) |
| `defined` | Its query compiles against the Startup’s Events and Entries; defining it again recompiles an edited query. | None: it ends here. |

## Who operates it
| Part | This System |
| --- | --- |
| Accountable | [Analyst](/agents/marketing/analyst) |
| Team | [Marketing Team](/agents/marketing) |
| Seat | A role agent holds it until a Human is seated. |
| Autonomy | `supervised` |
| Also calls its Verbs | [Founder](/agents/founding/founder), [Onboarding Specialist](/agents/customer/onboarding-specialist), [Operations Lead](/agents/operations/operations-lead), [Finance Lead](/agents/finance/finance-lead) |

## Approvals and limits
| Verb | Rule | Detail |
| --- | --- | --- |
| [Visitor.forget](/business/nouns/visitor/forget) | A person says yes first | Waits 1 business hour |

## Processes that use it
| Process | How it uses it |
| --- | --- |
| [Iteration](/workflows/processes/iteration) | A step calls [Metric.query](/business/nouns/metric/query) |
| [Onboarding](/workflows/processes/onboarding) | A step calls [Customer.activate](/business/nouns/customer/activate) |
| [Role review](/workflows/processes/role-review) | A step calls [Metric.query](/business/nouns/metric/query) |
| [Runway](/workflows/processes/runway) | A step calls [Metric.query](/business/nouns/metric/query) |

## Rail underneath
None.

## Views and dashboards
| View | Shows | Metrics |
| --- | --- | --- |
| Activation | The funnel from first Visit to first value, and retention by weekly cohort. | [Activation rate](/agents/product#activation-rate), [Month-3 retention](/agents/customer#month-3-retention) |
| The [Analyst](/agents/marketing/analyst)’s view | The Metrics its accountable Role answers for. | [Metric freshness](/agents/marketing#metric-freshness) |

## Access
What each Access level may call here.

| Access level | May call |
| --- | --- |
| `owner` | Every Verb (29) |
| `admin` | All but 1 of 29: `Visitor.forget` |
| `member` | All but 1 of 29: `Visitor.forget` |
| `viewer` | Read only (12 of 29) |

## Import and export
None.

## Fees and pricing
None.

## Availability and limits
| Part | This System |
| --- | --- |
| Status | Live |

## Compliance notes
Recordings mask inputs at capture, and an erasure request removes a Visitor everywhere; what to track stays the founder’s.

Controls it carries:

- [Log completeness](/systems/trust-and-governance/controls/log-completeness)
- [Append-only records](/systems/trust-and-governance/controls/append-only-records)
- [Point-in-time recovery](/systems/trust-and-governance/controls/point-in-time-recovery)
- [Processing definitions](/systems/trust-and-governance/controls/processing-definitions)

## Related Systems
- [Experiments](/systems/experiments)
- [Reports](/systems/reports)
- [Privacy](/systems/privacy)
- [Ads](/systems/ads): also holds [Audience](/business/nouns/audience)
- [Phone](/systems/phone): also holds [Recording](/business/nouns/recording)

## Example
```ts
// A weather-risk Dataset API counts a Customer activated at its first paid Order within 7 days.
import { $ } from 'startup-builder'

const activation = await $.Metric.define({
  name: 'Paid within 7 days',
  query: 'share of Customer.created followed by Order.paid within 7d',
  unit: 'percent',
})

// Which Plays bring Customers who pay? Split the funnel by Acquisition.
await $.Metric.query({ metric: activation.$id, shape: 'funnel', breakdown: 'acquisition.play', window: '30d' })

// Below 30 percent, the Analyst gets a Task to open an Experiment.
await $.Metric.watch({ metric: activation.$id, threshold: 30, direction: 'below' })
```