# Analytics

Privacy-first, consent-gated visitor analytics — pageviews, sources, devices, custom events, and conversions.

Source: https://docs.annot8.app/docs/analytics/overview



Analytics is a lightweight, cookieless visitor analytics layer that rides along
with the widget you already have installed. It's a **Pro** feature and it is
**off by default**.

## Turning it on [#turning-it-on]

Both of these are required. Neither is enough on its own.

<Steps>
  <Step>
    ### Enable it on the project [#enable-it-on-the-project]

    **Project → Settings → Features → Analytics**.
  </Step>

  <Step>
    ### Pass consent from your page [#pass-consent-from-your-page]

    ```html
    <script
      src="https://www.annot8.app/widget.js"
      data-project-id="pj_xxxxxxxxxxxx"
      data-convex-url="https://your-deployment.convex.cloud"
      data-analytics-consent="true"
      async
    ></script>
    ```

    Or, from your consent-management platform, once the visitor has agreed:

    ```js
    window.Annot8("init", {
      projectId: "pj_xxxxxxxxxxxx",
      convexUrl: "https://your-deployment.convex.cloud",
      analyticsConsent: true,
    });
    ```
  </Step>
</Steps>

<Callout type="warn">
  Do not hard-code `data-analytics-consent="true"` for visitors in the EEA or
  the UK. Wire it to your consent manager, and describe Annot8 in your own
  privacy and cookie notices. See [Privacy](/docs/security/privacy).
</Callout>

Analytics is the one part of the widget that keeps running on production hosts
even when the panel is hidden — collection and the feedback UI are independent.

## The views [#the-views]

| View                                   | Shows                                                                                                  |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Overview**                           | Unique visitors, page views, average session length, bounce rate, with top pages, sources, and devices |
| **Real-time**                          | Active visitors right now and what they're looking at                                                  |
| **Pages**                              | Page-by-page views, with scroll depth                                                                  |
| **Sources**                            | Referrers, and UTM campaigns                                                                           |
| **Countries**                          | Visitors by country                                                                                    |
| **Devices**                            | Device type, browser, and OS breakdown                                                                 |
| **Events**                             | Clicks, scrolls, custom events, conversions, and errors                                                |
| **[Funnels](/docs/analytics/funnels)** | Conversion paths you define                                                                            |
| **Privacy & data**                     | The on/off switch, what is and isn't collected, and deleting all collected data                        |

Most views support a date range of today, 7, 30, or 90 days.

## What's collected [#whats-collected]

| Signal       | Detail                                                                  |
| ------------ | ----------------------------------------------------------------------- |
| Pageviews    | Page origin and path, title, referrer origin and path                   |
| Sessions     | Entry and exit page, duration, page count, bounce, max scroll depth     |
| Visitor      | A random id stored in the browser — no cookie, no cross-site identifier |
| UTM          | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`   |
| Device       | Device type, browser, OS, screen size                                   |
| Country      | Two-letter country code from the edge network — never the IP address    |
| Interactions | Clicks (selector and text), scroll depth, JS errors                     |
| Custom       | Whatever you send via `track` and `trackConversion`                     |

**URLs are minimised.** Only the origin and path are stored. Query strings,
hash fragments, and any embedded credentials are stripped, and email addresses
or token-shaped path segments are redacted, because those routinely carry
personal data. UTM tags are the one exception: they are read from the query
string as separate fields. The server re-applies the same rules, so an old or
modified widget can't store more.

**Country comes from the edge.** The country code is read from the hosting
edge's geolocation header. The visitor's IP address is not stored or passed on
for analytics.

**Some browsers are never measured.** A visitor whose browser sends a
[Global Privacy Control](https://globalprivacycontrol.org) signal is not
tracked, even with consent passed. Headless browsers, crawlers, and audit tools
like Lighthouse are excluded too, so they don't inflate your numbers.

The visitor id is random, generated in the browser, and scoped to your site. It
is not derived from an IP address, a fingerprint, or anything shared between
sites.

## Custom events [#custom-events]

```js
// A named event with arbitrary properties
window.Annot8("track", "signup_clicked", { plan: "pro" });

// A conversion, with an optional monetary value
window.Annot8("trackConversion", "purchase", 49.99);
```

Both are no-ops when Analytics is disabled or unconsented — nothing is
transmitted and nothing throws, so you can leave the calls in place
unconditionally and let the toggle decide.

Event properties are capped at 25 keys per event.

## Withdrawing consent [#withdrawing-consent]

Re-initialise with consent off:

```js
window.Annot8("init", {
  projectId: "pj_xxxxxxxxxxxx",
  convexUrl: "https://your-deployment.convex.cloud",
  analyticsConsent: false,
});
```

Your consent manager should also clear the host-page storage keys, which are
suffixed with the project id: `ca_visitor_id:<projectId>` in `localStorage`, and
`ca_session_id:<projectId>`, `ca_session_start:<projectId>`, and
`ca_session_activity:<projectId>` in `sessionStorage`.

## Retention and deletion [#retention-and-deletion]

Analytics events and sessions are deleted automatically after **13 months**.
Sessions that go quiet without an end beacon are finalised after 30 minutes of
inactivity, so a closed laptop doesn't leave a session open forever.

To erase everything collected so far, open **Analytics → Privacy & data** and
use **Delete all analytics data**. It removes every event, session, and aggregate for the
project in the background; your funnel definitions are kept. Owners and admins
can do this.

## What Annot8 Analytics is not [#what-annot8-analytics-is-not]

It isn't a replacement for a full product-analytics suite, and it deliberately
doesn't do cross-site tracking, advertising identifiers, or session replay.
It's here to answer "which pages matter, where do people come from, and did they
get through the flow" — next to the feedback about those same pages.