> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Review pageviews and traffic breakdowns for your published site.

Fimo Analytics shows how people find and use your published website: visitors,
pageviews, popular pages, traffic sources, devices and approximate countries.
Open your site's **Analytics** workspace in Studio to explore the results.
Known bot traffic is excluded from the main metrics.

## Install pageview tracking

Your website needs a browser tracker to record visits. Projects created with
`fimo init` already include it. For an older project, add `fimo-analytics` and
mount its component once in your root layout:

```bash theme={null}
pnpm add fimo-analytics
```

```tsx theme={null}
import { Analytics } from 'fimo-analytics/next'; // or /react-router, /react, /vue

<Analytics />;
```

Astro, Svelte and SvelteKit use a default import, such as
`import Analytics from 'fimo-analytics/astro'`. Nuxt adds
`modules: ['fimo-analytics/nuxt']` to `nuxt.config`.

The component needs no configuration. Fimo hosting tells it where to send
visits, turns it on for your published site, and keeps it off in previews and
local development. If your website already has a tracker, keep only one; two
trackers count the same visit twice.

You can also ask your connected coding agent:

```text theme={null}
Enable Fimo pageview analytics on this website. Check for an existing tracker
first, then install fimo-analytics and mount its component for this framework.
```

Your agent can read the framework setup instructions with
`fimo skills get fimo-code --ref analytics`. See [Connect your coding agent](/docs/get-started/coding-agent.md#give-your-agent-fimo-skills)
if you haven't connected one yet.

> [!NOTE]
>
> Browser tracking uses a public endpoint and needs no API key. Never put private API keys, access tokens or server
> credentials in your website's browser code.

After publishing, open the live website and visit a few pages. Return to
**Analytics** to check that pageviews arrive. Installing the package alone does
not enable tracking; the website must render the component.

## Updating an existing website

From 2.8.0, React Router and Vite + React websites track pageviews with the same
`<Analytics />` component as every other framework. If your website tracked
visits before, add the one-line setup above when you run `fimo update`.

`fimo update` updates `fimo-analytics` when your site already uses it.
Updating packages alone never adds a tracker.

After publishing your updated website, verify new pageviews in Studio.
Your existing analytics history remains available.

## Verify tracking in Studio

Open your site's **Analytics** workspace after publishing. Publishing alone
does not confirm that your website sends pageviews.

* **Waiting for the first pageview** means Fimo has no stored pageviews for the
  published site. Select **Open site** to visit it. If nothing arrives, use
  **Set up tracking** to check the installation and endpoint.
* **Pageviews received** shows when Fimo last received a pageview. This status
  uses the available history, independently of the date range and device filter
  selected for the charts. A quiet reporting period does not mean the tracker
  is missing, and an old pageview does not prove that the current deployment
  still sends events.
* **Tracking status unavailable** means Fimo could not check. Select
  **Check again** to retry. Available charts remain visible.

While you keep Analytics open, it checks for the first pageview and refreshes
the charts automatically. Visits can take a short time to appear. If nothing
arrives, check the setup with your coding agent; browser privacy tools can also
block tracking.

## Review traffic

```bash theme={null}
fimo analytics pageviews --days 7
fimo analytics top pages
fimo analytics top countries
```

Reads default to the published `prod` target, even when your checkout is on `main` or another branch. Add `--json` to include the selected `branch` in structured results. To select a branch explicitly:

```bash theme={null}
fimo --branch prod analytics pageviews --days 7 --json
```

An explicit `--branch` takes precedence. Zero metrics from a preview branch do not describe published traffic. If the published target is unavailable or you lack access, the command fails; it does not switch to another branch.

`pageviews` returns the headline metrics, a time series, and top breakdowns. Use `top` when you only need one breakdown.

Available top dimensions are `pages`, `browsers`, `devices`, `countries`, and `sources`.

## Country estimates

Country is approximate. It can come from country information supplied with a visit
or, where available, a server-side IP lookup. VPNs, proxies and mobile networks can
make the estimate differ from the visitor's location. It is not verified residency.

When no country can be determined, the pageview still counts under `Unknown`.
Country lookup does not send the visitor's IP to an external geolocation service
or add it to the stored pageview. Existing visits keep their recorded country;
new estimates do not rewrite your analytics history.

## Bots are not visitors

AI crawlers and headless browsers are identified when they arrive and left out of visitors,
pageviews, bounce rate, visit duration, the chart and every breakdown. This is not a setting — it
is what the numbers mean.

To be precise: this excludes traffic Fimo **recognizes** as a bot. A visit with no usable
identification is still counted, so the figures are "known bots removed" rather than a guarantee
that every remaining visit was a person.

The dashboard still tells you how much was excluded, under the date range:

```
18,940 bot pageviews excluded · View bot traffic
```

Follow that link, or pass `--device bot`, to look at the excluded traffic. Expect a bounce rate
near 100% and a visit duration of 0 — that is what a crawler looks like, not a fault. The
**Top bots** breakdown names the crawler.

```bash theme={null}
fimo analytics pageviews --device bot --days 30
```

> [!NOTE]
>
> If you are comparing against a figure you noted before this change, the drop is bots leaving the count, not traffic
> you lost. `botPageviews` in the response says how much of the old number was never a person.

## Which AI assistants send you readers

When someone follows a citation inside ChatGPT, Perplexity or Claude, they arrive on your site
with that assistant as the source. The **AI assistants** card names them, and **Top sources**
folds them into one `AI assistants` channel alongside Google, Direct and the rest.

Two honest limits:

* Readers arriving from an assistant's **desktop or phone app** usually carry no source at all
  and land in `Direct`. The number is a floor, not a full count. Every analytics product shares
  this limitation.
* Being **cited without being clicked** is invisible. This measures arrivals, not mentions. No
  assistant passes on what the person asked.

## Choose a date range

Use a preset or an explicit range:

```bash theme={null}
fimo analytics pageviews --preset last_7_days
fimo analytics pageviews --from 2026-08-01 --to 2026-08-07
```

Available date ranges and retention depend on your plan. The CLI tells you when a requested range requires an upgrade. See [Fimo pricing](https://fimo.ai/pricing) for current details.

## Mark a launch or change

Annotations add a dated note to the analytics chart. Reads default to `prod`; setting and deleting notes use your current or explicit Branch and require its existing permissions:

```bash theme={null}
fimo analytics annotations set 2026-08-25 "Launched new homepage"
fimo analytics annotations list --days 30
fimo analytics annotations delete 2026-08-25
```

Use them for launches or other changes that may explain a traffic shift.

## What's next

> [card] [Launch checklist](/docs/environments/launch-checklist.md)
>
> Verify production before watching traffic.

> [card] [Custom domains](/docs/deploy/custom-domains.md)
>
> Choose the public URL.

> [card] [Deploy & publish](/docs/deploy/overview.md)
>
> Publish the site that analytics measures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.