Developer docs
Analytics definitions
Every number says what it counts, and every comparison says how much it can prove. YouSaid does not report correlation as cause.
Placement engagement
| Metric | Definition |
|---|---|
| view | The placement rendered on a page. Once per page load. |
| impression | Qualified impression: at least 50% of the card was visible for at least one second. |
| video_start | The visitor started playback. |
| video_q25, video_q50, video_q75 | Playback reached 25%, 50% or 75%. |
| video_complete | Playback reached the end. |
| click | A click on the call to action or an About this proof link. |
| fallback | The live render failed and a signed snapshot was shown instead. |
| error | The render failed and nothing was shown. |
| perf | Real-user time from script start to first render, in milliseconds. |
How it is collected
- A first-party beacon posts to YouSaid only. No cookies, no visitor ids and no stored IP addresses. Counts are kept as daily UTC totals per placement and item.
- Dropped before counting: crawler, preview and monitoring user agents; builder previews and components with preview set; disallowed origins; unknown items; paused placements; and more than 30 batches per IP per placement per minute.
Collection funnel
Counted from the Trust Ledger, in order: eligible opportunities, asks approved, requests sent, opened, started, abandoned, submitted, kept private, consent requested, consent granted, consent declined, approved, placed in a wall or widget, and revoked. Opt-outs are tracked separately and sent as proof.request.opted_out.
Interpretation labels
| Label | What it means |
|---|---|
| descriptive | Counts of observed events. Shows what happened, not why. All engagement and funnel numbers are descriptive. |
| associated | Moves together with an outcome. Not evidence of cause. |
| model_estimated | Inferred by a statistical model with stated assumptions. |
| experimentally_estimated | Measured against a randomized holdout. |
| insufficient_evidence | Too little data for a stable number. Rates from fewer than 100 qualified impressions carry this label. |
These five labels are the only ones the workspace, the REST API, exports and the MCP resource yousaid://proof/analytics-definitions use. Only experimentally_estimated supports a causal reading. Older clients may still send observed, assisted, correlated or experiment-supported; YouSaid reads them as descriptive, associated, associated and experimentally_estimated, and reads any unknown word as insufficient_evidence.
Conversions after proof
Your page can report a site conversion, such as signup, trial or purchase, from the page that shows your proof: useProofConversion() in the React SDK, sendProofConversion(name) in @yousaid/core, or the conversion(name) method of the yousaid-proof element. The beacon sends the conversion name and the items that had a qualified impression earlier in the same page load. Nothing else links the two: no cookie, no visitor id, no stored IP address and no tracking across pages or visits.
| Figure | Meaning | Label |
|---|---|---|
| After an impression | Conversions from a page load in which a qualified impression of the placement or story happened first. | associated, or insufficient_evidence below 30 conversions |
| No impression first | Conversions from a page load where the placement rendered but no qualified impression came first. | descriptive |
| Share after an impression | The first figure as a share of all conversions reported on pages with that placement. | associated, or insufficient_evidence below 30 conversions |
A conversion after an impression is an association: the visitor may have converted anyway. Run a placement experiment to estimate lift.
Experiments
A placement experiment shows a holdout share of views (10% by default, up to 50%) the baseline order and compares each variant with it. Results are read only after every arm reaches its minimum views, with the significance level adjusted for the number of variants. Until then, and if the maximum duration passes first, the result is insufficient_evidence. Only a finished experiment is labeled experimentally_estimated.
Pipeline influence
If you push deals from your CRM (POST /api/v1/proof/crm/deals), YouSaid matches them to proof interactions from accounts you identified with the account attribute. YouSaid never calls your CRM.
| Touch | Meaning |
|---|---|
| assisted | A qualified proof impression reached the account within the lookback window (90 days by default) before the deal closed. |
| observed | Someone at the account clicked proof within the lookback window before the deal closed. |
Assisted and observed describe how proof reached an account; they are not evidence labels. Every influence figure is labeled associated. The win-rate comparison of exposed and unexposed accounts is associated, or insufficient_evidence with fewer than 30 closed deals in either group.
Influence is never labeled as caused revenue. Outcomes with no proof interaction are not attributed to proof anywhere.
Proof Health
Proof Health scores each story with deterministic checks: consent completeness, source integrity, freshness, claim specificity and evidence, incentive disclosure, unresolved customer risk, overuse and accessible captions. Scores never reflect sentiment. Overuse covers one story in many placements, and also the same claim or metric (normalized, so small wording changes still match) on 6 or more placements and approved assets, the same quote on 6 or more, one Studio asset in 4 or more placements, and any of these on 4 or more channels. The gap map lists missing, stale or thin coverage by persona, use case, industry, company size, outcome category, objection, geography, format and freshness. It is a maintenance signal, not a measure of authenticity.