---
title: Measure usage and collect feedback
description: Enable Thally analytics and page ratings, persist events, and use the results to improve documentation.
url: https://pr-7-a9c4e9fe1b6c.thally.app/guides/analytics-and-feedback
---

# Measure usage and collect feedback

Enable Thally analytics and page ratings, persist events, and use the results to improve documentation.

Thally can record page views, searches, agent traffic, and page feedback. The
analytics service and dashboard are Thally Cloud capabilities; the open-source
runtime keeps the integration points but safely no-ops when no service is
connected.

## Enable the site controls

Set the file defaults in `docs.json`:

```json
{
  "analytics": {
    "enabled": true
  },
  "feedback": {
    "thumbsRating": true,
    "endpoint": "/api/feedback"
  }
}
```

| Field | Default | Purpose |
| --- | --- | --- |
| `analytics.enabled` | `true` | Allows collection when a connected analytics service provides it. Set `false` to opt out. |
| `feedback.thumbsRating` | `true` | Shows or hides the helpful/not-helpful control. |
| `feedback.endpoint` | `/api/feedback` | Receives page ratings and optional written follow-ups. |

The built-in endpoint accepts a rating without allowing an analytics failure to
break the reader's request. On an unconnected open-source site, it does not
create a durable feedback store. Replace the route with your own integration if
you want self-managed storage or forwarding.

## Connect analytics

Connect the deployment to Thally Cloud, open the site, then select
**Analytics**. The Cloud dashboard separates human and agent traffic and
shows engagement and discovery signals for the selected site. When analytics
is not included in the workspace plan, the page explains the requirement
instead of presenting empty data as a successful setup.

For a self-hosted runtime, `/admin/analytics` uses the same service bridge when
the deployment has a valid Cloud connection.

You do not need to configure an analytics database for a managed Cloud site.
If you operate the open-source runtime and need site-local analytics to survive
redeploys, see [Self-hosted settings](/guides/environment-variables#keep-self-hosted-state-after-a-redeploy).

## Cookies and consent

Thally's native traffic collection runs on the server. It records the requested
path, content slug, request format, referrer, and whether the request appears to
come from a human or an agent. It does **not** create a persistent visitor ID or
analytics cookie, so a public site using only native Thally analytics does not
need a cookie banner for that feature.

Thally does use strictly necessary, `HttpOnly` cookies when you enable features
that require a session:

- admin password or OIDC sign-in;
- password-protected documentation;
- the short-lived OIDC login flow.

Those cookies use `SameSite=Lax`, are marked `Secure` in production, and are not
used for advertising or cross-site tracking. A dismissible site banner stores
its dismissed state in `localStorage`, not a cookie.

> **Warning:**
Google Analytics, PostHog, advertising pixels, embedded media, or custom scripts
may set cookies or similar identifiers. If you enable them, add consent controls
that match the providers, your configuration, and the regions you serve. Do not
show a generic consent banner that cannot actually prevent those scripts from
loading.

## Review useful signals

Use the dashboard to look for:

- high-traffic pages with negative ratings;
- repeated searches that return weak results;
- important tasks with little traffic because readers cannot find them;
- differences between human and agent access;
- content gaps that should become a focused guide or reference page.

Treat a rating as a prompt to investigate, not proof that one paragraph caused
the problem. Read the page, reproduce the task, and update the permanent docs.

## Verify collection

1. Open a page on the deployed site.
2. Run a search.
3. Submit a positive and a negative rating on test pages.
4. Confirm the events appear in the connected analytics dashboard.
5. If they do not, inspect the browser requests to `/api/analytics/collect` and
   `/api/feedback`, then check server logs and storage variables.

## Next steps

- [Manage sites with Thally Cloud](/guides/thally-cloud)
- [Manage the built-in site admin](/guides/admin-dashboard)
- [Self-hosted settings](/guides/environment-variables)
- [Troubleshoot a deployment](/guides/troubleshooting)