rybbit Documentation

Content Docs (Docs) Mcp Index (`docs/content/docs/(docs)/mcp/index.mdx`) Copy Section

title: MCP Copy Chapter

import { Callout } from "fumadocs-ui/components/callout";
import { Cards, Card } from "fumadocs-ui/components/card";
import { SiClaude } from "@icons-pack/react-simple-icons";

Rybbit includes a hosted Model Context Protocol (MCP) endpoint. It gives an AI assistant read and write access to your analytics: exploring traffic and behavior data, and managing sites, goals, funnels, organization members, teams, and user profiles — through the same API the dashboard uses, with the same access checks, roles, and rate limits.

Your MCP client connects to Rybbit over HTTPS and sends your API key with each protocol request. Rybbit verifies the key before processing any message, and every tool call is authorized against the key user's role and site access.

Connect a client Copy Chapter

If your client supports the MCP authorization flow — Claude Code, Codex, Claude Desktop, and opencode all do — you can connect with OAuth and skip API keys entirely. The steps below describe the API-key path, which works in every client and supports scoped credentials.

1. Create an API key Copy Section

1. Open Settings → Account in Rybbit.
2. Create a key in the Personal API Keys section.
3. Copy it immediately. Rybbit only shows a new key once.

A key created without permissions can do everything its user can do. To hand an agent a narrower credential, create the key with scoped permissions (POST /api/user/api-keys with a permissions object, e.g. {"analytics": ["read"], "goals": ["read", "write"]}): the MCP tool list and every API call are then limited to those resource:action scopes. write implies read on the same resource, and scopes never elevate — org admin/owner requirements still apply. Deleting the key revokes the connection.

2. Add the endpoint Copy Section

Use this Streamable HTTP URL for Rybbit Cloud:

https://app.rybbit.io/api/mcp

For a self-hosted installation, replace the host with your configured BASE_URL:

https://analytics.example.com/api/mcp

Configure your client to send this header on every request:

Authorization: Bearer <RYBBIT_API_KEY>

MCP clients use different configuration formats. A typical remote-server configuration has this shape:

{
  "mcpServers": {
    "rybbit": {
      "url": "https://app.rybbit.io/api/mcp",
      "headers": {
        "Authorization": "Bearer <RYBBIT_API_KEY>"
      }
    }
  }
}

Use your client's secret or environment-variable support when available instead of saving the key in a file. Query-string API keys are not accepted by the MCP endpoint. Per-client walkthroughs — Claude Code, Codex, Claude Desktop, Cursor, VS Code, opencode — are in Client guides below.

Or connect with OAuth Copy Section

Clients that support the MCP authorization flow can skip API keys entirely: add the endpoint URL with no headers, and the client discovers Rybbit's authorization server through the standard well-known metadata (/.well-known/oauth-protected-resource), registers itself, and opens a browser window for you to log in and approve access. The resulting access token acts with your user's role, exactly like an API key would.

OAuth grants support the same resource:action scopes as API keys (advertised in scopes_supported). A grant that requests only the standard OIDC scopes is unrestricted; a grant that requests custom scopes like analytics:read is limited to them. The requesting client controls which scopes it asks for — consent is currently approve-or-deny as a whole.

3. Start with context Copy Section

Ask the assistant to call list_sites, or prompt it with something like:

List my Rybbit sites, summarize last month's traffic for the docs site, and create a goal for signups.

list_sites returns the numeric site_id and organization_id required by the other tools, plus the key's role in each organization. It does not return API keys or member email addresses.

Client guides Copy Chapter

Coding agents can use the endpoint to pull analytics into your development workflow — checking whether an error you just fixed still occurs in production, or looking up which pages matter before a refactor — and chat clients like Claude Desktop turn it into a conversational analytics interface. Follow the guide for your client:

Any other MCP client that supports Streamable HTTP works with the generic configuration from step 2.

Available tools Copy Chapter

Analytics (read) Copy Section

Search Console (read) Copy Section

Search Console tools read the Google Search Console property connected to the site under Site settings > Integrations (Rybbit Cloud); no Google Cloud project or separate MCP server is needed. get_search_console_data groups by up to three dimensions (query, page, country, device, date), accepts ANDed filters such as {"dimension": "page", "operator": "contains", "expression": "/pricing"}, and returns 100 rows by default (up to 25,000, paged with start_row). Google's numbers lag about two days; pass data_state: "all" to include fresh, still-changing data. For how this compares with self-run Search Console servers, and prompts that work well, see the Google Search Console MCP guide.

Sites Copy Section

Goals & funnels Copy Section

People Copy Section

Organization & teams Copy Section

Raw data & SQL Copy Section

Analytics tools accept optional time inputs (start_date/end_date with an IANA time_zone, or past_minutes) and the same filters as the dashboard. Omitting time inputs queries all time; an unrecognized time_zone is rejected before the call is made. get_sessions, get_events, and get_users accept an optional fields list to return only the named row columns, which keeps large result sets small.

Permissions and roles Copy Chapter

The MCP surface mirrors the REST API's permission model:

• Read tools work for any role with access to the site, including viewers.
• Write tools need the member role or above on the site (goals, funnels, identify_user, update_user_traits, save_funnel).
• Tools marked (editor) need the editor role or above on the site.
• Tools marked (admin) require the API key's user to hold the admin or owner role in the organization. add_member can't grant a role above the key's own, so only an owner's key can grant owner.

A key acts with its user's role on each site, including site-specific roles from site restrictions and teams, and it reaches exactly the sites that user can see. The REST layer enforces all of this: an underprivileged key gets a 403 "Insufficient role" naming the role required.

To give an assistant a read-only or read-mostly view, create a scoped API key (see step 1): grant only the resource:action scopes it needs — e.g. {"analytics": ["read"], "sessions": ["read"]} for a reporting agent. The MCP tool list is filtered to those scopes, and any out-of-scope call returns 403 { "error": "Insufficient scope", "required": "goals:write" }. Alternatively, connect with a viewer's key: it hides nothing but refuses every write.

OAuth clients request scopes through the standard grant. Rybbit advertises the same resource:action scopes in its discovery metadata; a grant carrying no custom scopes (or only the standard OIDC scopes) is treated as full access, for backward compatibility.

Destructive tools Copy Chapter

delete_goal, delete_funnel, delete_site, delete_team, and delete_user permanently destroy data and are marked with the MCP destructiveHint annotation, so well-behaved clients ask for confirmation before invoking them. delete_site and delete_user (the GDPR-erasure path) also remove recorded events and replays, with erasure completing asynchronously.

Data and security boundary Copy Chapter

• The API key is verified before any MCP message is processed, and each tool call re-runs the corresponding REST route's own access checks, role requirements, and rate limits.
• The surface returns whatever the REST API returns for your role — including session-level records and, where a site has IP tracking enabled, visitor IP addresses. Connect only AI clients you trust with that data, and use a separate, revocable API key per integration.
• Text originating in tracked traffic (page titles, paths, referrers, event names, traits) is stripped of control and bidi-override characters. AI clients should still treat these values as untrusted data, never as instructions.
• run_query is restricted to a read-only, site-scoped table with row and execution-time caps.
• The server does not contain an AI model or send analytics to an AI provider. Data only leaves Rybbit in response to the MCP client you configure.
• The endpoint is stateless. Each HTTP request is independently authenticated.

Troubleshooting Copy Chapter

• 401 Unauthorized: The client did not send a Bearer credential, or the key/token is invalid, expired, or revoked. OAuth-capable clients re-authenticate automatically via the WWW-Authenticate challenge.
• OAuth login loop or "table does not exist" (self-hosted): Run npm run db:push in server/ to create the OAuth tables, then retry.
• 403 in tool results: The key's user lacks access to that site or organization, or holds too low a role for the tool ("Insufficient role" names the role required). Check the role field in list_sites.
• 403 "Insufficient scope": The credential was created without the resource:action scope this tool needs (the required field names it). Use a key or OAuth grant that includes it.
• 429 Too Many Requests: The API key exceeded its plan's rate limit.
• 404 "GSC not connected" from Search Console tools: Connect Google Search Console for that site under Site settings > Integrations, then retry.
• 503 Service Unavailable: Rybbit could not verify the key. Retry the request; do not replace a known-valid key based on this response.
• 405 Method Not Allowed on GET: This is expected. The stateless endpoint accepts MCP messages over POST.
• Site access error: Call list_sites again. Membership or site permissions may have changed.

Content Docs (Docs) Proxy Guide Index (`docs/content/docs/(docs)/proxy-guide/index.mdx`) Copy Section

title: Proxy Setup Guide Copy Chapter

import { Cards, Card } from 'fumadocs-ui/components/card';
import { Callout } from 'fumadocs-ui/components/callout';
import {
SiAstro,
SiCloudflare,
SiExpress,
SiLaravel,
SiNextdotjs,
SiNginx,
SiVercel
} from '@icons-pack/react-simple-icons';

Proxying Rybbit's tracking script through your own domain helps bypass ad blockers and improves tracking accuracy by making all analytics requests appear as first-party traffic.

What is Proxy Setup? Copy Chapter

When you add Rybbit's tracking script directly to your website using the default installation:

<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>

The browser loads the script from app.rybbit.io, which ad blockers can identify and block as third-party analytics. Even though Rybbit is privacy-focused and doesn't use cookies, some ad blockers use aggressive blocking rules that target any analytics domains.

Proxying solves this by serving the tracking script and handling tracking requests through your own domain (e.g., yourdomain.com/analytics/script.js), making all tracking appear as first-party traffic.

Why Proxy Rybbit? Copy Chapter

Improve Tracking Accuracy Copy Section

Ad blockers are becoming increasingly aggressive and may block analytics scripts regardless of their privacy practices. By proxying through your own domain:

• Bypass ad blocker detection: Requests appear as first-party traffic to your own domain
• Increase data completeness: Typical improvement of 10-30% in tracked sessions
• Maintain accurate metrics: Get a true picture of your website's performance

Stay Privacy-Compliant Copy Section

Proxying doesn't compromise user privacy:

• No cookies are used (Rybbit remains cookieless)
• User data is still processed according to your privacy policy
• GDPR, CCPA, and other privacy regulations remain fully satisfied
• Users can still opt out through browser settings or Do Not Track

Better Performance (Optional) Copy Section

With proper caching configuration, proxying can also improve performance:

• Serve scripts from your CDN or edge network
• Reduce DNS lookups (one less domain to resolve)
• Cache static scripts closer to your users

How It Works Copy Chapter

Here's the flow when you proxy Rybbit:

1. User visits your website: Your HTML includes the tracking script from your domain

   html Copy

   <script src="https://yourdomain.com/analytics/script.js" data-site-id="123"></script>

2. Script loads from your domain: Your server proxies the request to Rybbit's servers

   • Request: yourdomain.com/analytics/script.js → proxied to → app.rybbit.io/api/script.js

3. Script auto-discovers analytics host: The Rybbit script automatically detects the domain it was loaded from

   typescript Copy

   // The script extracts the host from its own src attribute
   const analyticsHost = src.split("/script.js")[0];
   // Result: "https://yourdomain.com/analytics"

4. Tracking data sent through your domain: All analytics events are sent to your domain and proxied to Rybbit

   • Event tracking: yourdomain.com/analytics/track → proxied to → app.rybbit.io/api/track
   • Session replay: yourdomain.com/analytics/session-replay/record/{siteId} → proxied
   • Configuration: yourdomain.com/analytics/site/tracking-config/{siteId} → proxied

5. Data appears in your Rybbit dashboard: No changes needed in the Rybbit interface

Choose Your Framework Copy Chapter

Select the framework or platform that matches your setup:

Generic Implementation Copy Chapter

If your framework isn't listed above, check out our generic implementation guide that covers the core concepts applicable to any reverse proxy or server setup.

Need Help? Copy Chapter

If you encounter issues during setup, check our troubleshooting guide for common problems and solutions.

Content Docs Api Bots Overview (`docs/content/docs/api/bots/overview.mdx`) Copy Section

title: Get Bot Overview full: true method: GET Copy Chapter

import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

GET /api/sites/:site/bots/overview

Returns aggregate bot-traffic metrics with a breakdown by detection layer.

Path Parameters Copy Section

<TypeTable
type={{
site: {
type: 'string | number',
required: true,
},
}}
/>

Query Parameters Copy Section

Accepts all Common Parameters (time and filters).

Bot filtering supports a subset of filter parameters: browser, browser_version, operating_system, operating_system_version, country, region, city, device_type, referrer, hostname, pathname, querystring, dimensions, user_id, lat, and lon.

<TypeTable
type={{
layer: {
type: 'string',
typeDescription: '"ua_pattern" | "header_heuristics" | "client_signals" | "bot_asn" | "rate_anomaly"',
required: false,
},
}}
/>

Response Copy Section

<TypeTable
type={{
bot_requests: {
type: 'number',
},
total_events: {
type: 'number',
},
bot_percentage: {
type: 'number',
typeDescription: 'Range: 0-100',
},
ai_requests: {
type: 'number',
},
ai_agent_requests: {
type: 'number',
},
ai_crawler_requests: {
type: 'number',
},
ua_pattern: {
type: 'number',
},
header_heuristics: {
type: 'number',
},
client_signals: {
type: 'number',
},
bot_asn: {
type: 'number',
},
rate_anomaly: {
type: 'number',
},
}}
/>

<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}>

curl -X GET "https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
  -H "Authorization: Bearer your_api_key_here"

</Tab>
  <Tab value="Python">
```python title="Request"
import requests

response = requests.get(
    'https://app.rybbit.io/api/sites/123/bots/overview',
    params={
        'start_date': '2024-01-01',
        'end_date': '2024-01-31',
        'time_zone': 'America/New_York'
    },
    headers={
        'Authorization': 'Bearer your_api_key_here'
    }
)

data = response.json()

</Tab>
  <Tab value="Ruby">
```ruby title="Request"
require 'net/http'
require 'json'

uri = URI('https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer your_api_key_here'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

</Tab>
  <Tab value="Rust">
```rust title="Request"
let client = reqwest::Client::new();
let res = client
    .get("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
    .header("Authorization", "Bearer your_api_key_here")
    .send()
    .await?;

let data: serde_json::Value = res.json().await?;

</Tab>
  <Tab value=".NET">
```csharp title="Request"
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/bots/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
var data = await response.Content.ReadAsStringAsync();

{
  "data": {
    "bot_requests": 1840,
    "total_events": 48933,
    "bot_percentage": 3.76,
    "ai_requests": 940,
    "ai_agent_requests": 180,
    "ai_crawler_requests": 760,
    "ua_pattern": 1200,
    "header_heuristics": 410,
    "client_signals": 95,
    "bot_asn": 120,
    "rate_anomaly": 15
  }
}

Content Docs Api Overview Overview (`docs/content/docs/api/overview/overview.mdx`) Copy Section

title: Get Overview full: true method: GET Copy Chapter

import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

GET /api/sites/:site/overview

Returns high-level analytics metrics for a site.

Path Parameters Copy Section

<TypeTable
type={{
site: {
type: 'string | number',
required: true,
},
}}
/>

Query Parameters Copy Section

Accepts all Common Parameters (time and filters).

Response Copy Section

<TypeTable
type={{
sessions: {
type: 'number',
},
pageviews: {
type: 'number',
},
users: {
type: 'number',
},
pages_per_session: {
type: 'number',
},
bounce_rate: {
type: 'number',
typeDescription: 'Range: 0-100',
},
session_duration: {
type: 'number',
},
}}
/>

<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}>

curl -X GET "https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York" \
  -H "Authorization: Bearer your_api_key_here"

</Tab>
  <Tab value="Python">
```python title="Request"
import requests

response = requests.get(
    'https://app.rybbit.io/api/sites/123/overview',
    params={
        'start_date': '2024-01-01',
        'end_date': '2024-01-31',
        'time_zone': 'America/New_York'
    },
    headers={
        'Authorization': 'Bearer your_api_key_here'
    }
)

data = response.json()

</Tab>
  <Tab value="Ruby">
```ruby title="Request"
require 'net/http'
require 'json'

uri = URI('https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer your_api_key_here'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

</Tab>
  <Tab value="Rust">
```rust title="Request"
let client = reqwest::Client::new();
let res = client
    .get("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York")
    .header("Authorization", "Bearer your_api_key_here")
    .send()
    .await?;

let data: serde_json::Value = res.json().await?;

</Tab>
  <Tab value=".NET">
```csharp title="Request"
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

var response = await client.GetAsync("https://app.rybbit.io/api/sites/123/overview?start_date=2024-01-01&end_date=2024-01-31&time_zone=America/New_York");
var data = await response.Content.ReadAsStringAsync();

{
  "data": {
    "sessions": 15420,
    "pageviews": 48933,
    "users": 12847,
    "pages_per_session": 3.17,
    "bounce_rate": 42.8,
    "session_duration": 182.5
  }
}

Content Docs Api Performance Overview (`docs/content/docs/api/performance/overview.mdx`) Copy Section

title: Get Performance Overview full: true method: GET Copy Chapter

import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

GET /api/sites/:site/performance/overview

Returns aggregate performance metrics with percentile breakdowns for all Core Web Vitals.

Path Parameters Copy Section

<TypeTable
type={{
site: {
type: 'string | number',
required: true,
},
}}
/>

Query Parameters Copy Section

Accepts all Common Parameters (time and filters).

Response Copy Section

<TypeTable
type={{
data: {
type: 'PerformanceMetrics',
},
}}
/>

PerformanceMetrics Object

Each metric (lcp, cls, inp, fcp, ttfb) includes the following percentiles:

<TypeTable
type={{
lcp_p50: {
type: 'number',
typeDescription: 'milliseconds',
},
lcp_p75: {
type: 'number',
typeDescription: 'milliseconds',
},
lcp_p90: {
type: 'number',
typeDescription: 'milliseconds',
},
lcp_p99: {
type: 'number',
typeDescription: 'milliseconds',
},
total_performance_events: {
type: 'number',
},
}}
/>

<Tabs items={['cURL', 'JavaScript', 'Python', 'PHP', 'Ruby', 'Go', 'Rust', 'Java', '.NET']}>

curl -X GET "https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer your_api_key_here"

</Tab>
  <Tab value="Python">
```python title="Request"
import requests

response = requests.get(
    'https://app.rybbit.io/api/sites/1/performance/overview',
    params={
        'start_date': '2024-01-01',
        'end_date': '2024-01-31'
    },
    headers={
        'Authorization': 'Bearer your_api_key_here'
    }
)

data = response.json()

</Tab>
  <Tab value="Ruby">
```ruby title="Request"
require 'net/http'
require 'json'

uri = URI('https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer your_api_key_here'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

</Tab>
  <Tab value="Rust">
```rust title="Request"
let client = reqwest::Client::new();
let res = client
    .get("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31")
    .header("Authorization", "Bearer your_api_key_here")
    .send()
    .await?;

let data: serde_json::Value = res.json().await?;

</Tab>
  <Tab value=".NET">
```csharp title="Request"
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer your_api_key_here");

var response = await client.GetAsync("https://app.rybbit.io/api/sites/1/performance/overview?start_date=2024-01-01&end_date=2024-01-31");
var data = await response.Content.ReadAsStringAsync();

{
  "data": {
    "lcp_p50": 1850,
    "lcp_p75": 2400,
    "lcp_p90": 3200,
    "lcp_p99": 5100,
    "cls_p50": 0.05,
    "cls_p75": 0.1,
    "cls_p90": 0.18,
    "cls_p99": 0.35,
    "inp_p50": 120,
    "inp_p75": 180,
    "inp_p90": 280,
    "inp_p99": 450,
    "fcp_p50": 1200,
    "fcp_p75": 1600,
    "fcp_p90": 2100,
    "fcp_p99": 3500,
    "ttfb_p50": 450,
    "ttfb_p75": 650,
    "ttfb_p90": 950,
    "ttfb_p99": 1800,
    "total_performance_events": 48521
  }
}

CLAUDE (`docs/CLAUDE.md`) Copy Section

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands Copy Chapter

• Dev: npm run dev (Next.js with Turbopack on port 3003)
• Build: npm run build
• Production: npm start
• Type Check: tsc --noEmit
• Lint integration guides: npm run lint:guides (rules in content/partials/guides/README.md; copy TEMPLATE.mdx for a new guide)

Project Overview Copy Chapter

This is the documentation and marketing website for Rybbit, built with Next.js 16 and Fumadocs. The site includes:

• Documentation pages (using Fumadocs MDX)
• Blog (separate content collection)
• Marketing pages (home, pricing, features, comparison pages)
• Analytics tools (SEO, ROI calculators, privacy policy builder, etc.)
• LLM-friendly documentation endpoints
• The domain is rybbit.com

Code Architecture Copy Chapter

Content Management Copy Section

• Fumadocs MDX: Documentation system using fumadocs-mdx for MDX processing
• Source Configuration: source.config.ts defines two content collections:
  • docs: Documentation pages in content/docs/
  • blog: Blog posts in content/blog/ with extended frontmatter (date, author, image, tags)
• Source Adapters:
  • src/lib/source.ts: Docs source loader (base URL: /docs)
  • src/lib/blog-source.ts: Blog source loader (base URL: /blog)
• Auto-generated: .source/ directory contains generated TypeScript from MDX files

Route Structure Copy Section

• app/(home)/*: Marketing pages (landing, pricing, features, comparison pages, tools)
• app/docs/[[...slug]]/: Documentation pages using catch-all routing
• app/blog/: Blog listing and individual posts
• app/api/search/: Documentation search powered by Orama
• app/api/tools/: API endpoints for tool functionality (SEO generators, analytics detector, etc.)
• app/llms.mdx/ and app/llms-full.txt/: LLM-optimized documentation endpoints

Internationalization (i18n) Copy Section

• Library: next-intl v4 with experimental extract mode enabled
• Supported Locales: en (default), de, fr, zh, es, pl, it, ko, pt, ja
• Message Files: messages/{locale}.json — one JSON file per locale with ~242 keys
• Config Files in src/i18n/:
  • routing.ts: Locale list and prefix strategy (as-needed — no prefix for default en)
  • request.ts: Server-side locale resolution with fallback to en
  • navigation.ts: Locale-aware Link, redirect, usePathname, useRouter exports
• Middleware: src/proxy.ts uses next-intl/middleware for automatic locale detection from URL or Accept-Language header
• URL Structure: Default locale has no prefix (/pricing); others are prefixed (/fr/pricing)
• Fumadocs i18n: src/lib/i18n.ts configures the Fumadocs doc tree with the same locales
• Usage in components: const t = useExtracted() from next-intl, then t("key") or t("Welcome {name}", { name })
• Language Switcher: src/components/LanguageSwitcher.tsx — client component dropdown for all 10 locales
• Adding translations: Add keys to messages/en.json, then run npm run extract to sync all locale files
• Automated translation: .github/workflows/translate-docs.yml detects untranslated strings on push to master and opens a PR with AI-generated translations

Path Aliases Copy Section

• @/*: Maps to src/*
• @/.source: Maps to .source/index.ts (generated MDX content)

Code Conventions Copy Chapter

• Fumadocs for documentation infrastructure; MDX components defined in src/mdx-components.tsx
• Tailwind CSS v4 with dark mode support

Important Notes Copy Chapter

• Content files in content/docs/ and content/blog/ are processed by Fumadocs MDX
• The .source/ directory is auto-generated and should not be edited manually
• Next.js rewrites map /docs/:path*.mdx to /llms.mdx/:path* for LLM consumption
• Remote images allowed from: pbs.twimg.com, abs.twimg.com, ui-avatars.com, cdn.outrank.so, www.google.com

.Design Sync Docs ActivitySlider (`.design-sync/docs/ActivitySlider.md`) Copy Section

category: Replay Copy Chapter

The session-replay scrubber: a Radix slider whose track shows where the visitor was active and whose rail above it plots the meaningful events (clicks, navigations, typing, rage clicks, console errors) as colored 8px dots, so you can jump straight to the interesting moment. It is the "activity" view of the replay player; TimelineSlider is the plain thin transport rail used when there is no event data.

Single part: ActivitySlider. It extends every Radix Slider.Root prop (value/defaultValue as [ms], max, step, onValueChange, disabled) plus three of its own:

• duration (ms, the recording length; ALSO pass it as max so the thumb and the rail agree),
• activityPeriods ({ start, end }[] in ms; drawn as neutral-600 segments on the neutral-700 idle track),
• events (raw rrweb events { timestamp, type, data }; the slider runs them through getMeaningfulEvents from the replay module, so feed it what the player already has: type 4 Meta for session start/navigation, type 3 source 2 for clicks, source 5 for input, type 6 console plugin for logs).

Marker hues: navigation/console log blue-400, click/double click violet-500, right click fuchsia-500, rage click red-500, typing amber-500, resize cyan-500, console warning yellow-500, console error red-500. Each dot has a 2px ring in the panel color (ring-neutral-900 in dark) so overlapping dots stay distinct, and its title shows the label and offset on hover (not capturable statically). Over 160 markers the plain clicks/typing are sampled while every navigation, rage click and console event is kept. The played portion of the track is emerald (accent-500); the thumb is a 16px white disc with an emerald border.

Conventions: mount it inside the player card (neutral-900) with the session identity on the left and m:ss / m:ss on the right in 12px muted tabular figures; drive value from the player's current time.

import { ActivitySlider } from "@rybbit/ui";

<ActivitySlider
  duration={duration}
  max={duration}
  step={100}
  value={[currentTime]}
  onValueChange={([t]) => player.seek(t)}
  activityPeriods={[{ start: 0, end: 30_000 }, { start: 34_000, end: 78_000 }]}
  events={rrwebEvents}
/>

.Design Sync Docs Alert (`.design-sync/docs/Alert.md`) Copy Section

category: Feedback Copy Chapter

Inline, non-dismissing status message that lives in the page flow (a settings panel, the top of a report, an onboarding step). Use it for state the user needs to see when they arrive: tracking detected, a plan limit approaching, a failed verification. For a transient confirmation after an action use Toaster/toast; for something that must be acknowledged use AlertDialog.

Parts: Alert (root, role="alert", full width, 4.8px radius, 16px/12px padding, tinted fill) → a lucide icon as the first child (absolutely positioned top-left, 16px, tinted to the variant; the text shifts right 28px automatically) → AlertTitle (14px medium, one line) → AlertDescription (14px, wraps; nested `` get relaxed leading, so an action row can follow the text).

Variants (variant on Alert): default (neutral-800 fill, gray icon) · info (blue tint) · success (emerald tint) · warning (yellow tint) · destructive (red tint). There is no border; the hue is carried by the 12-15% tint and the icon only, so the alert sits flat on the panel like everything else in the instrument. Title in sentence case, description says the consequence or the next step; title-only and description-only are both fine for one-liners. Give the icon className="h-4 w-4".

import { Alert, AlertDescription, AlertTitle } from "@rybbit/ui";
import { AlertTriangle } from "lucide-react";

<Alert variant="warning">
  <AlertTriangle className="h-4 w-4" />
  <AlertTitle>Approaching your event limit</AlertTitle>
  <AlertDescription>You have used 91% of 1M monthly events. Upgrade to keep collecting after the cap.</AlertDescription>
</Alert>

.Design Sync Docs AlertDialog (`.design-sync/docs/AlertDialog.md`) Copy Section

category: Overlays Copy Chapter

Focus-trapped confirmation prompt (Radix AlertDialog). Unlike Dialog, it has no close X, cannot be dismissed by clicking the overlay, and always ends in a choice. Use it before an irreversible or costly action (delete a site, leave an organization, regenerate a key); use Dialog for forms and everything else.

Parts: AlertDialog (root, open/onOpenChange) → AlertDialogTrigger (asChild around a Button) → AlertDialogContent (centered 512px panel) → AlertDialogHeader / AlertDialogTitle / AlertDialogDescription → optional body → AlertDialogFooter with AlertDialogCancel (already styled as an outline Button, closes on click) and AlertDialogAction (accepts Button variant and size; closes on click, so attach the real work to onClick).

Conventions: title is a question naming the object ("Delete tomato.gg?"); description states the consequence and whether it can be undone; the cancel label is a verb ("Keep site"), not "No". The action is variant="destructive" for deletes and variant="accent" for non-destructive confirms. Never put more than two buttons in the footer.

<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="destructive">Delete site</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete tomato.gg?</AlertDialogTitle>
      <AlertDialogDescription>
        This removes the site and its 2.4M events. This cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Keep site</AlertDialogCancel>
      <AlertDialogAction variant="destructive" onClick={deleteSite}>Delete site</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

.Design Sync Docs Badge (`.design-sync/docs/Badge.md`) Copy Section

category: Data display Copy Chapter

Small inline status label: 12px medium text, 2px/6px padding, 2.8px radius (rounded-md), inline-flex. One export, Badge, with a variant prop; it renders a div, so it is not clickable — wrap it or use a Button size="xs" when it must act.

Variants:

• default — neutral-800 fill, neutral-100 text. Plan names, generic labels ("Pro").
• secondary — one notch quieter (panel fill, neutral-300 text). Counts and low-emphasis tags.
• success — emerald 20% tint, emerald-400 text. "Tracking", "Enabled", "Verified".
• warning — yellow tint. "No data", "Paused", thresholds.
• destructive — red tint. "Bot", "Blocked", "Failed".
• info — blue tint. "Beta", "New", informational only (never for data-series color).
• outline — neutral-700 border, transparent fill. Environment / category tags.
• ghost — no border or fill. Inline keywords.

Conventions: colored variants are semantic, so use them only when the state has that meaning — a status column is the canonical place. Put a 12px lucide icon (className="h-3 w-3") as the first child and add gap-1; add tabular-nums for counts and font-mono for paths. Badges do not change size; if you need a larger pill, it is a Button.

<Badge variant="success">Tracking</Badge>
<Badge variant="warning">No data</Badge>
<Badge variant="destructive" className="gap-1"><Bot className="h-3 w-3" /> Bot</Badge>
<Badge variant="secondary" className="tabular-nums">2,140</Badge>

.Design Sync Docs BasicTabs (`.design-sync/docs/BasicTabs.md`) Copy Section

category: Navigation Copy Chapter

Underline tabs (Radix), the quiet sibling of Tabs. There is no filled strip: triggers are muted text sitting on a transparent 32px row, and the active one turns bright with a 2px bottom border. Use it inside cards and section headers to switch a breakdown (Countries / Regions / Cities, Channels / Referrers) where a pill strip would be too heavy; use Tabs for top-level view switching.

Parts (exported with the BasicTabs prefix because the source file shares names with tabs.tsx): BasicTabs (root; defaultValue or value / onValueChange) → BasicTabsList (inline-flex row with 12px gaps) → BasicTabsTrigger (value, disabled) and BasicTabsContent (value; adds mt-2).

Conventions: short one-word labels; an optional count after the label as 48; keep the list flush-left with the card's content edge. Never mix BasicTabs and Tabs parts in one tree.

<BasicTabs defaultValue="countries">
  <BasicTabsList>
    <BasicTabsTrigger value="countries">Countries</BasicTabsTrigger>
    <BasicTabsTrigger value="regions">Regions</BasicTabsTrigger>
    <BasicTabsTrigger value="cities">Cities</BasicTabsTrigger>
  </BasicTabsList>
  <BasicTabsContent value="countries">{/* ranked list */}</BasicTabsContent>
  <BasicTabsContent value="regions">…</BasicTabsContent>
  <BasicTabsContent value="cities">…</BasicTabsContent>
</BasicTabs>

.Design Sync Docs Breadcrumb (`.design-sync/docs/Breadcrumb.md`) Copy Section

category: Navigation Copy Chapter

Location trail for deep pages (a user profile, a funnel, an org settings sub-page). Ancestors are muted links, the current page is bright plain text, and a small chevron separates them. Use it only when the page is two or more levels below a sidebar destination; top-level report pages do not need one.

Parts: Breadcrumb (<nav aria-label="breadcrumb">) → BreadcrumbList (<ol>, 14px muted text, wraps) → BreadcrumbItem (<li>) containing either BreadcrumbLink (href, or asChild to wrap a router Link) or BreadcrumbPage (current page, aria-current="page"). Put a BreadcrumbSeparator between items: with no children it renders a 14px ChevronRight; pass any node (e.g. <Slash />) to replace it. BreadcrumbEllipsis is a 36px "…" placeholder for collapsed middle levels; wrap it in its own BreadcrumbItem.

Conventions: the site domain (tomato.gg) is the first crumb inside a site; keep at most four visible crumbs and collapse the rest with the ellipsis; the last item is always a BreadcrumbPage, never a link. Hover brightening on links is a live state and is not shown statically.

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/tomato.gg">tomato.gg</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink href="/tomato.gg/users">Users</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>usr_8f3a91c2</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

.Design Sync Docs Button (`.design-sync/docs/Button.md`) Copy Section

category: Actions Copy Chapter

The primary control. Nine visual variants on one shared shape (36px tall, 4.8px radius, 14px medium text, 4px icon gap).

• accent — the ONE emerald primary action on a surface ("Add site", "Save", "Publish"). At most one per view.
• default — the raised gray chrome button (neutral-850 fill, neutral-750 border in dark). The everyday secondary action.
• secondary — one notch quieter than default (panel-colored fill).
• outline — bordered, transparent; toolbar and filter chrome.
• ghost — no border or fill until hover; icon buttons, "Cancel", inline actions.
• link — text only with underline on hover; navigation-like actions.
• success / warning / destructive — state-colored actions (emerald, yellow, red). Use for confirmations, never as decoration.

Sizes: lg (40px) · default (36px) · sm (32px) · xs (24px) · icon (36px square) · smIcon (28px square). Put a lucide icon as the first child; the button sizes it to 16px automatically.

asChild renders the styles onto the child element (e.g. an <a>), keeping one DOM node.

<Button variant="accent"><Plus /> New goal</Button>
<Button variant="outline" size="sm">Export CSV</Button>
<Button size="icon" variant="ghost" aria-label="Settings"><Settings /></Button>

.Design Sync Docs ButtonGroup (`.design-sync/docs/ButtonGroup.md`) Copy Section

category: Actions Copy Chapter

Joins adjacent Buttons (and inputs/select triggers) into one control: inner corners are squared and the shared border is collapsed so a Day/Week/Month switch, a zoom toolbar or a split "range + chevron" trigger reads as a single piece of chrome. Use it whenever two or more related actions sit flush; use plain flex gap-2 for unrelated buttons.

Parts: ButtonGroup (root, role="group", flex w-fit items-stretch; orientation="horizontal" (default) removes left borders/radii between children, "vertical" stacks them and removes the top ones) → children are ordinary Buttons. ButtonGroupSeparator is a hairline Separator (neutral-800, stretches to the group height) for splitting clusters inside one group. ButtonGroupText is a static label cell with the same height and border (neutral-800 fill; asChild to render it as a label or link); put a lucide icon first and it is sized to 16px. Nesting a ButtonGroup directly inside a ButtonGroup inserts an 8px gap between the clusters, which is how you build a filter bar.

Conventions: members share one size (sm for filter chips, icon for tool rails). Use variant="outline" for the members and variant="default" (the raised neutral-850 chrome) for the selected one; accent only for the single primary action at the end of a group. buttonGroupVariants is exported if you need the classes on a custom element.

import { Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@rybbit/ui";
import { Calendar, ChevronDown, Download } from "lucide-react";

<ButtonGroup>
  <Button variant="outline" size="sm">Day</Button>
  <Button variant="default" size="sm">Week</Button>
  <Button variant="outline" size="sm">Month</Button>
</ButtonGroup>

<ButtonGroup>
  <ButtonGroupText><Calendar /> Last 30 days</ButtonGroupText>
  <Button variant="outline" aria-label="Change range"><ChevronDown /></Button>
  <ButtonGroupSeparator />
  <Button variant="outline"><Download /> Export</Button>
</ButtonGroup>

.Design Sync Docs Calendar (`.design-sync/docs/Calendar.md`) Copy Section

category: Forms Copy Chapter

Month-grid date picker (react-day-picker v9) that lives inside the date-range popover and any "pick a day" dialog. One component plus its day cell: Calendar (all DayPicker props pass through) and CalendarDayButton (the ghost/icon Button used per day, swappable via components). Key props: mode="single" with selected: Date / onSelect(date), or mode="range" with selected: { from, to } / onSelect(range); defaultMonth (always set it so the render is deterministic); disabled (a matcher such as { after: new Date() } to block future days); captionLayout="label" (default, static "May 2024") or "dropdown" (month + year selects, needs startMonth/endMonth); numberOfMonths={2} for a side-by-side range picker; showOutsideDays (default true).

Appearance: a w-fit neutral-850 panel with 12px padding and 32px cells (--cell-size), muted weekday letters, the selected day as a light (neutral-200) pill with dark text, today as a neutral-700 pill, range middles as a continuous neutral-700 band with square inner corners, disabled days at 50% opacity. Inside a PopoverContent or CardContent the panel background goes transparent to sit on the host. Keep it for picking days; pair it with the preset range list (Last 7/30/90 days) rather than replacing it, and use Input type="time" for times.

const [range, setRange] = React.useState<{ from?: Date; to?: Date }>();

<Calendar
  mode="range"
  selected={range}
  onSelect={setRange}
  defaultMonth={new Date(2024, 4, 1)}
  disabled={{ after: new Date() }}
  numberOfMonths={2}
/>

.Design Sync Docs Card (`.design-sync/docs/Card.md`) Copy Section

category: Data display Copy Chapter

The panel. Every dashboard section, stat tile, and settings block sits in a Card: a neutral-900 surface one step off the canvas, 1px neutral-850 border, 4.8px radius, overflow-hidden, no shadow. Flat parts, all optional:

• Card — the surface (relative, so loaders and absolute children anchor to it).
• CardHeader — vertical stack with 16px padding; holds CardTitle (16px semibold, tight tracking) and CardDescription (14px, neutral-400 muted).
• CardContent — 16px padding with the top padding removed (p-4 pt-0) so it butts against the header. Put your rows, table, or chart here.
• CardFooter — horizontal flex row, same padding rule; put Buttons here (justify-end gap-2 for an action row, ONE accent).
• CardLoader — an indeterminate progress bar for "refetching in place". It is absolute top-0 left-0 w-full with a -15px top margin, so render it as the first child of a Card (or inside any relative container) and the card's overflow-hidden clips it to a thin line along the top edge. It needs no props; it reads the theme via next-themes and colors itself neutral-400 in dark mode. Use it with Skeleton content underneath on first load, or alone over stale data while refetching.

Conventions: stat tiles do not use CardHeader — they are a Card with px-3 py-2, a 12px text-muted-foreground label, and a 24px font-medium figure (delta in text-emerald-400 / text-red-400). Lists inside CardContent use border-b border-neutral-800 hairlines between rows, not nested cards. Never nest a Card in a Card.

<Card>
  <CardLoader />
  <CardHeader>
    <CardTitle>Top pages</CardTitle>
    <CardDescription>Last 7 days on tomato.gg</CardDescription>
  </CardHeader>
  <CardContent className="flex flex-col gap-2">
    <Skeleton className="h-4 w-full" />
    <Skeleton className="h-4 w-full" />
  </CardContent>
  <CardFooter className="justify-end gap-2">
    <Button variant="ghost" size="sm">Cancel</Button>
    <Button variant="accent" size="sm">Save changes</Button>
  </CardFooter>
</Card>

.Design Sync Docs Carousel (`.design-sync/docs/Carousel.md`) Copy Section

category: Data display Copy Chapter

Horizontal (or vertical) slide deck driven by Embla, for a row of stat cards, onboarding steps or screenshots that would not fit side by side. In an analytics UI reach for it rarely: a grid or a scrollable row is usually clearer; use a carousel when the slides are peers and only a few need to be visible at once.

Parts: Carousel (root, role="region"; props orientation="horizontal" | "vertical", opts passed straight to Embla, e.g. { loop: true, startIndex: 1, align: "start" }, plugins, setApi to receive the CarouselApi for programmatic scrolling; arrow keys work out of the box) → CarouselContent (the overflow-hidden viewport; its inner flex track has a -16px start margin so items are spaced by their own 16px padding) → CarouselItem (one slide, basis-full by default; set style={{ flexBasis: "33.3333%" }} or a basis-* class for N-up) → CarouselPrevious / CarouselNext (32px round outline icon buttons, absolutely positioned 48px OUTSIDE the track: -left-12 / -right-12, or above/below and rotated when vertical; they disable themselves at the ends unless loop is on). Both buttons accept every Button prop, so pass variant/className to reposition them inside the track if the parent has no gutter.

Conventions: reserve a 64px side gutter in the parent for the arrows; give a vertical CarouselContent an explicit height; slides are Cards with the stat-tile layout (12px muted label, 24px semibold tabular number, emerald/red delta line). Keep the visible slide count at 1-3.

import { Card, CardContent, Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from "@rybbit/ui";

<div style={{ padding: "16px 64px" }}>
  <Carousel opts={{ align: "start" }}>
    <CarouselContent>
      {stats.map((s) => (
        <CarouselItem key={s.label} style={{ flexBasis: "33.3333%" }}>
          <Card>
            <CardContent className="p-4">
              <div className="text-xs font-medium text-neutral-400">{s.label}</div>
              <div className="mt-1 text-2xl font-semibold tabular-nums">{s.value}</div>
              <div className="mt-1 text-xs text-emerald-400">{s.delta} vs. previous 30 days</div>
            </CardContent>
          </Card>
        </CarouselItem>
      ))}
    </CarouselContent>
    <CarouselPrevious />
    <CarouselNext />
  </Carousel>
</div>

.Design Sync Docs Checkbox (`.design-sync/docs/Checkbox.md`) Copy Section

category: Forms Copy Chapter

Radix checkbox, 16px square, 4.8px radius. Unchecked: 1px neutral-700 border on a faint neutral-900/30 fill. Checked: emerald (accent-500) border and fill with a white lucide Check. Focus shows a 3px emerald ring. Use it for independent on/off choices in a list (columns to include, sites to notify, filters to apply); use Switch for a single setting that applies immediately, and RadioGroup for mutually exclusive options.

Parts: Checkbox only (indicator is internal). Props: checked / defaultChecked, onCheckedChange, disabled, id, name, className.

Conventions:

• Always give it an id and a sibling Label htmlFor in a flex items-center gap-2 row; the label toggles it.
• With a description: flex items-start gap-3, add className="mt-0.5" to the checkbox so it aligns with the first text line, and put the description in text-xs text-neutral-400.
• Option lists live in a grid gap-2.5 inside a rounded-lg border border-neutral-800 bg-neutral-900 p-4 panel with a text-sm font-medium heading; option labels use font-normal.
• disabled fades the box to 50%; add opacity-70 to its label. Hover and indeterminate are not shown in the previews.

<div className="flex items-center gap-2">
  <Checkbox id="exclude-bots" defaultChecked />
  <Label htmlFor="exclude-bots">Exclude known bots</Label>
</div>

<div className="flex items-start gap-3">
  <Checkbox id="salt" className="mt-0.5" />
  <div className="grid gap-1">
    <Label htmlFor="salt">Salt user IDs daily</Label>
    <p className="text-xs text-neutral-400">Returning-visitor stats reset at midnight UTC.</p>
  </div>
</div>

.Design Sync Docs Command (`.design-sync/docs/Command.md`) Copy Section

category: Overlays Copy Chapter

Searchable command list built on cmdk. Typing in CommandInput filters CommandItems by their text (or value / keywords), arrow keys move the highlight, Enter fires onSelect. Use it for the ⌘K palette, site switchers, and any pick-from-many list that needs a search box; for a plain menu of actions use DropdownMenu, and for a form value use Select.

Parts: Command (root; transparent background, so wrap it in your own panel such as rounded-lg border border-neutral-800 bg-neutral-900, or use CommandDialog) → CommandInput (search icon + input, hairline bottom border; placeholder, value / onValueChange) → CommandList (scroll container capped at 300px) containing CommandEmpty (shown only when nothing matches), CommandGroup (heading renders a small muted label), CommandItem (value, keywords, onSelect, disabled; highlighted row is a raised neutral), CommandShortcut (right-aligned key hint) and CommandSeparator. CommandDialog wraps the same children in a Dialog (open / onOpenChange, title / description for screen readers, showCloseButton) with taller 48px rows.

Conventions: put a 16px lucide icon with mr-2 size-4 text-neutral-400 before item text; group by kind (Sites / Go to / Actions) with a separator between groups; keep the first item selected by default (cmdk does this). Keyboard navigation and the filtered state are live behaviors and are not shown statically.

<CommandDialog open={open} onOpenChange={setOpen} title="Command palette">
  <CommandInput placeholder="Search sites, pages, or commands…" />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Sites">
      <CommandItem onSelect={() => go("/tomato.gg")}>
        <Globe className="mr-2 size-4 text-neutral-400" /> tomato.gg
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Go to">
      <CommandItem>
        <Users className="mr-2 size-4 text-neutral-400" /> Sessions
        <CommandShortcut>⌘2</CommandShortcut>
      </CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>

.Design Sync Docs Dialog (`.design-sync/docs/Dialog.md`) Copy Section

category: Overlays Copy Chapter

Modal dialog (Radix). Compose the flat parts: Dialog (root, controls open) → DialogTrigger (wraps the opener, asChild for a Button) → DialogContent (portalled panel, 512px max, close X built in; hideClose removes it) → DialogHeader / DialogTitle / DialogDescription → body → DialogFooter (actions, right-aligned on desktop). DialogClose wraps any element that should dismiss. DialogContentFullScreen is the edge-to-edge editor surface with no overlay or padding.

Rules of thumb: title in sentence case; description explains the consequence; footer holds a ghost/outline cancel and ONE accent (or destructive) confirm. For screen-size-adaptive dialogs use ResponsiveDialog (dialog on desktop, drawer on mobile). For a plain confirm/cancel prompt with focus trapping use AlertDialog.

<Dialog>
  <DialogTrigger asChild><Button variant="accent">Add site</Button></DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Add a website</DialogTitle>
      <DialogDescription>Enter the domain you want to track.</DialogDescription>
    </DialogHeader>
    <Input placeholder="example.com" />
    <DialogFooter>
      <DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
      <Button variant="accent">Add site</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

.Design Sync Docs Drawer (`.design-sync/docs/Drawer.md`) Copy Section

category: Overlays Copy Chapter

Touch-first panel built on vaul: slides up from the bottom with a drag handle and swipe-to-dismiss. Use it on mobile layouts for short forms and detail cards (a goal editor, a session summary, a filter list). On desktop prefer Dialog or Sheet; ResponsiveDialog switches between the two for you.

Parts: Drawer (root, open/onOpenChange; direction="bottom" | "top" | "left" | "right", default bottom) → DrawerTrigger (asChild around a Button) → DrawerContent (portalled panel with overlay; the drag handle is rendered automatically for bottom) → DrawerHeader / DrawerTitle / DrawerDescription → your content → DrawerFooter (stacked, full-width actions pushed to the bottom with mt-auto). DrawerClose wraps any element that should dismiss.

Conventions: header and footer carry their own p-4, so pad body content with px-4 to line up. Footer buttons stack vertically at full width — put the accent action first and a ghost cancel below it. Bottom drawers center their header text; side drawers (left/right) behave like a Sheet and are capped at max-w-sm. Keep bottom drawers under ~60% of the viewport; anything taller belongs in a page.

<Drawer>
  <DrawerTrigger asChild><Button variant="accent">New goal</Button></DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>New goal</DrawerTitle>
      <DrawerDescription>Count a conversion whenever a visitor reaches this page.</DrawerDescription>
    </DrawerHeader>
    <div className="grid gap-3 px-4">
      <Label htmlFor="path">Path</Label>
      <Input id="path" defaultValue="/welcome" />
    </div>
    <DrawerFooter>
      <Button variant="accent">Create goal</Button>
      <DrawerClose asChild><Button variant="ghost">Cancel</Button></DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>

.Design Sync Docs DropdownMenu (`.design-sync/docs/DropdownMenu.md`) Copy Section

category: Overlays Copy Chapter

Contextual action menu (Radix) that opens from a trigger and closes on select or outside click. Use it for per-row/per-site actions, column toggles, and quick single-choice settings; use Select when the value is a form field, and Popover when the content is not a list of commands.

Parts: DropdownMenu (root, open / onOpenChange) → DropdownMenuTrigger (renders as a Button and accepts Button variant / size; pass asChild to supply your own element, or unstyled to opt out of button styling) → DropdownMenuContent (portalled panel, align="start" | "end", sideOffset 4 by default; give it a width like className="w-56"). Inside: DropdownMenuLabel (section heading), DropdownMenuGroup, DropdownMenuItem (a leading lucide icon is auto-sized to 16px; inset indents to align with checkbox rows; disabled dims it), DropdownMenuShortcut (right-aligned key hint), DropdownMenuSeparator, DropdownMenuCheckboxItem (checked / onCheckedChange, emerald check indicator), DropdownMenuRadioGroup + DropdownMenuRadioItem (value, emerald dot), and DropdownMenuSub + DropdownMenuSubTrigger (chevron built in) + DropdownMenuSubContent for a nested level. DropdownMenuPortal is only needed when you portal sub-content yourself.

Conventions: one label per section, separators between sections, the destructive action last and colored with text-red-400. Keep menus to ~8 rows; put value pickers with many options in Select. Hover/focus highlight is a raised neutral, never emerald: emerald appears only on the check/radio indicator.

<DropdownMenu>
  <DropdownMenuTrigger variant="outline" size="sm">
    tomato.gg <ChevronDown className="size-4" />
  </DropdownMenuTrigger>
  <DropdownMenuContent align="start" className="w-56">
    <DropdownMenuLabel>tomato.gg</DropdownMenuLabel>
    <DropdownMenuSeparator />
    <DropdownMenuItem>
      <Settings /> Site settings
      <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuCheckboxItem checked>Show bounce rate</DropdownMenuCheckboxItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem className="text-red-400 focus:text-red-400">
      <Trash2 /> Delete site
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

.Design Sync Docs Form (`.design-sync/docs/Form.md`) Copy Section

category: Forms Copy Chapter

The react-hook-form wiring layer for every settings and create dialog. Form is react-hook-form's FormProvider: spread the object from useForm() into it, then put a real <form onSubmit={form.handleSubmit(fn)}> inside. Each field is FormField (control={form.control}, name, and a render={({ field }) => ...} that spreads field onto the input) → FormItem (a space-y-2 stack that owns the ids) → FormLabel (turns red on error) → FormControl (a Slot that stamps id, aria-describedby, aria-invalid on the single child control) → FormDescription (muted 12.8px helper) → FormMessage (red 12.8px; renders the field's error message automatically, or its children, or nothing). useFormField() exposes the ids and error inside custom controls.

Conventions: one FormItem per field, grid gap-5 (or space-y-4) between them, actions in a right-aligned flex justify-end gap-2 row with a ghost cancel and ONE accent submit. Bind non-input controls via their own props: a Select takes value={field.value} onValueChange={field.onChange} with FormControl wrapping the SelectTrigger; a Switch/Checkbox takes checked={field.value} onCheckedChange={field.onChange}. Show errors from validation, or set them with form.setError("domain", { message }). Use plain Label + Input only for a single uncontrolled field outside a form.

const form = useForm({ defaultValues: { domain: "" } });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)} className="grid gap-5">
    <FormField
      control={form.control}
      name="domain"
      rules={{ required: "Domain is required." }}
      render={({ field }) => (
        <FormItem>
          <FormLabel>Domain</FormLabel>
          <FormControl><Input placeholder="example.com" {...field} /></FormControl>
          <FormDescription>The hostname the tracking script will report from.</FormDescription>
          <FormMessage />
        </FormItem>
      )}
    />
    <div className="flex justify-end gap-2">
      <Button type="button" variant="ghost">Cancel</Button>
      <Button type="submit" variant="accent">Add site</Button>
    </div>
  </form>
</Form>

.Design Sync Docs Input (`.design-sync/docs/Input.md`) Copy Section

category: Forms Copy Chapter

Single-line text field. Transparent fill, 1px neutral-800 border, 4.8px radius, placeholder in neutral-400, and a 1px neutral-300 ring on focus. Use it for every free-text, number, URL and password field in settings and dialogs; pair it with Label above via htmlFor.

Parts: Input only. It forwards every native `` prop (type, placeholder, defaultValue, disabled, aria-invalid, ref).

Conventions:

• inputSize="default" (36px, 14px text) for forms; inputSize="sm" (28px, 12px text) for toolbar filters and table headers.
• isSearch renders a leading lucide Search icon and pads the text past it. Use it for every "Search / Filter …" box.
• aria-invalid="true" turns the border red; put the error text in a text-xs text-red-400 line below.
• disabled drops the field to 50% opacity. Width comes from the container: it is w-full, so constrain with className="w-32" or a grid.
• Stack Label + Input in a grid gap-1.5; use grid grid-cols-2 gap-3 for side-by-side fields. Prefer Textarea for multi-line, Select for enumerations.

<div className="grid gap-1.5">
  <Label htmlFor="domain">Domain</Label>
  <Input id="domain" placeholder="example.com" defaultValue="tomato.gg" />
</div>

<Input isSearch inputSize="sm" placeholder="Search pages…" />

<div className="grid gap-1.5">
  <Input aria-invalid="true" defaultValue="not a domain" />
  <p className="text-xs text-red-400">Enter a valid domain, like tomato.gg</p>
</div>

.Design Sync Docs InputWithSuggestions (`.design-sync/docs/InputWithSuggestions.md`) Copy Section

category: Forms Copy Chapter

A text Input that shows a filterable list of known values underneath while typing: page paths, event names, referrers, UTM values. Free text is always allowed; the suggestions are hints, not constraints. One component, no sub-parts: InputWithSuggestions. Props: suggestions: { value, label?, count? }[] (count renders right-aligned in compact form, e.g. 6.1K), value + onValueChange(text) for controlled use (uncontrolled works too), plus every Input prop (placeholder, disabled, onChange, className). Forwards its ref to the input element.

Conventions: the list opens on focus and on every keystroke, filters by case-insensitive substring of the current value, closes on outside click or when a row is picked, and is portalled (into the nearest role="dialog" or body) so it escapes overflow clipping. Sort suggestions by count descending so the most common value is first. Prefer it over Select when the value space is open-ended (any path could be typed) and over MultiSelect when only one value is being entered.

const pages = [
  { value: "/pricing", count: 6120 },
  { value: "/docs/script", count: 4890 },
  { value: "/signup", count: 1975 },
];
const [path, setPath] = React.useState("");

<InputWithSuggestions
  value={path}
  onValueChange={setPath}
  suggestions={pages}
  placeholder="/checkout"
/>

.Design Sync Docs Label (`.design-sync/docs/Label.md`) Copy Section

category: Forms Copy Chapter

Form label built on Radix Label: 14px, medium weight, leading-none, inherits the foreground color. Always wire it to its control with htmlFor + id so clicking the text focuses the input or toggles the checkbox/switch. It is the only text style for field names; helper text below a field is a plain p.text-xs.text-neutral-400.

Parts: Label only. Forwards every native <label> prop and className.

Conventions:

• Above a field: grid gap-1.5 with Label first, then Input / Textarea / Select.
• Beside a toggle: flex items-center gap-2 with the Checkbox / RadioGroupItem / Switch first, then the Label. For lists of options use className="font-normal" so only the group heading is medium.
• When the control has peer and is disabled, the label auto-fades to 70% (peer-disabled:opacity-70); otherwise add className="opacity-70" yourself.
• Required marker: * inside the label. A trailing hint sits on the same row with flex items-baseline justify-between.

<div className="grid gap-1.5">
  <Label htmlFor="site-name">Site name</Label>
  <Input id="site-name" defaultValue="rybbit.com" />
  <p className="text-xs text-neutral-400">Shown in the site switcher.</p>
</div>

<div className="flex items-center gap-2">
  <Checkbox id="exclude-bots" defaultChecked />
  <Label htmlFor="exclude-bots">Exclude known bots</Label>
</div>

.Design Sync Docs MultiSelect (`.design-sync/docs/MultiSelect.md`) Copy Section

category: Forms Copy Chapter

Searchable multi-value picker for filters (countries, browsers, pages, sites): an outline combobox button that grows to hold the chosen values as secondary badges with an X to remove, and a Popover + Command list with a search box and check marks. One component, no sub-parts: MultiSelect. Props: options: { value, label, disabled? }[], value: string[] + onValueChange(values) (controlled; keep the array in state), placeholder (empty-state text, default "Select items..."), searchPlaceholder, emptyText ("No items found."), disabled, className (trigger), badgeClassName (chips).

Conventions: the trigger is w-full and at least 36px tall; chips wrap onto extra rows rather than truncating, so give it a bounded width (form column or w-96). The list opens on click only (no open prop) and filters by label substring; selecting toggles membership and keeps the list open. Use it when more than one value can be active at once; for a single choice use Select; for free text use InputWithSuggestions.

const countries = [
  { value: "US", label: "United States" },
  { value: "DE", label: "Germany" },
  { value: "GB", label: "United Kingdom" },
];
const [selected, setSelected] = React.useState<string[]>(["US"]);

<MultiSelect
  options={countries}
  value={selected}
  onValueChange={setSelected}
  placeholder="Filter by country"
  searchPlaceholder="Search countries"
  emptyText="No country matches."
/>

.Design Sync Docs NavigationMenu (`.design-sync/docs/NavigationMenu.md`) Copy Section

category: Navigation Copy Chapter

Horizontal top-level nav bar (Radix) whose triggers open a content panel that drops from below the bar. It is for marketing/site-wide headers with a few sections, not for the dashboard sidebar (which is a plain list) and not for per-item actions (DropdownMenu). Plain links live in the same bar via NavigationMenuLink styled with navigationMenuTriggerStyle().

Parts: NavigationMenu (root; renders the NavigationMenuViewport for you. Uncontrolled by default; pass value / onValueChange to force an item open) → NavigationMenuList (flex row) → NavigationMenuItem (give it value when controlling) containing either NavigationMenuTrigger (36px button, chevron built in and flips when open) + NavigationMenuContent (the panel body; size it yourself, e.g. w-[400px] p-2), or a bare NavigationMenuLink (href, asChild). NavigationMenuIndicator is an optional caret under the active trigger. The panel is a bg-neutral-950 surface with a hairline border-neutral-800.

Conventions: 2-4 triggers plus 1-2 plain links; inside a panel list links as block rounded-md p-3 hover:bg-neutral-800 blocks with a 14px medium title and a 12px text-neutral-400 description. Give the container enough height below the bar for the panel. Hover-to-open and the slide animation are live behaviors; the preview forces the panel open with value.

<NavigationMenu>
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Reports</NavigationMenuTrigger>
      <NavigationMenuContent>
        <div className="grid w-[400px] gap-1 p-2">
          <NavigationMenuLink asChild>
            <a href="/overview" className="block rounded-md p-3 hover:bg-neutral-800">
              <div className="text-sm font-medium">Overview</div>
              <p className="mt-1 text-xs text-neutral-400">Visitors, pageviews and top pages.</p>
            </a>
          </NavigationMenuLink>
        </div>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/docs" className={navigationMenuTriggerStyle()}>Docs</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>

.Design Sync Docs Popover (`.design-sync/docs/Popover.md`) Copy Section

category: Overlays Copy Chapter

Non-modal floating panel anchored to a trigger (Radix Popover). Use it for small, focused controls that belong next to the thing they change: date-range presets, a filter's value picker, the site selector, a one-paragraph explanation. Use DropdownMenu for a list of commands, Tooltip for a label that needs no interaction, and Dialog for anything that needs a title and footer.

Parts: Popover (root, open/onOpenChange) → PopoverTrigger (asChild around a Button) → PopoverContent (portalled panel: w-72 p-4 rounded-md, raised neutral surface; props align="start" | "center" | "end" (default center), side, sideOffset (default 4), onOpenAutoFocus). PopoverAnchor positions the panel against an element other than the trigger.

Conventions: prefer align="start" so the panel lines up with the trigger's left edge. Override width per use (w-64, w-80, or w-[var(--radix-popover-trigger-width)] to match the trigger); pass p-0 when the content is a Command list or a Calendar. Inside, use text-sm, muted labels in text-xs text-neutral-400, and a right-aligned size="sm" action row. Inputs inside inherit a slightly lighter border automatically.

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" size="sm"><CalendarIcon /> Last 7 days</Button>
  </PopoverTrigger>
  <PopoverContent align="start" className="w-64">
    <div className="grid gap-1">
      {["Today", "Last 7 days", "Last 30 days"].map(p => (
        <button key={p} className="rounded-md px-2 py-1.5 text-left text-sm hover:bg-neutral-700/60">{p}</button>
      ))}
    </div>
    <Separator className="my-3 dark:bg-neutral-700" />
    <div className="grid grid-cols-2 gap-2">
      <Input defaultValue="2026-09-06" className="h-8 text-xs" />
      <Input defaultValue="2026-09-13" className="h-8 text-xs" />
    </div>
  </PopoverContent>
</Popover>

.Design Sync Docs Progress (`.design-sync/docs/Progress.md`) Copy Section

category: Data display Copy Chapter

Determinate progress / usage meter (Radix Progress). One export, Progress: an 8px-tall, fully rounded neutral-800 track with an emerald (accent-500) indicator that slides in by value percent. Props: value (0-100, undefined renders empty), max (Radix, default 100), className on the track. There is no indeterminate mode — for "loading" use CardLoader or Skeleton.

Conventions: the bar carries no text, so always pair it with a label and a figure. The canonical usage meter is a flex justify-between text-sm row (name left, 812K / 1M in tabular-nums text-neutral-400 right), the bar, then a 12px muted note. For inline rows (countries, browsers) shrink the track with h-1.5 and give the bar flex-1 between a fixed-width name and a right-aligned percentage. Emerald here means "amount used / achieved", not success; do not recolor the indicator per row (chart series use periwinkle in Nivo, not this component). Use Slider when the user should change the value.

<div className="flex flex-col gap-2">
  <div className="flex items-center justify-between text-sm">
    <span className="font-medium">Events this month</span>
    <span className="tabular-nums text-neutral-400">812K / 1M</span>
  </div>
  <Progress value={81} />
  <div className="text-xs text-muted-foreground">Resets in 9 days · Pro plan</div>
</div>

.Design Sync Docs RadioGroup (`.design-sync/docs/RadioGroup.md`) Copy Section

category: Forms Copy Chapter

Radix radio group for one-of-N choices that need every option visible (retention period, chart interval, visitor scope). Items are 16px circles: 1px neutral-700 border when idle, emerald (accent-500) fill with a white dot when selected, 3px emerald focus ring. Use Select instead when there are more than ~5 options or space is tight; use Checkbox when choices are independent.

Parts:

• RadioGroup — the root (grid gap-2 by default). Props: value / defaultValue, onValueChange, disabled, name, className.
• RadioGroupItem — one option. Props: value (required), id, disabled, className. Indicator is internal.

Conventions:

• Each item sits in a flex items-center gap-2 row with a Label htmlFor matching its id; option labels use className="font-normal", the group heading is text-sm font-medium above.
• Horizontal: <RadioGroup className="flex gap-4"> for short enums like hour / day / week.
• With descriptions: flex items-start gap-3, className="mt-0.5" on the item, description in text-xs text-neutral-400.
• disabled on an item fades it to 50%; add opacity-70 to that label.

<RadioGroup defaultValue="365">
  <div className="flex items-center gap-2">
    <RadioGroupItem value="90" id="r-90" />
    <Label htmlFor="r-90" className="font-normal">90 days</Label>
  </div>
  <div className="flex items-center gap-2">
    <RadioGroupItem value="365" id="r-365" />
    <Label htmlFor="r-365" className="font-normal">1 year</Label>
  </div>
</RadioGroup>

.Design Sync Docs ResponsiveDialog (`.design-sync/docs/ResponsiveDialog.md`) Copy Section

category: Overlays Copy Chapter

One overlay, two presentations: at viewports ≥640px it renders a centered Radix Dialog; below that it renders a vaul Drawer (bottom sheet with drag handle). Use it for any dialog that also has to work on phones — invite a member, edit a goal, expand a dashboard card. If you only ever need one presentation, use Dialog, Sheet or Drawer directly.

Parts: ResponsiveDialog (root; open/onOpenChange, plus direction for the drawer side, onlyDialog / onlyDrawer to pin a presentation, dismissible={false} to block overlay/Escape, alert to make it an un-dismissable confirm with no X) → ResponsiveDialogTrigger → ResponsiveDialogContent (showCloseButton, closeButtonClassName, dragHandleClassName) → ResponsiveDialogHeader / ResponsiveDialogTitle / ResponsiveDialogDescription → body → ResponsiveDialogFooter (row on desktop, reversed column on mobile). ResponsiveDialogClose wraps a dismissing element. useResponsiveDialog() (call inside the root) returns { modal, dismissible, direction, onlyDrawer, onlyDialog, alert } for custom parts.

Conventions: ResponsiveDialogContent sets no width or padding, so always pass them — className="max-w-md p-6" for a form, max-w-[1000px] w-[calc(100vw-2rem)] p-4 for a wide card expansion. In drawer mode add px-4 pb-4 instead. Same footer rule as Dialog: one accent/destructive confirm, one ghost/outline cancel.

<ResponsiveDialog>
  <ResponsiveDialogTrigger asChild><Button variant="accent">Invite</Button></ResponsiveDialogTrigger>
  <ResponsiveDialogContent className="max-w-md p-6">
    <ResponsiveDialogHeader>
      <ResponsiveDialogTitle>Invite a teammate</ResponsiveDialogTitle>
      <ResponsiveDialogDescription>They get access to every site in Tomato Labs.</ResponsiveDialogDescription>
    </ResponsiveDialogHeader>
    <Input placeholder="[email protected]" />
    <ResponsiveDialogFooter>
      <ResponsiveDialogClose asChild><Button variant="ghost">Cancel</Button></ResponsiveDialogClose>
      <Button variant="accent">Send invite</Button>
    </ResponsiveDialogFooter>
  </ResponsiveDialogContent>
</ResponsiveDialog>

.Design Sync Docs ScrollArea (`.design-sync/docs/ScrollArea.md`) Copy Section

category: Data display Copy Chapter

Custom-scrollbar container for any fixed-height list or wide row (Radix ScrollArea, with a touch-device fallback to native scrolling). Parts: ScrollArea (root + viewport; already includes a vertical ScrollBar, a corner, and an edge-fade mask) and ScrollBar (add one with orientation="horizontal" as a child when the content is wider than the panel).

ScrollArea props beyond Radix's: viewportClassName (classes on the scrolling viewport, e.g. pr-3), maskHeight (px, default 30; 0 disables the fade), maskClassName. Radix props pass through — type="always" keeps the bar visible, the default (hover, scrollHideDelay={0}) reveals it only while the pointer is over the area. The mask is a panel-colored (neutral-900) gradient that appears only on edges with more content, so it tells the user "there is more" without a visible scrollbar.

Conventions: the root needs a height (h-64, h-[314px], or h-full min-h-0 inside a flex column) or nothing scrolls; put padding on the inner content, not the root, so the mask and bar sit at the true edge. Use it for dashboard lists (countries, pages, bot rows), dialog bodies, and chip rows; use plain Table for short lists that fit. Rows inside are ordinary flex justify-between lines with tabular-nums figures. The mask assumes the panel is neutral-900; on the raw canvas set maskClassName or maskHeight={0}.

<ScrollArea className="h-64 rounded-lg border border-neutral-800 bg-neutral-900">
  <div className="flex flex-col p-2 text-sm">
    {countries.map(([name, n]) => (
      <div key={name} className="flex items-center justify-between px-2 py-1.5">
        <span>{name}</span>
        <span className="tabular-nums text-neutral-400">{n.toLocaleString()}</span>
      </div>
    ))}
  </div>
</ScrollArea>

<ScrollArea className="rounded-lg border border-neutral-800">
  <div className="flex w-max gap-2 p-3">{chips}</div>
  <ScrollBar orientation="horizontal" />
</ScrollArea>

.Design Sync Docs Select (`.design-sync/docs/Select.md`) Copy Section

category: Forms Copy Chapter

Single-value dropdown (Radix Select) for picking one option from a short, known list: time range, site, timezone, metric. Compose the flat parts: Select (root; value/defaultValue, onValueChange, open, disabled) → SelectTrigger (the 36px bordered field; size="sm" for the 28px toolbar variant) containing SelectValue (shows the chosen item's text or its placeholder) → SelectContent (portalled popper list, dark neutral-800 panel; pass the same size) → SelectItem (value required; the chosen one shows an emerald check on the right; disabled dims it). Group with SelectGroup + SelectLabel heading and separate groups with SelectSeparator. SelectScrollUpButton / SelectScrollDownButton are already inside SelectContent.

Conventions: the trigger is w-full by default, so size it with the parent. Keep size consistent across Trigger/Content/Item/Label. Use Select when there are 3-12 mutually exclusive options; for 2 options use a RadioGroup or Switch, for many searchable options use MultiSelect/Command, for free text with hints use InputWithSuggestions. Inside a Form, wrap the SelectTrigger in FormControl and bind value={field.value} onValueChange={field.onChange}.

<Select defaultValue="7d" onValueChange={setRange}>
  <SelectTrigger>
    <SelectValue placeholder="Pick a range" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Recent</SelectLabel>
      <SelectItem value="24h">Last 24 hours</SelectItem>
      <SelectItem value="7d">Last 7 days</SelectItem>
      <SelectItem value="30d">Last 30 days</SelectItem>
    </SelectGroup>
    <SelectSeparator />
    <SelectItem value="all">All time</SelectItem>
  </SelectContent>
</Select>

.Design Sync Docs Separator (`.design-sync/docs/Separator.md`) Copy Section

category: Data display Copy Chapter

A 1px hairline (Radix Separator) in neutral-800, the same tone as table row borders. One export, Separator. Props: orientation ("horizontal" default → h-[1px] w-full; "vertical" → h-full w-[1px]), decorative (default true, so it is hidden from assistive tech; set false only when the division is semantic), and className for margins or an explicit height.

Conventions: horizontal separators divide text blocks inside a Card or settings page — give them vertical breathing room with my-4 (or my-3 in dense lists). Between list rows prefer border-b border-neutral-800 on the row itself rather than a Separator per row. A vertical separator is h-full, so its parent must have a height: either make the row a fixed-height flex container (flex h-4 items-center) or set the height directly (className="h-5") when dividing toolbar button groups. Do not use separators as decoration between every element; the grayscale ramp and spacing should do most of the dividing.

<div className="text-sm font-medium">Tracking script</div>
<Separator className="my-4" />
<div className="text-sm font-medium">Data retention</div>

<div className="flex h-9 items-center gap-2">
  <Button variant="ghost" size="sm">Filter</Button>
  <Separator orientation="vertical" className="h-5" />
  <Button variant="ghost" size="sm">Export</Button>
</div>

.Design Sync Docs Sheet (`.design-sync/docs/Sheet.md`) Copy Section

category: Overlays Copy Chapter

Edge-anchored panel that slides in over a dimmed page (Radix Dialog under the hood). Use it for secondary work that keeps the page in context: site settings, a site switcher, a filter editor, a bulk-action strip. For a centered task use Dialog; for a touch-first bottom panel with drag-to-dismiss use Drawer.

Parts: Sheet (root, open/onOpenChange) → SheetTrigger (asChild around a Button) → SheetContent (portalled panel; side="right" | "left" | "top" | "bottom", default right; showClose={false} hides the built-in X) → SheetHeader / SheetTitle / SheetDescription → your content → SheetFooter (right-aligned actions). SheetClose wraps any element that should dismiss.

Conventions: right is the default and the one to reach for; left reads as navigation; bottom/top are full-width strips, so keep them short (a title line plus actions). Side panels are w-3/4 capped at max-w-sm (384px), so lay the body out as a single column with grid gap-4 py-6. Footer holds one accent confirm plus a ghost/outline cancel. Group settings rows as bordered cards (rounded-lg border border-neutral-800 p-3) with a Switch on the right.

<Sheet>
  <SheetTrigger asChild><Button variant="outline">Settings</Button></SheetTrigger>
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Site settings</SheetTitle>
      <SheetDescription>tomato.gg</SheetDescription>
    </SheetHeader>
    <div className="grid gap-4 py-6">
      <div className="grid gap-1.5">
        <Label htmlFor="domain">Domain</Label>
        <Input id="domain" defaultValue="tomato.gg" />
      </div>
    </div>
    <SheetFooter>
      <SheetClose asChild><Button variant="ghost">Cancel</Button></SheetClose>
      <Button variant="accent">Save changes</Button>
    </SheetFooter>
  </SheetContent>
</Sheet>

.Design Sync Docs Skeleton (`.design-sync/docs/Skeleton.md`) Copy Section

category: Data display Copy Chapter

Loading placeholder. Skeleton is a single div with animate-pulse, 2.8px radius, and a neutral-850 fill (one step above the card surface); it has no intrinsic size, so every instance needs a height and width class. Compose skeletons to mirror the shape of the content they replace — the layout should not jump when real data lands.

Conventions:

• Stat tile: keep the real label, replace the figure with h-9 w-[60px] and the delta with h-5 w-[50px] (this is exactly what the overview does).
• Table / list: one h-4 bar per row, flex-1 for the name column and a fixed w-12 for the figure column; 5-6 rows.
• Text: h-5 for a title, h-4 w-full body lines, make the last line shorter (w-64).
• Avatar: h-8 w-8 rounded-full.
• Put skeletons inside the same Card / CardContent the data will use; for an in-place refetch over existing data use CardLoader instead.

<Card>
  <div className="flex flex-col px-3 py-2">
    <div className="text-xs font-medium text-muted-foreground">Unique visitors</div>
    <div className="flex items-center justify-between">
      <Skeleton className="h-9 w-[60px] rounded-md" />
      <Skeleton className="h-5 w-[50px] rounded-md" />
    </div>
  </div>
</Card>

.Design Sync Docs Slider (`.design-sync/docs/Slider.md`) Copy Section

category: Forms Copy Chapter

Numeric range control (Radix Slider) for settings that are tuned rather than typed: replay sample rate, session-duration filter, retention window. One component, no sub-parts: Slider. Props are Radix's: defaultValue / value as a number array (one entry per thumb, so [40] is a single thumb and [30, 300] is a two-thumb range), onValueChange(values), min / max (default 0-100), step, disabled, orientation. It stretches to w-full.

Appearance: a 6px neutral-800 track, the filled range in emerald (accent-500), 16px near-black thumbs with a neutral-800 border. There is no built-in value label; pair it with a Label and put the current value in a muted text-sm tabular-nums text-neutral-400 span on the same row. disabled blocks interaction but draws the same (Radix puts the disabled state on a span, so the thumb's opacity rule never matches); dim the whole row yourself if the state must read visually. Use Slider for approximate values where seeing the position matters; use an Input type="number" when the exact figure matters.

const [rate, setRate] = React.useState([40]);

<div className="flex items-center justify-between mb-3">
  <Label>Session replay sample rate</Label>
  <span className="text-sm tabular-nums text-neutral-400">{rate[0]}%</span>
</div>
<Slider value={rate} onValueChange={setRate} max={100} step={5} />

// two thumbs = range
<Slider defaultValue={[30, 300]} min={0} max={600} step={10} />

.Design Sync Docs Switch (`.design-sync/docs/Switch.md`) Copy Section

category: Forms Copy Chapter

Radix toggle for a single setting that takes effect immediately (session replay on/off, public dashboard, live mode). Track is 36×20px with a 16px white thumb: emerald (accent-500) when on, neutral-800 when off, 50% opacity when disabled. Use Checkbox when the choice is submitted with a form or is one of many, and RadioGroup for mutually exclusive options.

Parts: Switch only (thumb is internal). Props: checked / defaultChecked, onCheckedChange, disabled, id, name, className. It carries the peer class, so a following Label fades automatically when the switch is disabled.

Conventions:

• Inline: flex items-center gap-2 with the Switch first, then Label htmlFor.
• Settings list (the common case): rows of flex items-center justify-between gap-4 px-4 py-3 inside a divide-y divide-neutral-800 rounded-lg border border-neutral-800 bg-neutral-900 panel; label + text-xs text-neutral-400 description on the left, switch on the right.
• One switch per row; never stack switches horizontally. Keep the label a noun phrase ("Web vitals"), not a verb.
• Hover/pressed transitions are not shown in previews.

<div className="flex items-center justify-between gap-4 px-4 py-3">
  <div className="grid gap-0.5">
    <Label htmlFor="replay">Session replay</Label>
    <p className="text-xs text-neutral-400">Record sessions for the last 7 days.</p>
  </div>
  <Switch id="replay" defaultChecked />
</div>

.Design Sync Docs Table (`.design-sync/docs/Table.md`) Copy Section

category: Data display Copy Chapter

Data table for dense analytics lists. Parts: Table (scroll wrapper + ``) → TableHeader (neutral-850 band) → TableRow → TableHead; TableBody → TableRow → TableCell; optional TableFooter (totals) and TableCaption (below the table, muted). TableSortIndicator renders the sort chevrons for a sortable column: sortDirection="asc" | "desc" shows a blue arrow, undefined shows the neutral double chevron, canSort={false} hides it.

Conventions: 14px text, 8px cell padding, hairline row borders, no zebra striping. Right-align numeric columns and add tabular-nums. Keep the first column a name/path in font-medium. Use Badge for status cells and Skeleton rows while loading.

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Page</TableHead>
      <TableHead className="text-right">Visitors <TableSortIndicator sortDirection="desc" /></TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell className="font-medium">/pricing</TableCell>
      <TableCell className="text-right tabular-nums">6,120</TableCell>
    </TableRow>
  </TableBody>
</Table>

.Design Sync Docs Tabs (`.design-sync/docs/Tabs.md`) Copy Section

category: Navigation Copy Chapter

Segmented tabs (Radix). A filled TabsList pill strip where the active TabsTrigger lifts to a darker surface; each TabsContent panel shows only while its value is active. Use it to switch between views of one thing (Overview / Sessions / Goals, Desktop / Mobile). For the lighter underline style used inside report cards use BasicTabs.

Parts: Tabs (root; defaultValue for uncontrolled, value / onValueChange for controlled) → TabsList (36px strip, bg-neutral-800, inline-flex by default; add grid w-full grid-cols-N to stretch triggers evenly) → TabsTrigger (value, disabled; active state is bg-neutral-950 with bright text) and TabsContent (value; adds mt-2).

Conventions: 2-5 triggers, sentence-case labels, no icons. Keep the list left-aligned above its content; stretch it full-width only for two-way toggles. Disable a trigger for a feature the plan lacks rather than hiding it. Focus rings are keyboard-only and are not shown in the static preview.

<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="sessions">Sessions</TabsTrigger>
    <TabsTrigger value="goals">Goals</TabsTrigger>
    <TabsTrigger value="replay" disabled>Replay</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">
    <div className="grid grid-cols-2 gap-3">{/* stat cards */}</div>
  </TabsContent>
  <TabsContent value="sessions">…</TabsContent>
  <TabsContent value="goals">…</TabsContent>
</Tabs>

.Design Sync Docs Textarea (`.design-sync/docs/Textarea.md`) Copy Section

category: Forms Copy Chapter

Multi-line text field for notes, descriptions and pasted snippets. Same chassis as Input (transparent fill, 1px neutral-800 border, neutral-400 placeholder, ring on focus) with a 60px minimum height and vertical resize. Use it for annotation notes, site descriptions, alert messages, and raw filter/config text; use Input for anything that fits on one line.

Parts: Textarea only. Forwards every native <textarea> prop (rows, placeholder, defaultValue, disabled, aria-invalid, ref).

Conventions:

• Default height is min-h-[60px]; set rows={5} (or className="min-h-32") for longer content.
• Text is 14px at md+ (text-base on phones so iOS doesn't zoom). Add font-mono text-xs for code-like content such as rule DSLs.
• There is no invalid style baked in (unlike Input): pass aria-invalid="true" for accessibility plus className="dark:border-red-400" for the red border (the dark: prefix is required: the component's own dark:border-neutral-800 overrides a bare border-red-400), and put the message in a text-xs text-red-400 line below. A right-aligned text-xs text-neutral-400 tabular-nums counter goes on the same row.
• disabled fades to 50% opacity. Always pair with a Label via htmlFor.

<div className="grid gap-1.5">
  <Label htmlFor="note">Annotation note</Label>
  <Textarea id="note" placeholder="What changed on this date?" />
</div>

<Textarea rows={5} className="font-mono text-xs" defaultValue={"path contains /docs\nAND country is Germany"} />

.Design Sync Docs TimelineSlider (`.design-sync/docs/TimelineSlider.md`) Copy Section

category: Replay Copy Chapter

The minimal playback rail of the session-replay transport bar: a 2px neutral-800 track, an emerald (accent-500) played range and a 10px emerald-300 thumb that scales up on hover and shows a grab cursor. Use it for any "position in time" control (replay progress, a funnel-step scrubber); use Slider for a value input with a visible track height, and ActivitySlider when the rail should also plot events and activity.

Single part: TimelineSlider, a thin wrapper over Radix Slider.Root, so the whole Radix API applies: value / defaultValue as a one-element array in the unit you choose (milliseconds for replay), max (the duration), min, step, onValueChange, onValueCommit (seek on release), disabled, orientation. Pass className="flex-1" so it fills the space between the elapsed and total times.

Conventions: sit it in a flex items-center gap-3 bar on a neutral-900 panel with ghost smIcon transport buttons on the left, m:ss elapsed and total in 12px muted tabular figures on either side, and a playback-rate label at the end. Hover/active scaling can't be rendered statically. The thumb hue is the only chromatic element on the bar; everything else stays neutral.

import { Button, TimelineSlider } from "@rybbit/ui";
import { Pause } from "lucide-react";

<div className="flex items-center gap-3 rounded-lg border border-neutral-800 bg-neutral-900 px-4 py-3">
  <Button size="smIcon" variant="ghost" aria-label="Pause"><Pause /></Button>
  <span className="text-xs tabular-nums text-neutral-400">0:42</span>
  <TimelineSlider
    className="flex-1"
    max={duration}
    step={100}
    value={[currentTime]}
    onValueChange={([t]) => setCurrentTime(t)}
    onValueCommit={([t]) => player.seek(t)}
  />
  <span className="text-xs tabular-nums text-neutral-400">3:00</span>
</div>

.Design Sync Docs Toaster (`.design-sync/docs/Toaster.md`) Copy Section

category: Feedback Copy Chapter

Transient confirmations after an action ("Settings saved", "Couldn't verify domain"). Mount ONE <Toaster /> at the app root (it is a configured react-hot-toast host: bottom-right, neutral-850 card with neutral-200 text in dark mode, 4.8px radius, 14px medium) and fire messages from anywhere with the toast function. Toasts stack newest at the bottom and auto-dismiss (success ~2s, default/error ~4s), so keep the message to one line that reads on its own. For state that must persist on the page use Alert; for something the user must acknowledge use AlertDialog.

Parts: Toaster (the host, no props) and toast (the API). The API takes a plain string: toast(message) (no icon), toast.success(message) (emerald check), toast.error(message) (red cross), toast.info(message) (an "i" glyph), toast.dismiss(id?) (dismiss one or all), toast.custom(node, opts) (escape hatch for a fully custom body). Every call returns the toast id.

Conventions: one toast per user action; name the object ("Goal “Signup completed” created", "Settings saved for tomato.gg"); an error says what to do next. Never use a toast for validation (that belongs in FormMessage) or for anything the user has to read later.

import { Button, Toaster, toast } from "@rybbit/ui";

// once, at the root
<Toaster />

// anywhere
<Button
  variant="accent"
  onClick={async () => {
    try {
      await saveSettings();
      toast.success("Settings saved for tomato.gg");
    } catch {
      toast.error("Couldn't save settings. Try again.");
    }
  }}
>
  Save changes
</Button>

.Design Sync Docs Tooltip (`.design-sync/docs/Tooltip.md`) Copy Section

category: Overlays Copy Chapter

Hover/focus label (Radix Tooltip). Use it to name icon-only buttons and to explain a metric or setting in one or two short lines. It is not interactive: if the content needs a link, a button or more than a couple of sentences, use Popover instead. RybbitTheme already mounts the required TooltipProvider, so never add another.

Parts: Tooltip (root; open for a controlled state, delayDuration default 300ms) → TooltipTrigger (asChild around the Button or icon) → TooltipContent (portalled: text-xs, raised neutral surface with a hairline border; props side="top" | "right" | "bottom" | "left" (default top), align, sideOffset default 4). TooltipProvider is exported but only for apps that opt out of RybbitTheme.

Conventions: keep the default top unless the trigger sits at a viewport edge. Content is sentence case, no trailing period for a single label. For a two-line explainer, put a font-medium heading first and the body in text-neutral-400, and cap width with max-w-56. Always give icon-only triggers an aria-label that matches the tooltip text. The hover-in state cannot be rendered statically; the previews use open.

<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="outline" size="icon" aria-label="Site settings">
      <Settings />
    </Button>
  </TooltipTrigger>
  <TooltipContent>Site settings</TooltipContent>
</Tooltip>

<Tooltip>
  <TooltipTrigger asChild>
    <button type="button" aria-label="What is bounce rate?"><Info className="h-3.5 w-3.5" /></button>
  </TooltipTrigger>
  <TooltipContent side="right" align="start" className="max-w-56">
    <p className="font-medium">Bounce rate</p>
    <p className="mt-1 text-neutral-400">Sessions with one pageview and no events.</p>
  </TooltipContent>
</Tooltip>

Public Security (`docs/public/security.txt`) Copy Section

security.txt for rybbit.com

We accept vulnerability reports. We do not offer monetary or bug bounty rewards.

Canonical: https://rybbit.com/.well-known/security.txt
Contact: mailto:[email protected]
Preferred-Languages: en
Expires: 2027-01-01T00:00:00Z

Server Docs Better Auth 1.7.3 (`server/docs/better-auth-1.7.3.md`) Copy Section

Better Auth 1.7.3 migration

This upgrade moves the client, server, API key and SSO packages from 1.6.25 to
1.7.3. MCP OAuth now uses @better-auth/mcp, @better-auth/oauth-provider and
the JWT plugin, with an explicit consent page at /auth/consent.
@better-auth/infra keeps its separate 0.1.x version. The MCP SDK and stateless
transport remain on their existing versions; dynamic client registration stays
enabled.

Database and cutover Copy Chapter

Migration 0018_better_auth_173.sql is additive. It creates the OAuth/JWT tables,
copies registered clients, hashes their previously plaintext secrets, and adds
team membership keys and member counts. Counts are backfilled; existing nullable
membership keys use Better Auth's compatibility lookup. New memberships use the
same key calculation as Better Auth.

Auth uses the native PostgreSQL/Kysely adapter, so its array fields are stored
as JSONB. Drizzle's native PostgreSQL arrays are not compatible with that
adapter's serialization. The Drizzle schema and snapshot reflect this.

1. Back up PostgreSQL and record the current application version. Run only the
   opening DO block from migration 0018 as a read-only preflight: it checks
   duplicate account identities and parses every nonempty legacy client metadata
   value with PostgreSQL's JSON parser. Fix any reported record before cutover.
2. Stop the old backend workers before migrating. Client registrations and team
   membership changes must not race the data copy and count backfill.
3. Apply migration 0018 with the existing file-based migration runner. The Docker
   backend entrypoint already runs npm run db:migrate before starting. For a
   manual deployment, run that command from server/ against the deployment's
   database before starting the new backend.
4. Deploy the matching client and server. Keep BASE_URL set to the public site
   origin and keep the existing BETTER_AUTH_SECRET. OAuth requires HTTPS, with
   an exception for HTTP loopback during development. Plain HTTP LAN deployments
   keep session and API key authentication but do not enable OAuth.
5. Check password login, Google/GitHub sign-in where configured, existing
   sessions/API keys, team updates, and an MCP connection through discovery,
   login, consent and a tool call. Sign out of the linked session and confirm
   its MCP bearer is rejected on the next request. The explicit BASE_URL must
   produce the registered /api/auth/callback/google and
   /api/auth/callback/github URLs; check this in both development and production.

No live database migration is part of preparing this change.

The migration stops before schema writes if accounts contain duplicate
(providerId, accountId) pairs or legacy OAuth client metadata is invalid JSON.
The metadata error identifies the affected oauthApplication.id without logging
its contents. Resolve these records explicitly before retrying. Do not apply an
account issuer backfill from the 1.7.0–1.7.2 instructions: upstream reverted
that migration in 1.7.3.

MCP client behavior Copy Chapter

• Existing OAuth clients must reconnect and approve fresh consent. Old access
  tokens, refresh tokens and consent are retained in the legacy tables but are
  not accepted by the new provider. Password sessions and API keys are not
  rewritten by this migration.
• Registered client IDs and redirect URIs are preserved. Imported confidential
  clients use client_secret_basic; the old schema did not record their token
  authentication method. Clients that previously posted a secret must switch to
  HTTP Basic or register again with their intended method.
• New native clients with loopback redirects must register
  application_type: "native" and token_endpoint_auth_method: "none".
  Other public clients must also explicitly send
  token_endpoint_auth_method: "none". Omitting it now creates a confidential client using
  client_secret_basic, even for unauthenticated registration. Such a client
  receives a secret and must authenticate with it or subsequent token requests
  fail with invalid_client.
• Discovery advertises the new /api/auth/oauth2/* endpoints. Clients caching
  the old endpoints should rediscover the server.
• Resource tokens are verified for signature, issuer, expiry, audience,
  client state and validity of the linked session. These Bearer routes reject
  proof-bound tokens.
  The single resource remains /api/mcp; per-client resource join
  enforcement is disabled so imported clients can request it.
• Access tokens are JWTs with the upstream default lifetime of one hour. There
  is no per-access-token database revocation check: /oauth2/revoke rejects JWT
  access tokens with unsupported_token_type. Revoking a refresh token prevents
  future refreshes but leaves already-issued access JWTs valid until expiry.
  Deleting or disabling the OAuth client, or signing out of the linked session,
  makes those JWTs fail verification. Do not describe a refresh-token revocation
  or consent deletion as immediately disconnecting existing access tokens.
• Existing scope semantics remain: a grant with only standard OIDC scopes has
  full API access within the user's permissions. The consent page states this
  explicitly. Custom scopes narrow that access.

Rollback Copy Chapter

The old OAuth tables remain available, and the new columns are additive. A
rollback needs a coordinated stop of the new workers before restoring the old
application version. New client registrations and consent are not copied back;
those clients will need to register or reconnect again. Old tokens retained in
the legacy tables can become usable again under the old binary, including tokens
whose corresponding access was revoked after cutover. Account for those grants
before restoring OAuth traffic. Recompute team member counts before returning
to 1.7 after any period of running 1.6.

Verification Copy Chapter

The team's internal memberCount reservation counter can drift after user
deletions that cascade to memberships. Rybbit's team lists read the membership
rows, and maximumMembersPerTeam is not configured. Reconcile this counter on
all deletion paths before enabling that limit; it is not an authoritative count
for reporting. This remains a follow-up rather than a cutover requirement.

The disposable PostgreSQL integration test applies every migration through 0018
using the production Kysely adapter. It checks client migration and secret
hashing, duplicate-account and malformed-metadata rejection, discovery, signed
consent, PKCE token exchange, refresh and its revocation, JWT revocation limits,
bearer verification, sign-out revocation, pre-migration
sessions/API keys, team keys and email OTP password recovery. Client tests cover
consent, rejection, error retry and preservation of the signed login query.

Validation used Node 24: the server suite passed with four workers, the client
suite passed, both packages type-checked, and the client production build passed
with npm run build -- --webpack. A headless browser check also exercised the
real client plugin's signed-query submission and the mobile consent layout.
Local Turbopack builds cannot resolve the existing @rybbit/shared symlink
outside the client root; the production Dockerfile already materializes that
package before building. npm run lint is blocked by the existing empty ESLint
configuration scanning generated .next files and encountering undefined rules.
The 17 new consent messages are translated in all 11 non-English locales, with
their interpolation placeholders and existing translations preserved.

Upstream references: 1.7 upgrade guide,
MCP plugin, and
changelog.

Content Blog 5k Stars (`docs/content/blog/5k-stars.mdx`) Copy Section

title: "How Rybbit Got 5,000 GitHub Stars in 9 Days" date: 2025-05-26 updated: 2026-09-28 keyword: "github stars" tags: ['growth'] author: Rybbit Team Copy Chapter

The backstory Copy Chapter

I run an open source web analytics platform with a freemium hosted version. I have a gaming stats site that gets around 1.5 million visits a month, so I needed serious web analytics. The existing platforms were either too simple (just a basic dashboard) or too complicated and enterprisey, so I decided to build my own web analytics platform since I love stats anyway.

I started working on it in January 2025, and it took around 110 days for me to launch. Rybbit being open source made the distribution problem so much easier, as I could freely advertise it in many places since it was self-hostable and free to use.

The launch strategy Copy Chapter

I made posts on 2 major subreddits - r/SideProject and r/selfhosted, plus a few smaller subs. Pretty much every post reached #1 in hot and I probably got 150k free impressions from this.

TL;DR - all I did was make like 4 Reddit posts with the same headline, got 150k free impressions, and then proceeded to go viral on X, Hacker News, Bluesky, Mastodon, and some random Asian language sites from other people sharing my project.

What I think I did right Copy Chapter

1. Full iframe embed as hero section Copy Section

I put a full iframe embed of my demo site as my hero section. A lot of analytics platforms have a demo site, but I went a step further by embedding the entire demo site into the landing page so any visitor is immediately greeted by a full demo of the product. I haven't ever seen anyone do this, but I think this is an insane hack if this suits your product.

2. Visual-first GitHub README Copy Section

I included a ton of product screenshots on my GitHub README and kept the text content short since I had a landing and docs page. People have short attention spans and aren't gonna read a wall of text.

3. Catchy positioning Copy Section

I used the post title "I built an open source Google Analytics replacement" - simple but effective positioning that immediately communicates the value.

4. Strong visual assets Copy Section

I created a good OpenGraph image that showed the best features of the product, which helped with social sharing.

5. Polish matters Copy Section

I had a genuinely good & polished product with a fully functional landing page, docs, self-hosting guide, and SaaS product that I personally use every single day. I doubt I would've gotten as much traction if I released a barely-working MVP after a few weeks.

What didn't work Copy Chapter

I made a couple launch posts from my X account, but I only had a couple hundred followers so nobody cared (though I didn't expect to go viral on X in the first place).

Some big Discord servers like the Next.js server have #showcase channels. Literally nobody reads these.

The results and reality check Copy Chapter

I optimized my launch for reach instead of revenue, so I wasn't surprised that I didn't get a huge surge of paid plan signups. The vast majority of people are self-hosting it since my most viral post was in r/selfhosted. I'm just playing the numbers game and hoping that a small single-digit percentage of people who see it will pay for the cloud version.

So far I have around 700 total signups and $900 in total revenue in 3 weeks - not life-changing money, but solid validation.

What's next Copy Chapter

The virality cooled down after the first week, but the organic growth is still going strong. I'm at 5.8k stars 3 weeks post-launch, so the daily gain is still around ~50 stars. I expect to hit 10k stars in around 3 months.

Content Blog Amplitude Alternatives (`docs/content/blog/amplitude-alternatives.mdx`) Copy Section

title: "9 Best Amplitude Alternatives for Product Teams in 2026" keyword: "amplitude alternatives" date: 2026-09-27 tags: ["product analytics", "comparisons", "tools"] author: Rybbit Team Copy Chapter

The best Amplitude alternatives for most product teams are Mixpanel and PostHog: both cover event funnels, retention, behavioral cohorts, experiments, feature flags and session replay, and both publish their prices. Heap and Pendo suit teams that want autocapture or in-app guides. OpenPanel, Rybbit, Countly and Matomo are open source and can run on your own servers, and Google Analytics 4 is the $0 fallback. This guide compares nine tools on price at your event volume, the Amplitude features each one replaces, and what each is missing.

Disclosure up front: we build Rybbit, one of the nine, and we rank it sixth for a typical Amplitude user because it replaces less of Amplitude than the five tools above it. Every claim about the other tools comes from that vendor's own pricing or documentation pages, linked inline and checked in September 2026. Where a vendor doesn't publish a number, we say so.

Quick comparison Copy Chapter

Why teams look for Amplitude alternatives Copy Chapter

Amplitude is generous where most tools are stingy. Its pricing page gives the Free plan 2 million events a month, 10,000 session replays and unlimited seats with no credit card, and every plan includes unlimited feature flags plus a small allowance of experiments, guides and surveys. The reasons teams leave are in the plan comparison table further down the same page:

• Analysis depth is tiered. Free has no behavioral cohorts and 10 saved charts per organization; Plus allows 20 behavioral cohorts. Conversion drivers and saved metrics start on Growth, and predictions, computations and cross-product analysis are limited there and complete only on Enterprise.
• History is tiered. Data history is 1 year on Free, 2 years on Plus, and unlimited only on Growth and Enterprise.
• Growth and Enterprise are sales-priced. Both are listed as "Custom", and SSO and project-level permissions start there. Role-based access control and SCIM are Enterprise-only.
• The extras are add-ons. Account-level (group) analytics, more active experiments than the one (Free, Plus) or two (Growth, Enterprise) included, extra guides and surveys, and replay retention past 1 month cost more. Amplitude says its expanded packages are "priced as a percentage of your platform plan".
• It sets cookies by default. The Browser SDK keeps user identity in a cookie with a 365-day expiry unless you change identityStorage, which usually means asking EU visitors for consent.

What the same volume costs elsewhere Copy Section

Price is a weaker reason than it sounds. Amplitude Plus starts at $0 for the first 2 million events, and on each vendor's own calculator it costs less than Mixpanel Growth at every volume we checked. Monthly billing, on the cheapest plan that covers the volume:

Sources: the calculators on Amplitude's and Mixpanel's pricing pages, PostHog's per-event rates, OpenPanel's price table and our pricing page. Annual billing cuts most rows; Amplitude's 10M tier drops to $576 a month and Mixpanel's to $840. Replay allowances differ too: 10,000 a month on Amplitude Plus, 20,000 on Mixpanel Growth, a tenth of the event tier on Rybbit Pro (1 million at 10M events), and billed separately on PostHog. Vendors also count events differently, so treat the table as a rough guide, not a quote.

Startups with under $10 million in funding and fewer than 20 employees can also get a free year of Amplitude's Growth plan. Switching makes more sense when you need what the plan gates hold back without a sales contract, want to self-host, or want tracking without cookies.

How we ranked these Amplitude alternatives Copy Chapter

We ranked by how much of a typical Amplitude setup each tool replaces: funnels, retention and cohorts first, then experiments, flags and replay, then mobile SDKs and published pricing. Mixpanel and PostHog replace nearly all of it. Heap and Pendo cover the core analytics but don't publish paid prices. OpenPanel and Rybbit cost less at volume but replace less (Rybbit has no experiments or behavioral cohorts), and Countly, GA4 and Matomo fit narrower cases. Open source gets its own section.

1. Mixpanel Copy Chapter

Best for: the closest like-for-like switch.

Mixpanel works the way Amplitude does: insights, funnels, retention and flows reports on an event model, for web and mobile. Its pricing page now puts experiments and feature flags on Free and Growth (Free gets 1,000 monthly experiment users and 10 active flags), alongside session replay, heatmaps, and US or EU data residency. SAML SSO and SCIM come with self-serve Growth, while Amplitude starts SSO at its sales-priced Growth plan.

Free is tighter than its event count suggests. The pricing docs cap it at 5 saved reports per user, let you create cohorts but not save them, and block your reports (rather than billing you) once a month passes 1 million events. On Growth the first million events are free, and the calculator shows $140 a month at 1.5 million events and $1,176 at 10 million, or $840 a month billed annually.

• Free option: 1M events and 10K session replays a month, unlimited seats
• Paid: Growth from $0; $1,176/month at 10M events
• Drawbacks: costs more than Amplitude Plus at every volume we checked; group analytics is a paid add-on; anomaly detection and root cause analysis are Enterprise-only

Our Mixpanel pricing breakdown has every Growth tier, and Mixpanel alternatives covers the rest of the field.

2. PostHog Copy Chapter

Best for: engineering-led teams that want analytics, flags, experiments, surveys and error tracking on one usage-based bill.

PostHog covers trends, funnels, retention, paths, stickiness, lifecycle and SQL, with autocapture of pageviews, clicks and form submissions (docs). Cohorts can be behavioral (did an event several times, completed a sequence, stopped, started again), and there are SDKs for iOS, Android, React Native and Flutter. Replay, flags, experiments, surveys, error tracking and a data warehouse are separate products, each with its own monthly allowance on the pricing page. Past the first million events, analytics costs $0.00005 per event, falling in tiers to $0.000009 above 250 million. Events are kept for 1 year on the free plan and 7 years on pay-as-you-go.

The core is MIT-licensed, but the self-hosting docs call self-hosted deployments "officially unsupported" and keep all paid-plan features cloud-only. More in Rybbit vs PostHog.

• Free option: 1M events, 5K recordings, 1M flag requests, 100K exceptions and 1,500 survey responses a month, no card
• Paid: per product; about $324/month at 10M events for analytics alone
• Drawbacks: many meters to watch; replay, flags and surveys are billed on top; self-hosting isn't a supported path

For the per-product rates and worked examples, see PostHog pricing, explained.

3. Heap (Contentsquare) Copy Chapter

Best for: teams that don't want to plan tracking up front and would rather pay per session than per event.

Heap has been part of Contentsquare since December 2023, when the acquisition closed, and it still sells its own plans. Its autocapture "grabs every click, swipe, tap, pageview, and fill", so you can analyze history without deciding in advance what to track, and there are autocapture SDKs for web, iOS, Android, React Native and Flutter (docs). The gap has narrowed, though: Amplitude now lists autocapture on every plan.

On the pricing page, Free includes core charts, SSO and 6 months of history. Growth adds unlimited users and reports and 12 months of history, but shows its price only after you install the snippet. Pro adds account analytics and report alerts, and Premier adds data warehouse integration and unlimited projects; both are "Custom Session Pricing", with session replay as an add-on.

• Free option: up to 10K sessions a month
• Paid: Growth by estimate after install; Pro and Premier by quote
• Drawbacks: no public paid prices; replay costs extra; 6 to 12 months of history below Pro

4. Pendo Copy Chapter

Best for: B2B SaaS teams that want product analytics and in-app guides in one tool.

Pendo pairs product analytics with in-app guides, a natural next step for teams that have outgrown Amplitude's Guides and Surveys (one guide or survey on Free and Plus). Its pricing page charges by monthly active users (MAUs), says the cost per MAU falls as you add more, and advertises your complete data history from the day you install. Free includes product analytics, guides, and Pendo-branded roadmaps and NPS surveys across unlimited web and mobile apps. Base, Core and Ultimate are "Request pricing"; session replay is an add-on on Base and included on Core and Ultimate.

• Free option: up to 500 MAUs
• Paid: by quote; a 30-day trial of the full platform goes through sales
• Drawbacks: no published prices; 500 MAUs is a low ceiling; no experiments or feature flags in the plan table

5. OpenPanel Copy Chapter

Best for: small teams that want Mixpanel-style event analytics, open source, at low cloud prices.

OpenPanel calls itself an open-source alternative to Mixpanel. Its README lists funnels, cohorts, user profiles, session replay, custom dashboards, alerts, revenue tracking and A/B variant breakdowns, with cookieless tracking and SDKs for web, iOS, Android, React Native and servers. Retention is event-based: you pick an initial event and a return event. Cloud pricing is by events, with websites, users and dashboards unlimited and two months free on yearly billing. Self-hosting is free "with unlimited events" under AGPL-3.0.

• Free option: self-hosting; the cloud has a 30-day trial with no card
• Paid: $2.50/month for 5K events, $90 at 1M, $350 at 10M
• Drawbacks: nothing free on the cloud after the trial; feature flags aren't in its feature list

6. Rybbit Copy Chapter

Best for: web products (SaaS apps, stores, content sites) that want product and traffic analytics in one cookieless tool. If that describes you, start here.

Rybbit is open-source web analytics with the product-analytics reports in the same dashboard: funnels built from page paths, custom events or autocaptured clicks, outbound links, form submits and copies; retention; user journeys; user profiles with identify() and custom traits; sessions; error tracking; and Web Vitals, next to referrers, UTM campaigns, pages and devices. Tracking is cookieless by default, so Rybbit's own tracking needs no consent banner, and the cloud is hosted in the EU.

Pricing is by events. Standard is $19 a month for 100,000 events (up to 5 websites and 3 team members) and includes everything above plus goals, email reports, API access and 3 years of data retention, against 2 on Amplitude Plus. Pro is $39 a month for 100,000 events and adds session replay (10,000 replays a month at that tier, rising with the plan), unlimited websites and team members, and 5-year retention. Cloud plans start with a 7-day trial (the card is collected at signup), and self-hosting is free under AGPL-3.0.

Where it falls short of Amplitude:

• No experiments or feature flags.
• No behavioral cohorts at Amplitude's depth. Segments are saved filters on properties such as country, UTM source, page or event name, and retention groups users by the day or week of their first visit and counts any return, with no choice of start and return events.
• Journeys are page-path Sankey diagrams, not event sequences.
• No account-level (group) analytics and no heatmaps.
• Mobile goes through the React Native SDK, which tracks screens, events, errors and users in an App Analytics dashboard mode. There's no native iOS or Android SDK and no mobile session replay.
• No Amplitude importer. Data import covers Plausible, Umami and Simple Analytics, so switching means running both tools side by side.

Pick something else if you run experiments in Amplitude today (PostHog or Mixpanel), are mobile-first (Mixpanel, PostHog or Heap), or target users with behavioral cohorts (Mixpanel or PostHog).

• Free option: self-hosting, replay included; the cloud has a 7-day trial
• Paid: Standard from $19/month, Pro from $39/month; $249 and $499 at 10M events
• Drawbacks: the list above

7. Countly Copy Chapter

Best for: mobile, desktop and connected-device apps that have to run on your own infrastructure.

Countly collects data from mobile, web and desktop apps, with crash reporting, push notifications and remote config next to analytics (README). Flex, a managed private cloud priced on MAUs and data points (Flex page), includes events, sessions, user profiles and dashboards. Per the pricing page, funnels, retention and flows are in the Intelligence add-on and A/B testing and remote config in the Adaptivity add-on, neither with a published price. Enterprise includes everything and runs on your own servers.

The free Countly Lite is AGPL-3.0 with a modified Section 7 that requires keeping Countly's branding (license). Its README calls Lite "core analytics and essential features" under "an open-source, non-commercial license", and lists no funnels or retention.

• Free option: Countly Lite, self-hosted
• Paid: Flex from $175/month with a 14-day trial; Enterprise by quote
• Drawbacks: funnels and retention cost extra on Flex; add-on prices unpublished; Lite lacks product-analytics reports

8. Google Analytics 4 Copy Chapter

Best for: $0 budgets and teams whose questions are mostly about acquisition and Google Ads.

Google says Analytics gives you its tools "free of charge", and one property can hold up to 50 web and app data streams (help center). For product questions, explorations offer funnel, path, cohort, segment overlap, user and user-lifetime reports.

The limits show up fast. Explorations are sampled once a query exceeds 10 million events, and their event-level data is kept 2 or 14 months on standard properties; longer retention needs Analytics 360, which has no public price, only a "Talk to Sales" button. Optimize, Google's testing tool, has been unavailable since September 30, 2023, and GA4's _ga cookies last 2 years, which generally means asking EU visitors for consent. More in Rybbit vs Google Analytics.

• Free option: all of it; there's no usage fee
• Paid: Analytics 360, by quote
• Drawbacks: sampling on large queries; 14-month cap on exploration data; cookie consent in the EU; no built-in experiments

9. Matomo Copy Chapter

Best for: organizations that need self-hosted, GA-style web analytics with funnels and cohorts.

Matomo is open-source web analytics under GPL v3, with funnels, users flow, cohorts, A/B testing, heatmaps, session recordings and visitor profiles on top of its traffic reports. Matomo Cloud's Business plan includes all of those, with 24 months of raw data, no sampling, 30 websites, 30 team members and data stored in Frankfurt. Its pricing page shows US visitors $26 a month for 50,000 hits, and the trial needs no card.

Self-hosted On-Premise is free with unlimited users and hits, but the product-analytics parts are paid plugins: funnels, users flow and heatmaps in the Team bundle (€275 a month, or €230 billed annually), cohorts in Business (€1,450 a month) and A/B testing in Enterprise (€3,400 a month). Plugins can also be bought one at a time.

Rybbit vs Matomo compares the two in detail.

• Free option: Matomo On-Premise, self-hosted
• Paid: Cloud from $26/month for 50K hits; on-premise bundles from €275/month
• Drawbacks: on-premise product features are paid plugins, with cohorts and A/B tests in the pricier bundles

Open-source Amplitude alternatives Copy Chapter

If analytics data can't leave your servers, or you'd rather pay for servers than per event, these are the open-source options, and their licenses differ in ways that matter:

PostHog is the closest to Amplitude's feature set, but its maintainers don't support self-hosted installs. Of the rest, OpenPanel is the nearest match to Amplitude's event model, and Rybbit is the pick for websites and web apps. If what you'll miss most is Amplitude's experimentation, GrowthBook covers feature flags and A/B tests: its cloud Starter plan costs nothing for up to 3 users, Pro is $40 per seat per month, and the self-hosted edition is free and reads from your own data warehouse (see its license).

Names to drop from older lists Copy Chapter

Some lists of alternatives to Amplitude still recommend tools that are now part of Amplitude or on their way out:

• Statsig, which had agreed to join OpenAI, was acquired by Amplitude on May 5, 2026, according to a note on Statsig's own blog. A June 2026 update says the two products are being connected at the data layer.
• June wound down its product on August 8, 2025, and its founding team joined Amplitude.
• Smartlook carries a Cisco end-of-life notice: no new subscriptions since May 31, 2026, and the platform shuts down on September 30, 2027.

Which Amplitude alternative should you pick? Copy Chapter

• Same workflow, different vendor: Mixpanel.
• Flags, experiments, surveys and error tracking on one usage-based bill: PostHog.
• Autocapture, priced by sessions: Heap.
• B2B SaaS where in-app guides matter as much as charts: Pendo.
• Open-source event analytics on a small budget: OpenPanel.
• A website or web app that needs traffic analytics, product analytics, errors and Web Vitals in one cookieless tool: Rybbit.
• Mobile, desktop or IoT apps that must stay on your servers: Countly Enterprise.
• A $0 budget: GA4, or Mixpanel and PostHog within their no-cost limits.
• GA-style web analytics on your own servers: Matomo.

If price is your only complaint, check Amplitude's Plus calculator first: at 3, 10 and 20 million events it came in under Mixpanel Growth. For the web-analytics side of the decision, see our guide to the best web analytics tools.

FAQ Copy Chapter

What is the best alternative to Amplitude?
For most product teams, Mixpanel: the same event model (funnels, retention, flows, behavioral cohorts), with experiments, feature flags and session replay, and a public price calculator. PostHog is the better pick if you also want error tracking and surveys, or an open-source core.

Is there a free Amplitude alternative?
Yes. Mixpanel costs nothing up to 1 million events a month, PostHog up to 1 million events and 5,000 recordings, Heap up to 10,000 sessions and Pendo up to 500 monthly active users, and GA4 has no usage fee. Self-hosted OpenPanel, Countly Lite, Matomo and Rybbit cost only the server they run on.

Who are Amplitude's main competitors?
Amplitude's own site footer lists ten under "Compare us": Adobe, Google Analytics, Contentsquare, Fullstory, Heap, LaunchDarkly, Mixpanel, Optimizely, Pendo and PostHog. In product analytics specifically, the direct competitors are Mixpanel, PostHog, Heap and Pendo.

Is there an open-source alternative to Amplitude?
Yes: PostHog (MIT core), OpenPanel and Rybbit (both AGPL-3.0), Countly Lite (AGPL-3.0 with branding terms) and Matomo (GPL-3.0), plus GrowthBook for experiments and feature flags. PostHog is the closest to Amplitude but doesn't support self-hosted installs; OpenPanel is the nearest of the rest.

Is Amplitude cheaper than Mixpanel?
On their own calculators, yes: $720 against $1,176 a month at 10 million events, and $94 against $378 at 3 million, both on monthly billing. Mixpanel's edge is SAML SSO on self-serve Growth, which Amplitude keeps for its sales-priced plans.

Content Blog Best Analytics Mcp Servers (`docs/content/blog/best-analytics-mcp-servers.mdx`) Copy Section

title: "Best Analytics MCP Servers in 2026: GA4, PostHog, Mixpanel" keyword: "analytics mcp server" date: 2026-09-27 tags: ["mcp", "ai", "comparisons", "tools"] author: Rybbit Team Copy Chapter

An analytics MCP server connects an AI assistant (Claude, ChatGPT, Cursor, Codex and others) to your analytics through the Model Context Protocol. You ask "which pages lost the most traffic last week?" and the assistant calls the vendor's tools instead of you exporting a CSV. Most major analytics vendors now ship one, and they differ more than the name suggests. PostHog, Amplitude, Mixpanel, Contentsquare and Rybbit run hosted servers you connect with a URL and a login. Google Analytics and Microsoft Clarity ship local servers you install yourself, and both are read-only. Matomo's runs inside your own Matomo. Google Search Console has no official server, and Plausible's docs point to one built by Sentry.

Disclosure: we build Rybbit, which has its own MCP server and is listed first. Every claim about the other servers comes from that vendor's own documentation or pricing pages (for the two community projects, their GitHub READMEs), linked inline and checked in September 2026. Tool counts are what each vendor's docs listed on the day we checked, and they change often.

Analytics MCP servers compared Copy Chapter

Rybbit MCP server Copy Chapter

Rybbit is open-source, cookieless web and product analytics. Its MCP server is hosted at https://app.rybbit.io/api/mcp, and self-hosted installations serve the same endpoint from their own domain. It has 44 tools: 28 read-only and 16 that write. The read tools cover traffic overviews and breakdowns, live visitors, custom events, JavaScript errors, Web Vitals, retention, user journeys, sessions and raw events. The write tools create and edit goals, funnels, sites, members and teams, and user profiles, including GDPR erasure of one person's data.

Two tools set it apart. run_query runs read-only ClickHouse SQL against a site-scoped events table, capped at 1,000 rows and 60 seconds of execution, for questions the fixed tools can't answer. And on Rybbit Cloud, once a site admin connects Google Search Console under Site settings > Integrations, get_search_console_data returns clicks, impressions, CTR and average position by query, page, country, device or date, with filters and up to 25,000 rows, through the same connection as your on-site data.

Claude Code, Claude Desktop, Codex and opencode connect with OAuth. Other clients (Cursor, VS Code, anything that speaks Streamable HTTP) use an API key, which you can limit to resource:action scopes such as analytics:read; the tool list then shrinks to match. Every call re-runs the dashboard API's role checks and rate limits, and the delete tools carry the MCP destructive hint so well-behaved clients confirm first. The server contains no AI model and sends nothing to an AI provider on its own.

The limits: the MCP server has no tools for feature flags, experiments, dashboards or session replay, so an agent can't review recordings through it. The Search Console tools read Search Analytics only (no URL Inspection, sitemaps or indexing requests) and need Rybbit Cloud. The server comes with every Cloud plan: Standard from $19/month for 100k events, or Pro from $39/month with higher API rate limits, per the pricing page. Plans start with a 7-day trial, and the card is collected at signup. Self-hosting is free under AGPL-3.0.

• Setup: claude mcp add --transport http rybbit https://app.rybbit.io/api/mcp in Claude Code; the MCP docs cover other clients
• Skip it if: you want an agent to manage feature flags and experiments or dig through session replays; PostHog, Amplitude and Mixpanel expose tools for both.

Google Analytics (GA4) MCP server Copy Chapter

Google's Google Analytics MCP server is official (it's published under the googleanalytics GitHub organization and linked from Google's developer guide) but still labeled experimental. It's a local server: a Python package you start with pipx run analytics-mcp. There is no hosted URL, and Analytics isn't on Google's list of its remote MCP servers.

It has seven tools: account summaries, property details, Google Ads links, custom dimensions and metrics, and three report runners over the Data API (run_report, run_funnel_report and run_realtime_report). Google's guide is explicit that the server "is available for read requests only. It can't edit your Google Analytics configuration or settings."

Setup is where it costs you; our Google Analytics MCP setup guide walks through each step. You need a Google Cloud project with the Analytics Admin API and Analytics Data API enabled, Application Default Credentials that carry the analytics.readonly scope (from your own OAuth client, or by impersonating a service account through gcloud), and Python with pipx. The README documents Gemini CLI, Gemini Code Assist and Claude Code. GA4 itself is "free of charge", and the server's calls draw on Data API quotas: 200,000 core tokens per property per day on a standard property. For how the products compare, see Rybbit vs Google Analytics.

Setup: the Google Cloud, credential and client steps are in the README.

PostHog MCP server Copy Chapter

PostHog's MCP server is the broadest one here. It's hosted at https://mcp.posthog.com/mcp and routes you to the US or EU region based on the account you log in with. Its tools reference lists more than 1,000 tools in about 70 categories, spanning product and web analytics, SQL (execute-sql), feature flags, experiments, error tracking, session recordings, surveys, logs and data pipelines. To keep that list from flooding the model's context, most clients get a "CLI mode" with a single exec tool that finds and calls the others on demand; Cursor registers every tool.

It reads and writes by default. The FAQ documents a read-only switch (the x-posthog-read-only header or ?readonly=true), filters by feature category or tool name, and headers that pin a session to one organization or project. You log in with OAuth, or use a personal API key created with the "MCP Server" preset; enterprise plans can manage access through an identity provider.

On cost, PostHog's FAQ says: "Connecting to the MCP server and calling its MCP tools is free. Standard PostHog usage and billing still apply to the underlying data your queries consume." A few AI-powered tools are billed as PostHog AI spend and only appear when AI data processing is enabled. PostHog's pricing includes the first 1 million product analytics events each month free. If you land on the PostHog/mcp GitHub repo, it's archived; the server now lives in PostHog's main repository. For the products themselves, see Rybbit vs PostHog.

Setup: npx @posthog/wizard mcp add, or add the URL by hand using the client guides.

Amplitude MCP server Copy Chapter

Amplitude's MCP server is hosted at https://mcp.amplitude.com/mcp, with https://mcp.eu.amplitude.com/mcp for EU data residency, and authenticates with OAuth 2.0. Its docs list 45 tools. On the read side it searches charts, dashboards, notebooks, experiments and cohorts, runs ad-hoc segmentation, funnel and retention queries, and finds session replays from the last 30 days. On the write side it creates and edits charts, dashboards, notebooks, cohorts, experiments, feature flags and metrics, and manages the tracking plan, with a two-step confirmation before deleting events or properties.

Access is on by default for every user in the organization. Admins can block it under Settings > Content Access > MCP, and two role actions, Use MCP (read) and Use MCP (write), limit what an agent can do per project. ChatGPT gets a curated subset of about 25 tools that leaves out session replay. The docs say "any existing Amplitude customer" can use it, and the pricing page lists "AI Agents and MCP" on the Free plan, which covers 2M events a month.

Setup: add the URL as a remote server in your client; the Amplitude MCP docs have guides for Claude, ChatGPT, Cursor, Codex, Gemini CLI and others.

Mixpanel MCP server Copy Chapter

Mixpanel's MCP server is hosted in three regions: https://mcp.mixpanel.com/mcp plus EU and India endpoints. Its docs list 63 tools: insights, funnel, flow and retention queries; dashboards (create, update, duplicate, delete); cohorts, custom properties, lookup tables and saved metrics; a tool that analyzes one user's replays alongside their events; and a large set of Lexicon tools that edit event descriptions, merge duplicate event names and mark PII. Experiment and feature flag tools are in open beta.

You connect with OAuth, or with a service account (in beta) sent as a static header for CI jobs and shared agents. Mixpanel's docs are direct about the trade-offs: "the AI assistant can both read and write to Mixpanel on your behalf," your data goes to whichever AI provider you use, and "The MCP server does not currently support HIPAA requirements." Each user gets up to 600 MCP requests per hour.

Whether it's switched on depends on account age. Free and Growth accounts created after August 1, 2026 have MCP enabled by default; on every other account, an organization admin has to enable it under Settings > Org > Overview. The pricing page lists a Free plan with up to 1M events a month.

Setup: add your region's URL to your client; the Mixpanel MCP docs cover OAuth and service-account configs per client.

Google Search Console MCP Copy Chapter

As of September 2026, Google doesn't publish a Search Console MCP server. It isn't on Google's list of Google and Google Cloud MCP servers, which covers products like BigQuery, Maps and Workspace, and the "Google Search Console MCP" servers you'll find are third-party projects built on the public Search Console API. Our Google Search Console MCP guide compares them, with setup steps and example prompts.

One widely used option is mcp-gsc (MIT). It runs locally via uvx mcp-search-console and authenticates with an OAuth desktop client you create in your own Google Cloud project, or with a service account you add to the property. Its 20 tools go past reporting: URL inspection (up to 10 URLs per batch), indexing-issue checks, sitemap submission and deletion, and adding or removing properties. That's useful, and it also means an agent can change your Search Console setup, so review the tools before you let one run.

There are two other routes to search data. GA4's Data API, which the GA server's run_report calls, exposes organic Google Search clicks, impressions, CTR and average position for properties with an active Search Console link. And Rybbit's hosted Search Console tools, covered above, need no Google Cloud project, but they cover Search Analytics only (no URL inspection or sitemaps) and only on Rybbit Cloud.

Setup: credential and client steps are in the mcp-gsc README.

Microsoft Clarity MCP server Copy Chapter

Microsoft's Clarity MCP server is official and local: you run it with npx @microsoft/clarity-mcp-server --clarity_api_token=... or install it as a Claude Desktop extension. It authenticates with a Data Export API token that a project admin generates under Settings > Data Export. The GitHub repo lists three read-only tools: query-analytics-dashboard (traffic, scroll depth, engagement time and other dashboard metrics), list-session-recordings (recordings filtered by URL, device, browser, OS, country, city and more) and query-documentation-resources (answers from Clarity's docs).

The limits come from the API underneath. Microsoft's MCP guide states: "Each project permits up to 10 API requests per day, with a maximum of 3 days' data and up to 3 dimensions per request." The Data Export API docs add that a response is capped at 1,000 rows, with no pagination. Ten requests covers a morning check-in; an agent that iterates will use them up quickly. Microsoft lists higher limits as a planned improvement. Clarity itself is, per its FAQ, "a free service forever."

Setup: token and client config are in the Microsoft Learn guide.

Contentsquare (Hotjar) MCP server Copy Chapter

Hotjar doesn't have its own MCP server. Contentsquare's Hotjar page says the two products "have merged into a single, more powerful experience intelligence platform" and that new users sign up on Contentsquare, so for "Hotjar MCP" the official route is Contentsquare's MCP server. Contentsquare's help center doesn't say whether legacy Hotjar accounts can connect.

The server is hosted and uses OAuth, with access tokens that expire hourly and refresh automatically. Only Customer Admins can set it up (Analysis setup > Model Context Protocol) and grant access to other users. It supports funnel, journey and impact analysis, page comparison, site and page metrics, and error analysis, which requires Experience Monitoring; the help center's capability list doesn't mention session replay or heatmaps. It's read-only for now: the Write permission is "reserved for future MCP tools" and selecting it "now has no effect."

It's the only server here with a published tool-call allowance per plan. Only calls that return analytics count, and the pool is shared across the whole account:

When the allowance runs out, the server stops processing new requests until it resets, unless you're on Pro or Enterprise and buy more capacity.

Setup: an admin follows the in-app steps for each AI client, as described in the help center.

Matomo MCP server Copy Chapter

Matomo's MCP Server plugin is official, licensed GPL-3.0, and runs inside your Matomo, so the endpoint is your own instance. According to Matomo's setup guide, "The MCP is included with Matomo Cloud. For Matomo On-Premise, you must first install and activate the MCP Server plugin." Either way, a superuser has to switch it on under Administration > System > General settings.

Out of the box it's read-oriented, with tools for sites, reports and report metadata, processed report data, goals, segments and dimensions. Raw Matomo API access is off by default. An admin can open it partially, with separate checkboxes for read, create, update and delete methods, or fully, at which point an agent can call state-changing methods such as creating segments. Admins can also cap the highest privilege level usable over MCP.

You authenticate with a Matomo token_auth sent as a Bearer token, or with OAuth 2.0 through Matomo's OAuth2 plugin. The OAuth path has caveats: tokens last 3,600 seconds by default, refresh "must currently be handled manually," and clients that expect fully spec-compliant discovery endpoints may not connect. See Rybbit vs Matomo for the analytics side.

Setup: enable it, copy the endpoint from the admin screen, then follow Matomo's setup guide and its per-client guides.

Plausible MCP server Copy Chapter

Plausible doesn't maintain an MCP server itself. Its data access docs point to one "built by the Sentry team": getsentry/plausible-mcp (MIT). It has four read-only tools (get_timeseries, get_breakdown, get_conversions and compare_periods) and runs either locally over stdio or on Sentry's hosted instance at https://plausible-mcp.sentry.dev/mcp, where you pass your own Plausible API key as a Bearer token.

That key is the catch. The server needs a Stats API key, and per the Stats API docs, "Stats API is a Business plan feature," with a default limit of 600 requests per hour. On Plausible's lower plans, there's no key to connect with. For the analytics products themselves, see Rybbit vs Plausible.

Setup: hosted and local configs are in the getsentry/plausible-mcp README.

How to choose an analytics MCP server Copy Chapter

Most teams use the server that comes with the analytics tool they already have; few switch vendors for an MCP server. If you're choosing both, or connecting more than one tool, these are the differences that matter:

• Product-analytics depth: PostHog, Amplitude and Mixpanel have the deepest servers, with funnels, retention, cohorts, experiments, feature flags and replay tools, and write access to match. PostHog covers the most products; Amplitude and Mixpanel add tracking-plan and Lexicon cleanup that data teams will use.
• Web analytics and search: For traffic, sources, pages and conversions, look at Rybbit, GA4, Matomo or Plausible. Rybbit has dedicated Search Console tools, and GA4's server reaches Search Console metrics if the property is linked. GA4's is reporting only; Rybbit's also manages goals, funnels and sites.
• Least setup: Hosted servers with OAuth (Rybbit, PostHog, Amplitude, Mixpanel, Contentsquare) connect with a URL and a browser login. GA4 needs a Google Cloud project, two APIs, gcloud credentials and Python; Clarity needs Node.js and a token.
• Privacy and data control: Self-hosting keeps the analytics side on your infrastructure, and Rybbit and Matomo both serve their MCP endpoint from your own server when self-hosted. Whatever you pick, query results go to your AI provider.
• Guardrails: GA4, Clarity, Contentsquare and the Plausible server can't change anything. For the rest, restrict the agent with PostHog's read-only mode, Rybbit's scoped keys, Amplitude's role actions or Matomo's API access setting.
• Quotas: Clarity's 10 requests a day is the tightest limit here, followed by the 300 tool calls a month on Contentsquare's Free plan. Mixpanel allows 600 MCP requests per user per hour, and Plausible's Stats API 600 per hour per key.

FAQ Copy Chapter

What is an analytics MCP server?
It's a service that exposes an analytics product's data and actions as tools an AI assistant can call through the Model Context Protocol, an open standard. A hosted server is a URL you add to your client; a local server is a program your client starts on your machine. Either way, the assistant picks a tool, the server runs it with your credentials, and the result comes back into the conversation.

Is it safe to connect an AI assistant to my analytics?
It can be, with the care you'd give any API key. Give each integration its own revocable credential with the narrowest access that works, such as PostHog's read-only mode, Rybbit's scoped keys, Amplitude's MCP role actions or a dedicated low-privilege Matomo user, and keep confirmations on for anything that deletes. Watch for prompt injection too: page titles, referrers and event names are written by your visitors, and PostHog's FAQ warns that "LLMs can be tricked into following untrusted commands." Rybbit strips control and bidirectional-override characters from tracked text, but an agent should still treat that text as data, never as instructions.

Does my analytics data leave the vendor?
Yes. Whatever a tool returns goes to the model provider behind your AI client. Mixpanel's docs say so directly, and Amplitude's docs note that "The AI service you're using (for example, Claude or Gemini) processes your Amplitude data." The servers differ in what they do with it themselves: PostHog says its server "does not store your analytics data," Contentsquare says it is "not training any third-party models with data accessed through the MCP server," and Rybbit's server contains no AI model and returns data only to the client you connect. Mixpanel's MCP server isn't covered by its HIPAA BAA, so check compliance scope before connecting regulated data.

How much do analytics MCP servers cost?
Usually nothing beyond the analytics plan. Google Analytics, Clarity and the community Search Console server are free but self-run; PostHog's server is free to connect (some AI-powered tools bill as PostHog AI spend); Amplitude and Mixpanel include theirs on their Free plans. The exceptions: Contentsquare meters tool calls by plan, and the Sentry-built Plausible server needs Plausible's Business plan. Your AI client's subscription is a separate cost.

Rybbit's server comes with Cloud plans from $19/month, or at no cost when self-hosted.

Is "MCP analytics" the same thing?
No. "MCP analytics" usually means measuring how AI agents use your own MCP server: which tools they call and where calls fail. PostHog's MCP Analytics (in beta) is one example. This guide covers the reverse: servers that let an agent read your analytics.

Content Blog Best Google Analytics Alternatives (`docs/content/blog/best-google-analytics-alternatives.mdx`) Copy Section

title: "9 Best Google Analytics Alternatives in 2026 (Free & Paid)" keyword: "google analytics alternatives" date: 2026-07-19 updated: 2026-09-28 tags: ["analytics", "privacy", "comparisons"] author: Rybbit Team Copy Chapter

Google Analytics is still the default, and still the tool people most want to leave. Since the forced GA4 migration, the complaints have been remarkably consistent: the interface buries simple questions under 150+ reports, busy properties get sampled data, cookie-based tracking forces consent banners that silently drop a third or more of your real traffic, and several EU data-protection authorities have ruled that Google Analytics data transfers violated GDPR.

The good news is that the alternatives in 2026 aren't compromises anymore. Several of them ship features GA4 has never had (session replay, error tracking, uncomplicated funnels) while staying cookie-free and consent-banner-free.

Full disclosure up front: we build Rybbit, the first tool on this list. We've kept every claim about the other tools factual (pricing and limits below come from each vendor's own published pages as of July 2026), and we'll tell you honestly when another tool is the better fit.

Quick comparison Copy Chapter

Why people are leaving GA4 Copy Chapter

Before the list, it's worth being precise about what you're escaping, because it determines which alternative fits:

• Consent loss. GA4 needs cookies, so GDPR/ePrivacy requires a consent banner in most jurisdictions. A large share of visitors decline. Teams that switch to cookieless analytics routinely find their real traffic is 30–60% higher than GA4 reported.
• Sampling and retention. Complex reports on busy properties get sampled, and standard GA4 properties keep event-level data for at most 14 months. Unsampled exports live in GA360, which starts around $50,000/year.
• Complexity. GA4 is an event warehouse with a reporting UI, not an analytics product. Most teams need a dashboard, not a data modeling project.
• Legal risk. Data-protection authorities in Austria, France, and Italy all found GA's EU–US transfers unlawful in the Schrems II era. The regulatory direction hasn't reversed.

If you searched for a GA4 alternative specifically because of one of these, jump to the tool that fixes it: consent loss and legal risk → any cookieless tool below; sampling → Rybbit or Matomo; complexity → Plausible, Fathom, or Pirsch.

1. Rybbit Copy Chapter

Best for: teams that want GA4-level depth (funnels, session replay, error tracking) without GA4's complexity or cookie banners.

Rybbit is an open-source, cookie-free analytics platform that deliberately sits between the "simple stats" tools and the heavyweight product-analytics suites. The dashboard reads like Plausible (one page, instantly legible), but underneath it ships the features that usually force teams back to Google: funnels, user journeys, session replay, error tracking, Web Vitals, user profiles, and custom events with attributes.

Because it's cookie-free with daily-rotating visitor hashes, you don't need a consent banner, and you see every visitor, including the ones GA4's banner was hiding from you. There's no sampling at any traffic level. Independent reviewers have come to the same conclusion: Travis of travis.media called Rybbit the best Google Analytics alternative after testing it against the field.

Pricing starts at $19/month for 100k events with a 7-day free trial; session replay and unlimited sites come with Pro, from $39/month. It's also fully open source and free to self-host with Docker. The main limitation is that there's no historical import from GA4 (Plausible, for one, offers a GA importer); Rybbit's importers cover Plausible, Umami, and Simple Analytics. Rybbit is also younger than Matomo or Plausible, though it ships things Plausible lacks, such as session replay and error tracking.

2. Plausible Copy Chapter

Best for: simple, lightweight traffic stats with the longest track record among privacy tools.

Plausible is the tool that made privacy-first analytics mainstream: a single-page dashboard, a script it advertises as ~54× smaller than GA's, and cookieless tracking that needs no consent banner. It's open source, EU-hosted, and independent.

The trade-off is depth. Plausible intentionally stops at traffic analytics: goals and simple funnels exist, but there's no session replay, no error tracking, no user-level view. If your questions are "where do visitors come from and what do they visit," it answers beautifully; if you ask "why did signups drop," you'll need another tool alongside it.

Starter is $9/month for 10k pageviews on one site; Growth at $14/month and Business at $19/month add sites and team members. The trial runs 30 days with no card required, annual billing gets you two months free, and self-hosters have a free Community Edition. Two things to watch: pageview-based pricing climbs with traffic, and the feature set is deliberately minimal.

See our detailed Rybbit vs Plausible comparison.

3. Matomo Copy Chapter

Best for: teams that want the closest thing to old Universal Analytics, or a mature free self-hosted option.

Matomo (formerly Piwik) is the veteran of this list, nearly two decades old, with the largest feature surface of any GA alternative: heatmaps, A/B testing, tag manager, and hundreds of plugins. Its free on-premise Community Edition has no hit limits, which has made it the default for public-sector and compliance-heavy deployments.

The honest downside is age: the interface feels like the era it came from, and the full feature set on-premise means assembling paid plugin bundles (Team bundles from €275). Cloud pricing is hit-based and EU-hosted (Frankfurt) with no data sampling.

Cloud starts at €29/month for 50k hits with a no-card free trial, while the on-premise Community Edition is free forever, and it's the most battle-tested self-hosted analytics there is. Weigh that against the dated UX, plugin-based pricing complexity, and a heavier footprint to run than newer tools.

See Rybbit vs Matomo.

For a head-to-head with GA4, see Matomo vs Google Analytics.

4. Fathom Analytics Copy Chapter

Best for: set-and-forget simple stats from a long-running independent company.

Fathom was one of the first paid privacy-analytics products, and it stays deliberately simple: one dashboard, cookieless tracking, forever data retention, and every plan includes at least 50 sites. It's a polished, stable product from a small company that's been profitable for years.

Pricing is a slider by pageviews: $45/month at 500k pageviews (the entry 100k tier is priced lower on their slider), with a 7-day trial and two months free on annual billing. There's no free tier (their FAQ is upfront about that) and no self-hosting. Simple by design also means no funnels on the level of product tools and no replay.

See Rybbit vs Fathom.

5. Umami Copy Chapter

Best for: developers and hobby projects that want free, minimal, MIT-licensed analytics.

Umami is a lightweight open-source analytics tool that developers love: trivial to self-host, MIT-licensed, and its cloud has a genuinely free Hobby plan. The product covers pageviews, referrers, custom events, and basic reports, and stops there.

The Hobby cloud plan is free forever; Pro is $20/month for 1M events, with a 14-day trial on paid plans. Self-hosting is free and among the easiest to run (a small Node app plus a database). Keep expectations in check, though: reporting depth is minimal, the team behind it is small, and most of its adoption is the free tier.

See Rybbit vs Umami.

6. PostHog Copy Chapter

Best for: product engineering teams that want analytics, feature flags, A/B testing, and a data warehouse in one platform.

PostHog comes at this list from the other direction: it's a product-analytics platform that happens to include a web analytics dashboard. If you want feature flags, experiments, SQL access to raw events, and session replay in a single vendor, it's the strongest option, and its free tier is huge: 1M events every month, no card required.

The flip side: PostHog is a lot. The pricing is per-product and usage-based (from $0.00005/event after the free tier), which is cheap at small scale and requires spreadsheet attention at large scale, and the interface has GA4-ish complexity because it's solving a bigger problem than web analytics.

You get 1M events/month free, then usage-based billing, with a card only needed past the free tier. A hobby self-deploy exists, but the real product is cloud. Both the complexity and the cookie/consent posture depend on how you configure it, and web analytics is a side dish, not the meal.

See Rybbit vs PostHog.

7. Simple Analytics Copy Chapter

Best for: EU-based companies that want the most privacy-conservative option.

Amsterdam-based Simple Analytics is exactly what the name says, with a notable 2026 twist: it now positions itself as a complement that fixes the traffic GA4 misses, arguing GA can under-report by up to 60%. It's EU-hosted end to end, has a free tier for hobby sites, and an AI chat interface over your stats.

The hobby tier is free (1 user, 5 websites, 1 month of history); paid plans start at $20/month with usage-based sliders, and the 14-day trial needs no card. Self-hosting is not offered. Watch the per-user pricing if you have a team, and note the short history on the free tier. Like Plausible and Fathom, it's simple by design.

See Rybbit vs Simple Analytics.

8. Pirsch Copy Chapter

Best for: the lowest-priced paid entry point in privacy analytics.

Pirsch is a German-built, cookieless analytics tool with developer-friendly touches (server-side tracking via SDKs is a first-class feature) and aggressive pricing: $6/month covers 10k pageviews across up to 50 websites with unlimited team members and unlimited retention. The $12/month Plus tier adds funnels and A/B testing. It also ships importers for GA, Plausible, and Fathom.

Plans start at $6/month with a 30-day no-card trial. Self-hosting is gated to the paid Enterprise tier; the code isn't free OSS. And the feature set is smaller than Rybbit's or PostHog's, with no session replay or error tracking.

9. Cloudflare Web Analytics Copy Chapter

Best for: a free rough signal when you can't justify any budget, not a GA replacement.

Cloudflare's free web analytics is cookieless and takes one minute to enable if you're already behind Cloudflare. But know what you're getting: per Cloudflare's own developer docs, dashboard stats are based on a ~10% sample of page-load events and retention is limited to 30 days. There are no custom events, goals, or funnels.

The price is free. The limitations are the point: sampled reporting, ~30-day retention, and minimal features make it fine as a sanity check and unusable as your only analytics.

Which Google Analytics alternative should you pick? Copy Chapter

• Depth without the pain (funnels, replay, errors, and a dashboard anyone can read): Rybbit. That's the exact gap we built it for.
• The simplest possible stats page: Plausible, Fathom, or Pirsch (cheapest), in roughly that order of polish.
• Maximum features, and you don't mind the learning curve: PostHog (modern, product-focused) or Matomo (mature, UA-like).
• Free forever: Umami's Hobby cloud tier, or self-host Rybbit, Umami, Plausible CE, or Matomo, all genuinely free to run yourself.
• Zero budget and zero setup: Cloudflare, eyes open about sampling.

FAQ Copy Chapter

Do I still need a cookie banner with these tools?
Not for the cookieless ones (Rybbit, Plausible, Fathom, Umami, Simple Analytics, Pirsch, Cloudflare) when used as designed: they don't set cookies or track individuals across sites. GA4 and full-configuration PostHog generally do require consent in the EU.

Can I import my Google Analytics history?
Effectively no. Google only exports GA4 data to BigQuery, and no alternative can rebuild its reports from that. The standard move is to run your new tool in parallel with GA4 for a few weeks, then archive the GA4 property. (Rybbit does import data from Plausible, Umami, and Simple Analytics if you're switching between alternatives.)

Is Google Analytics illegal in Europe?
It's not banned, but DPAs in Austria, France, and Italy ruled its EU–US data transfers unlawful under GDPR, and using it compliantly requires consent banners plus careful configuration. Cookieless alternatives remove most of that burden.

What's the best free Google Analytics alternative?
Self-hosting an open-source tool (Rybbit, Umami, Plausible CE, Matomo) gives you the most for free if you can run Docker. If you want free cloud hosting, Umami's Hobby plan and PostHog's 1M-events tier are the real ones; Cloudflare is free but sampled.

Start a free Rybbit trial or explore the live demo to see what GA4 has been hiding. Setup is one script tag and takes about five minutes.

Content Blog Best Session Replay Tools (`docs/content/blog/best-session-replay-tools.mdx`) Copy Section

title: "10 Best Session Replay Tools in 2026 (Free & Open Source)" keyword: "session replay tools" date: 2026-09-13 updated: 2026-09-27 tags: ["session replay", "comparisons", "tools"] author: Rybbit Team Copy Chapter

Session replay tools record what a visitor does on your site (clicks, scrolls, page changes, masked typing) and let you watch it back like a video. This guide compares ten of them on price, limits, privacy defaults, and whether you can run them on your own servers.

Disclosure up front: we build Rybbit, one of the tools on this list. Every claim about the other nine comes from that vendor's own pricing or documentation pages, linked inline and checked in September 2026. Where a vendor doesn't publish a number, we say so rather than guess.

Quick comparison Copy Chapter

How to choose a session replay tool Copy Chapter

Privacy controls. What is masked before data leaves the browser, and is that the default? Sentry masks all text, inputs and media unless you loosen it. Clarity masks numbers, emails and every input box. PostHog and Rybbit mask input values by default but show page text unless you tag it. LogRocket only guarantees that passwords are never recorded.

Sampling and limits. Vendors meter replay per session (Mouseflow, Lucky Orange, LogRocket), per recording (PostHog, Sentry), or with a replay cap separate from the session or event quota (Contentsquare, and Rybbit, whose Pro plan includes replays equal to 10% of its event allowance). Retention runs from 30 days (Clarity, Rybbit cloud, Sentry's free plan) to 12 months (FullStory's free plan, Mouseflow Premium).

Bundled or standalone. Replay is most useful next to the data that sent you there: a funnel drop-off, a JavaScript error, a rage-click. Rybbit, PostHog, Sentry and LogRocket bundle replay with analytics or error tracking; Clarity, Hotjar, Mouseflow and Lucky Orange pair it with heatmaps.

Self-hosting. If recordings can't leave your infrastructure, the shortlist is Rybbit, OpenReplay, PostHog (with caveats) and Sentry. Everything else here is cloud only.

Cost at 100k sessions a month. Starting prices hide the curve. This is what each tool's published pricing works out to at roughly 100,000 sessions or recordings a month, computed from the pages linked in each section:

Rybbit Copy Chapter

Rybbit is open-source, privacy-first web analytics with session replay built into the same dashboard as funnels, user journeys, error tracking, Web Vitals and user profiles. Replay records DOM mutations rather than video. You filter recordings by minimum duration, browser, device, country, referrer, channel or user ID, then press play; each replay carries a breadcrumb timeline of pages, clicks and custom events.

Replay is opt-in per site (feature guide), all input values are masked by default, and the script attributes let you block elements entirely, ignore interactions on specific fields, or mask text by selector. The analytics side is cookieless, so there is no consent banner to lose visitors behind.

The honest limits: on Rybbit Cloud, replay is a Pro-plan feature. Standard (from $19/month) doesn't include it; Pro starts at $39/month for 100k events, or $26/month billed annually, per the pricing page. Plans start with a 7-day trial (a card is collected at signup and not charged until the trial ends). Cloud replays are kept for 30 days. There are no heatmaps, and replay is web only; the React Native SDK tracks events but doesn't record screens. If you self-host, everything including replay is free under AGPL-3.0 and you set your own retention.

• Pros: replay, analytics, errors and funnels in one tool; inputs masked by default; replay quota grows with the plan (10,000 a month at 100k events); free self-hosting with replay included
• Cons: replay needs the Pro plan on cloud; 30-day cloud retention; no heatmaps; no native mobile replay
• Pricing (as of September 2026): Standard from $19/month, Pro (with replay) from $39/month at 100k events; self-hosted free. Source: rybbit.com/pricing

Microsoft Clarity Copy Chapter

Clarity is what people mean by "free session replay". Microsoft's FAQ says: "Clarity is a free service forever. You never encounter traffic limits or are compelled to upgrade to a paid version", with no sampling and no credit card. Recordings, heatmaps and ML insights are included, and there are mobile SDKs for Android, iOS, React Native, Flutter and Cordova/Ionic.

Recordings are kept for 30 days (favorites and a random sample stay up to 9 months). Data lives with Microsoft, with no self-hosted option. And the same FAQ notes that for visitors in the EEA, UK and Switzerland, "valid consent is required" to use recordings, and without it Clarity limits data collection in those regions.

Masking defaults are sensible: Balanced mode masks numbers and email addresses, input boxes and drop-downs are masked in every mode, and Strict mode masks everything.

• Pros: free with no traffic limits; no sampling; heatmaps and native mobile SDKs included
• Cons: 30-day recording retention; consent required for EEA/UK/Swiss visitors; cloud only, hosted by Microsoft
• Pricing (as of September 2026): $0, no paid tiers. Source: Clarity FAQ

Hotjar (Contentsquare) Copy Chapter

Hotjar no longer exists as a separate product. Contentsquare's Hotjar page says the two platforms "have merged into a single, more powerful experience intelligence platform", and hotjar.com/pricing now redirects to contentsquare.com/pricing. New signups get Contentsquare's Free, Growth, Pro and Enterprise plans.

Free gives 200,000 monthly sessions, unlimited heatmaps, basic funnels and error monitoring, on 1 project. The catch is that replay is a separate, fixed allowance of 10,000 captures a month, which the pricing page says "can't be increased". Growth starts at $49/month for 7,000 sessions and 7,000 replays and reaches $409/month at 100,000 sessions, but the replay cap tops out at 20,000 on every Growth tier. Growth keeps session data for 13 months and replays for 2 months; Contentsquare's free-plan post lists 1 month of retention on Free. Annual billing takes 20% off.

Privacy defaults carry over from Hotjar: keystrokes are suppressed by default and replaced with asterisks, and you add data-hj-allow to fields you want captured, per the Hotjar help center. Contentsquare describes Experience Analytics as covering "sites and mobile apps". There is no self-hosted edition.

• Pros: generous free session quota; heatmaps, surveys and replay together; 15-day Growth trial without a card
• Cons: replay allowance is fixed and small relative to sessions; 2-month replay retention on Growth; cloud only
• Pricing (as of September 2026): Free (200k sessions, 10k replays); Growth from $49/month. Source: contentsquare.com/pricing

For heatmaps and surveys as well as replay, see our Hotjar alternatives guide.

FullStory Copy Chapter

FullStory is the enterprise option: replay plus product analytics, funnels and retroactive data history. The paid tiers (Business, Advanced, Enterprise) have no published prices; each reads "Request pricing & demo" on the pricing page. Mobile analytics is an add-on on paid plans.

What is published is the free plan: FullstoryFree gives "30,000 sessions per month" with "12 months of data retention" for up to 10 users, no credit card required.

Privacy is chosen at setup from three modes: Full Capture, Form Privacy, and Private by Default, under which "no text is captured or sent outside the user's browser unless it is explicitly allowlisted as safe to capture".

• Pros: 30k free sessions with 12-month retention; strong privacy mode; mature enterprise analytics
• Cons: no public pricing above the free plan; cloud only; mobile is an add-on
• Pricing (as of September 2026): Free (30k sessions/month); paid plans by quote. Source: fullstory.com/pricing

For more options by use case, see our FullStory alternatives guide.

LogRocket Copy Chapter

LogRocket is replay for engineers. Recordings include console logs, network requests and exceptions, and the mobile SDKs cover Android, iOS, React Native, Flutter, Ionic and Expo. Analytics, error and log events are unlimited on every plan; you pay for sessions captured.

The pricing page calculator starts with a Free plan for 1,000 sessions a month, then Core at $83/month for 10,000 sessions and $176/month for 25,000; paid features also come with a 14-day trial. A Conditional Recording option captures roughly a quarter of sessions, and Pro features are "included free above 100K sessions/mo". Self-hosting is an Enterprise option for regulated industries.

On privacy, LogRocket's documentation states that password fields are never recorded; masking anything else uses a data-private attribute or the SDK's sanitizers, so the safe default is your responsibility.

• Pros: deep debugging context per session; broad mobile coverage; unlimited non-session events
• Cons: the Free plan stops at 1k sessions, and 25k sessions costs $176/month; masking beyond passwords is opt-in; self-host is Enterprise only
• Pricing (as of September 2026): Free for 1k sessions/month; Core from $83/month for 10k sessions; 14-day trial. Source: logrocket.com/pricing

PostHog Copy Chapter

PostHog bundles replay with product analytics, feature flags, experiments and surveys on usage-based pricing. The replay pricing page gives 5,000 web recordings and 2,500 mobile recordings free every month, no card required, then charges $0.0050 per web recording from 5k to 15k, falling to $0.0015 above 500k. Mobile recordings cost $0.0100 each on the first paid tier.

Retention follows your plan: up to 30 days free and up to 90 days on pay-as-you-go. Inputs are masked by default; page text isn't, and you mask it with maskTextSelector or maskTextFn.

The core is MIT-licensed with a one-command "hobby" Docker Compose deployment, but PostHog's self-host page calls self-hosted deployments "officially unsupported" and steers anyone expecting more than roughly 300k events or 1k recordings a month to PostHog Cloud. We compare the two products further in Rybbit vs PostHog.

• Pros: real free tier renewed monthly; replay next to funnels, flags and experiments; transparent volume pricing
• Cons: breadth brings complexity; self-hosting is unsupported and not meant for scale; page text unmasked by default
• Pricing (as of September 2026): 5,000 web recordings free per month, then from $0.005 per recording. Source: posthog.com/docs/session-replay/pricing

OpenReplay Copy Chapter

OpenReplay is the self-hosting purist's replay tool. The core is AGPL-3.0 (an ee/ directory carries a separate license, per the repository), and the pricing page says "Open-Source is free — you host it on your own infrastructure". It is aimed squarely at developers, with iOS and Android SDKs.

The cloud option is a single "Dedicated" plan: "Starting from $199/mo", billed hourly at $0.276, a dedicated VM in its own VPC "with no limits on users, recordings, or retention", with a 7-day trial and no card. Enterprise is custom.

Self-hosting asks for at least 2 vCPUs, 8 GB of RAM and 50 GB of storage per the Docker guide. Privacy defaults are good: inputs are obscured by default, emails are obscured in inputs and text, and the docs note that obscured data "will never leave the user's browser". Numbers in text are not obscured unless you turn that on.

• Pros: free open-source self-hosting with no recording limits; developer-grade context; strong default sanitization
• Cons: cloud starts at $199/month; needs an 8 GB server at minimum; no shared cloud tier for small sites
• Pricing (as of September 2026): self-hosted free; Dedicated cloud from $199/month. Source: openreplay.com/pricing.html

Lucky Orange Copy Chapter

Lucky Orange is a conversion-optimization bundle for small businesses: recordings, heatmaps, funnels, surveys and an AI layer it calls Discovery, with unlimited team members on every plan. Pricing is by monthly sessions: Build is $39/month, or $32/month paid annually, for 3,500 sessions; Grow is $72/month paid annually for 10,000; Expand is $199/month paid annually ($249 monthly) for 50,000; Scale is $839/month paid annually ($1,049 monthly) for 300,000; Enterprise starts at 700,000. Extra sites cost $5 each.

There is no free plan, only a 7-day trial with every feature. Base storage "starts at 60 days" with 90, 180 and 365-day upgrades. It is cloud only, and the pricing page doesn't mention native app recording.

• Pros: affordable entry price with everything included; unlimited seats; surveys in the same tool
• Cons: no free plan; 60-day base retention; large jump from the 50k to the 300k tier; cloud only
• Pricing (as of September 2026): from $39/month ($32 billed annually) for 3,500 sessions. Source: luckyorange.com/pricing

Mouseflow Copy Chapter

Mouseflow offers replay and heatmaps, plus friction scoring, form analytics and journey analysis on higher tiers. The pricing page is public and simple. Free is $0 for 500 sessions a month, 1 month of retention, 1 website. Essential is $25/month for 5,000 sessions and 3 months of retention. Advanced is $109/month for 25,000 sessions and 6 months. Premium is $319/month for 100,000 sessions and 12 months. Enterprise is custom. The page advertises up to 35% off for annual billing and a 14-day money-back guarantee, and all plans include unlimited users.

Privacy defaults are conservative; Mouseflow's help center says it does not record keystrokes by default, and you whitelist individual fields from the UI. It is cloud only, and the pricing page doesn't mention native app SDKs.

• Pros: clear public pricing; 12-month retention on Premium; keystrokes excluded by default
• Cons: the 500-session free plan is a demo, not a tier; cloud only; web only
• Pricing (as of September 2026): Free (500 sessions); Essential $25/month for 5,000 sessions. Source: mouseflow.com/pricing

Sentry Session Replay Copy Chapter

Sentry is error monitoring first, and its replay exists to show the seconds before an exception. The default setup in the JavaScript docs records 10% of sessions and 100% of sessions with an error, and replay is available for web plus Android, iOS, React Native and Flutter.

The free Developer plan (one user) and the paid Team ($26/month billed annually) and Business ($80/month billed annually) plans each include 50 replays a month on the pricing page. Beyond that you pay as you go; the pricing docs list Team replays at $0.00375 each up to 5k and $0.003563 each from 5k to 100k. Replays are retained for 30 days on Developer and 90 days on paid plans.

Defaults are the strictest here: maskAllText, maskAllInputs and blockAllMedia are all true out of the box, per the privacy docs. Self-hosting exists under the Functional Source License, needs at least 4 CPU cores and 16 GB of RAM per the self-hosted docs, and has included replay since release 23.3.1 according to the project's issue tracker.

• Pros: replay linked to the exact error; mask-everything defaults; sampling built in; self-hostable
• Cons: 50 included replays; per-replay costs add up; built for debugging errors rather than UX research
• Pricing (as of September 2026): Developer free (50 replays); Team $26/month billed annually plus $0.00375 per extra replay. Source: sentry.io/pricing

Which one should you pick Copy Chapter

• You want replay and web analytics in one privacy-first tool, or need to self-host without a giant server: Rybbit.
• You have no budget and can live with 30-day retention and a consent banner in Europe: Microsoft Clarity.
• You're a marketer who wants heatmaps, surveys and replay with a big free session quota: Hotjar / Contentsquare.
• Your engineers want console logs and network calls next to every recording: LogRocket, or Sentry Session Replay if you already use Sentry and only need replays for errored sessions.
• You want the widest product-analytics suite with a real free tier, and cloud hosting is fine: PostHog.
• Recordings must never leave your infrastructure and you have a spare 8 GB box: OpenReplay.
• You need 12 months of replay history at a published price: Mouseflow Premium, or FullStory's free plan if 30k sessions is enough.

One tool to skip: Smartlook. Its homepage now carries a Cisco end-of-life notice, with no new subscriptions since 31 May 2026, no renewals after 31 August 2026, and the platform decommissioned on 30 September 2027. If you already use Amplitude, its pricing page lists 10,000 replay sessions a month on the free plan with 1 month of retention.

For the analytics side of the decision, see our guides to the best web analytics tools and the best Google Analytics alternatives.

FAQ Copy Chapter

Is there a free session replay tool? Copy Section

Yes, several. Microsoft Clarity is free with no traffic limits. Contentsquare's Free plan includes 10,000 replay captures a month, PostHog gives 5,000 web recordings a month, LogRocket's Free plan covers 1,000 sessions a month, and FullStory's free plan covers 30,000 sessions with 12-month retention. Rybbit and OpenReplay are free if you self-host; Rybbit Cloud has a 7-day trial rather than a free tier.

Is session replay software the same as session recording software? Copy Section

Yes. Vendors use "session recording", "session replay" and "visitor recordings" for the same thing: capturing DOM changes and interactions in the browser and reconstructing them for playback.

Is session replay GDPR compliant? Copy Section

It can be, but your configuration makes it so, not the tool. Mask inputs and personal text before data leaves the browser, record only with a lawful basis, honor consent where you rely on it, keep retention short, and sign a processing agreement with the vendor. Self-hosting (Rybbit, OpenReplay, PostHog, Sentry) removes the vendor-transfer question entirely.

Which session replay tools are open source? Copy Section

Rybbit (AGPL-3.0), OpenReplay (AGPL-3.0 core with a separately licensed ee/ directory) and PostHog (MIT core) are open source and self-hostable. Sentry is source-available under the Functional Source License, which is not an OSI-approved open-source license.

Does session replay slow down a website? Copy Section

Modern tools record DOM mutations, not screenshots or video, and load their capture script asynchronously, so the effect on page load is small. Bandwidth on long, interaction-heavy sessions is the real cost, which is why tools offer sampling: Sentry defaults to 10% of sessions, and Rybbit's script attributes let you throttle mouse-move and scroll events and slim the recorded DOM.

Content Blog Best Web Analytics Tools (`docs/content/blog/best-web-analytics-tools.mdx`) Copy Section

title: "10 Best Web Analytics Tools in 2026, Compared by Use Case" keyword: "best web analytics tools" date: 2026-07-19 updated: 2026-09-28 tags: ["analytics", "tools", "comparisons"] author: Rybbit Team Copy Chapter

Every list of web analytics tools pretends there's one "best" answer. There isn't. A solo blogger checking referrers, a SaaS team debugging a signup funnel, and an EU retailer with a nervous legal department need genuinely different products.

So this guide is organized around the question that actually decides the purchase: what do you need your analytics to do? We build one of these tools (Rybbit), so we'll flag that bias where it matters. Every price and limit below comes from the vendor's own published pages, checked July 2026.

The short version Copy Chapter

How to choose a web analytics tool Copy Chapter

Four questions sort the whole market:

1. Traffic stats or behavior? Counting visits, referrers, and top pages is the easy half. Understanding behavior (funnels, session replay, user journeys, errors) is where tools diverge sharply. Simple trackers stop at the first half.
2. Cookies or cookieless? Cookie-based tools (GA4 chief among them) require consent banners in most of the world, and every declined banner is a visitor deleted from your data. Cookieless tools see everyone and need no banner.
3. Cloud or self-hosted? If analytics data legally can't leave your infrastructure, your shortlist is the open-source tools: Rybbit, Matomo, Plausible CE, Umami.
4. Who reads the dashboard? If the answer includes non-analysts, weight simplicity heavily. The most common analytics failure is a tool nobody opens, not missing data.

Rybbit Copy Chapter

The all-rounder: product-analytics depth on a dashboard anyone can read.

Most tools on this list force a choice between simple-but-shallow and deep-but-painful. Rybbit exists to refuse that choice: a single-page, real-time dashboard in the Plausible tradition, with funnels, session replay, user journeys, error tracking, Web Vitals, and user profiles built in. That feature set otherwise requires a PostHog-class suite. Tracking is cookieless (no consent banner, no lost visitors, no sampling), the whole platform is open source, and there's a live demo with real data you can click around right now.

Pricing: from $19/month for 100k events on Standard; session replay and unlimited sites come with Pro, from $39/month. 7-day trial. Self-hosting is free with Docker.
Skip it if: you need years of GA-style ad-attribution workflows, or feature flags and experiments in the same tool (that's PostHog territory).

Google Analytics 4 Copy Chapter

The default, and the tool everyone on this page is measured against.

GA4 is free, integrates natively with Google Ads, and exports raw events to BigQuery. For paid-acquisition teams inside Google's ecosystem, it remains genuinely hard to replace. It's on this list on merit.

But treat its price with suspicion: "free" is funded by your visitors' data feeding Google's ad network. The operational costs are consent banners (and the 30–60% of traffic they cost you), report sampling on busy properties, 14-month standard retention, and an interface that has made "how do I just see my top pages?" a support-forum genre. Unsampled data means GA360, at roughly $50,000/year. If those are your pain points, our detailed GA4 comparison breaks down the switch, or see the full guide to Google Analytics alternatives.

Plausible Copy Chapter

The standard-bearer for simple, privacy-first analytics.

One page of stats, a tiny script (their claim: ~54× smaller than GA's), cookieless by design, EU-owned and EU-hosted. Plausible proved a paid GA alternative could be a real business, and a decade of polish shows. Its scope is deliberately narrow (traffic analytics, goals, basic funnels), which is either its best feature or its dealbreaker depending on your needs. From $9/month (10k pageviews), 30-day no-card trial, free self-hosted Community Edition. Rybbit vs Plausible →

Matomo Copy Chapter

The open-source veteran with the largest feature list.

Heatmaps, A/B tests, a tag manager, hundreds of plugins, and a free on-premise edition with unlimited hits: Matomo (ex-Piwik) is what "we replaced Google Analytics" meant for a decade, and it's still the compliance-department favorite (cloud data lives in Frankfurt, no sampling). The cost is a dated interface and pricing complexity on-premise, where advanced features come in paid plugin bundles from €275. Cloud from €29/month for 50k hits; no-card trial. Rybbit vs Matomo →

For a head-to-head with GA4, see Matomo vs Google Analytics.

PostHog Copy Chapter

The product-analytics suite that swallowed web analytics.

PostHog bundles product analytics, session replay, feature flags, experiments, surveys, and a SQL-queryable event warehouse, with a web analytics dashboard on the side. For engineering-led product teams it's the most capable platform here, and the free tier is the market's most generous: 1M events every month, no card. Past that it's usage-based (from $0.00005/event), which needs monitoring at scale. The trade: GA4-class complexity, because it's solving a much bigger problem than "how's my traffic." Rybbit vs PostHog →

For the per-product rates and worked examples, see PostHog pricing, explained.

Fathom Analytics Copy Chapter

Simple stats from one of the original privacy-analytics companies.

Cookieless, one clean dashboard, forever data retention, and at least 50 sites on every plan. Fathom's pitch is stability: a profitable independent company that's been doing exactly this since before it was a category. Pricing is a pageview slider ($45/month at 500k pageviews; smaller tiers cost less), 7-day trial, no free tier, no self-hosting. Rybbit vs Fathom →

Umami Copy Chapter

Free, minimal, MIT-licensed: the developer's hobby-project default.

Umami is the easiest analytics tool to self-host (a small Node app), and its cloud Hobby plan is free forever, with Pro at $20/month for 1M events. Reporting is deliberately minimal (pageviews, referrers, events), and that's the point. If your need is "decent stats on my side projects for $0," this is the answer. Rybbit vs Umami →

Simple Analytics Copy Chapter

The most privacy-conservative option, made and hosted in the EU.

Simple Analytics collects the least data of any paid tool here and wears it proudly. In 2026 it's also carved out a clever niche: positioning itself as the fix for GA4's consent-loss problem (their number: GA can miss up to 60% of traffic). Free for hobby sites (5 sites, 1 month history); paid from $20/month per user with usage sliders; 14-day no-card trial. No self-hosting. Rybbit vs Simple Analytics →

Pirsch Copy Chapter

The lowest-cost paid entry in privacy analytics.

German-built, cookieless, with first-class server-side tracking SDKs and importers for GA, Plausible, and Fathom. $6/month buys 10k pageviews across up to 50 sites with unlimited team members and retention; $12/month adds funnels and A/B testing; 30-day no-card trial. Self-hosting exists but only behind the Enterprise tier. For tight budgets it's the best dollar-for-dollar deal on this list.

Cloudflare Web Analytics Copy Chapter

Free and instant, as long as you understand what it isn't.

If your site is behind Cloudflare, this is one toggle. It's cookieless and costs nothing, but Cloudflare's own docs note the dashboard is built on a ~10% sample of page-load events with roughly 30-day retention, and there are no goals, events, or funnels. Use it as a free second opinion, not as your analytics.

What we'd actually do Copy Chapter

• Under 10k visits a month and a $0 budget: Umami's free cloud tier, or self-host if you enjoy it.
• A business site where decisions ride on the data: Rybbit. You'll use the funnels and replay within the first week, and cookieless tracking means the numbers are actually complete.
• A content site that just needs clean traffic stats: Plausible or Fathom. Pirsch if price wins.
• An engineering-led product team: PostHog, or Rybbit if you want your PMs and marketers to actually open the dashboard.
• A regulated or self-host-only environment: Rybbit or Matomo, both free to run on your own infrastructure.

FAQ Copy Chapter

What's the difference between web analytics and product analytics?
Web analytics answers traffic questions (visitors, sources, pages); product analytics answers behavior questions (activation, retention, funnels) usually tied to identified users. GA4 and PostHog are product-analytics tools wearing web-analytics clothes; Plausible and Fathom are pure web analytics; Rybbit deliberately covers both sides for websites and apps.

Are free web analytics tools good enough?
Often, yes. Umami and PostHog's free tiers are real products, and self-hosting an open-source tool costs only your server. The free options to be wary of are the ones with invisible costs: GA4 (consent loss, complexity, your users' data) and Cloudflare (sampling, 30-day window).

Can I run two analytics tools at once?
Yes, and during any migration you should. Scripts from different vendors don't conflict, and a few weeks of parallel data is the only honest way to compare them. It's also the standard way to leave Google Analytics without losing your bearings.

Do cookieless analytics tools comply with GDPR?
The cookieless tools here (Rybbit, Plausible, Fathom, Umami, Simple Analytics, Pirsch) are built to run without consent banners: no cookies, no cross-site identifiers, no personal profiles. Self-hosting adds the strongest guarantee, since data never touches a third party at all.

Want the deep version of any matchup? Every comparison above links to a feature-by-feature breakdown, or start with Rybbit vs Google Analytics, the switch most teams are weighing.

Content Blog Bounce Rate (`docs/content/blog/bounce-rate.mdx`) Copy Section

title: "What Is Bounce Rate? How to Calculate and Reduce It" keyword: "bounce rate" date: 2025-11-21 updated: 2026-09-28 tags: ['analytics', 'metrics'] author: Rybbit Team Copy Chapter

Bounce rate measures the percentage of visitors who leave your site after viewing only one page. For anyone running a website, this number matters, it shows whether people find what they're looking for or bail immediately. Rybbit makes tracking bounce rate simple, and I'll walk you through everything you need to know.

Understanding Bounce Rate Copy Chapter

A bounce happens when someone lands on your site and leaves without clicking anywhere else. That's it. The bounce rate is just the percentage of these single-page sessions compared to total sessions (the bounce rate calculator does the division for you). To understand bounce rate in the broader context of web analytics, it's one of the most fundamental metrics you'll track.

High bounce rates aren't always terrible. Someone might read your entire 2,000-word guide, get their answer, and close the tab feeling satisfied. But if users hit your homepage and immediately leave? That signals a real problem.

Accessing Your Bounce Rate Data Copy Chapter

Once you've added the Rybbit tracking script (takes about five minutes), bounce rate data appears immediately in your dashboard.

Dashboard Access Copy Section

Log into app.rybbit.io and select your website from the list.

Main Metrics View Copy Section

Your bounce rate sits right on the main dashboard next to:

• Unique Users
• Sessions (see our sessions guide for deeper analysis)
• Pageviews
• Pages Per Session
• Session Duration

The interface stays clean and simple. No digging through buried menus for your key numbers are front and center.

The Math Behind Bounce Rate Copy Chapter

Rybbit calculates bounce rate with this formula:

Bounce Rate = (Single-Page Sessions ÷ Total Sessions) × 100

Real example: You had 1,000 sessions yesterday. 350 were single-page visits. Your bounce rate: 35%.

For more on session behavior and user engagement patterns, see our Sessions Tab Guide, Churn Rate vs Retention Rate article, and Website Traffic Drop Analysis.

Segmenting Your Data Copy Chapter

Rybbit's filtering capabilities let you dig into the "why" behind your bounce rate numbers.

Traffic Source Comparison Copy Section

Click "Referrer" or "UTM Source" to compare channels:

• Organic Search: Your SEO pages converting?
• Social Media: How do Twitter, LinkedIn, and Facebook visitors behave?
• Direct Traffic: Performance from bookmarks and typed URLs
• Paid Campaigns: Getting ROI from paid traffic?

Device Breakdown Copy Section

Mobile users behave differently than desktop users. Filter by device type:

• Desktop
• Mobile

If mobile bounce rates run significantly higher, your mobile experience needs work.

Geographic Patterns Copy Section

The Location Filter shows bounce rates by country, region, and city. Useful for spotting regional issues or informing localization choices.

Advanced Filtering Options Copy Section

Rybbit offers 15+ dimensions for detailed segmentation:

• Browser and Browser Version
• Operating System
• Screen Resolution
• Language
• UTM parameters (Campaign, Medium, Term, Content)

You can easily select the right filter at the top of the page of your main dashboard

Real-Time Monitoring Copy Chapter

Rybbit shows bounce rate changes as they happen. This matters during:

• Campaign launches
• New content releases
• A/B tests
• Site updates

Historical Trend Analysis Copy Chapter

Looking at bounce rate over time reveals patterns and shows whether your optimizations work.

Time Range Selection Copy Section

Pick your date range from the top of your dashboard:

• Today
• Yesterday
• Last 7 days
• Last 30 days
• Last 90 days
• Custom date range

Pattern Recognition Copy Section

The bounce rate graph shows you what's happening over time. Watch for:

• Spikes: Something caused a sudden jump—what was it?
• Declines: Did your recent changes help?
• Weekly rhythms: Certain days consistently different?
• Seasonal shifts: How does time of year affect behavior?

Setting Up a Funnel Copy Section

1. Navigate to Funnels
2. Click "Create Funnel"
3. Map your steps (Landing Page → Product Page → Cart → Checkout)
4. Analyze drop-off rates

Your first step drop-off equals your bounce rate for that entry point. For a comprehensive guide on using funnels to measure conversions, see our sales funnel measurement guide.

Core Web Vitals Monitoring Copy Chapter

Page performance impacts bounce rate. Rybbit automatically measures Core Web Vitals:

• LCP (Largest Contentful Paint): How fast the main content loads
• FID (First Input Delay): How quickly the page responds to interactions
• CLS (Cumulative Layout Shift): Visual stability during loading

Poor scores here often match high bounce rates.

Actionable Ways to Reduce Bounce Rate Copy Chapter

Now that you know how to track bounce rate, here's how to improve it:

1. Improve Load Speed Copy Section

Check Web Vitals data, find slow pages, fix them.

2. Align Content with Expectations Copy Section

Review referrer data, do landing pages deliver what traffic sources promise?

3. Optimize Mobile Experience Copy Section

High mobile bounce rates mean your mobile site needs attention now. If you need to understand how different devices are performing, check out our e-commerce analytics guide which covers device-specific optimization.

4. Clarify Next Steps Copy Section

Watch session replays to see if users understand where to go next. Session replays are invaluable for understanding user behavior patterns that metrics alone can't reveal.

5. Match Content to Headlines Copy Section

Blog posts with high bounces often fail to deliver what titles promise.

6. Fix Technical Issues Copy Section

Session replays expose broken elements, confusing navigation, error messages. If you're seeing sudden bounce rate spikes, consult our website traffic drop analysis guide to diagnose what went wrong.

7. Improve Audience Targeting Copy Section

Use UTM tracking to measure campaign-level bounce rates and adjust targeting. Understanding how different traffic sources perform helps you optimize your acquisition strategy.

Comparing Rybbit to Alternatives Copy Chapter

Switching from Google Analytics, Plausible, or Umami? Key differences:

• Content-friendly: Long-form content doesn't get unfairly penalized
• Complete data: No sampling—you see every session
• Instant updates: Real-time data without processing delays
• Privacy-first: No cookies required, no consent banners needed

Support Resources Copy Chapter

Need help with bounce rate or other Rybbit features?

• Documentation: rybbit.com/docs
• Discord Community: Join other Rybbit Users at discord.gg/DEhGb4hYBj
• Twitter/X: Reach out to @yang_frog
• GitHub: github.com/rybbit-io/rybbit

Final Thoughts Copy Chapter

Bounce rate reveals a lot about user engagement. Rybbit makes the data accessible and actionable. Real-time tracking, session replays, detailed filters, and privacy-focused analytics give you everything needed to convert insights into improvements.

What works:

1. Regular monitoring: Check bounce rate trends each week
2. Deep segmentation: Examine sources, devices, and pages—not just overall numbers
3. Session replay review: Watch real user behavior to understand the story
4. Change testing: Implement improvements and measure results
5. Privacy respect: Get accurate data without invasive tracking

Ready to start? Start a free trial or explore the live demo featuring a real site handling millions of events annually.

Additional Resources:

• Getting Started with Rybbit Analytics
• Self-Hosting Guide
• Tracking Custom Events
• Framework Integration Guides (React, Next.js, Vue, plus 20+ frameworks)
• Ecommerce Analytics: The Metrics and Reports That Matter
• What Is Web Analytics? A Complete Guide
• Funnel Analysis: How to Find Where Users Drop Off

Content Blog Core Web Vitals (`docs/content/blog/core-web-vitals.mdx`) Copy Section

title: "Core Web Vitals Explained: LCP, INP, CLS and How to Fix Them" keyword: "core web vitals" date: 2026-09-13 tags: ["web vitals", "performance", "seo"] author: Rybbit Team Copy Chapter

Core Web Vitals are three metrics Google uses to judge how a page feels to real visitors: how quickly the main content shows up, how fast the page reacts when someone clicks or taps, and how much the layout jumps around while it loads. Google scores them from real Chrome visits at the 75th percentile, and a page passes when all three are in the "good" range.

The three metrics and the thresholds Google publishes on web.dev:

All three are evaluated at the 75th percentile of page loads, segmented by mobile and desktop: at least three out of four visits have to be good before the page counts as good.

INP is the newest of the three. It replaced First Input Delay (FID) on March 12, 2024, and FID was removed from Search Console the same day. Any guide that still talks about FID is out of date.

The three Core Web Vitals metrics, and how to fix each one Copy Chapter

Largest Contentful Paint (LCP) Copy Section

LCP is the time from the start of navigation until the largest visible element has rendered: an img element, an image inside an inline SVG, a video poster frame, an element with a CSS background image, or a block of text (web.dev). It is a proxy for "when did the page look loaded".

Common causes of a poor LCP:

• Slow server response. Nothing else can start until the HTML arrives.
• The LCP image is discovered late. It is a CSS background-image, injected by JavaScript, or lazy-loaded.
• Render-blocking CSS and synchronous scripts in the <head>.
• Oversized images in old formats, served at desktop size to phones.

Citing the 2024 Web Almanac, web.dev notes that 73% of mobile pages have an image as their LCP element, and 35% of those images had source URLs that were not discoverable in the initial HTML response.

Fixes that usually work, from web.dev's Optimize LCP guide:

• Put the LCP image in the HTML as a plain img element with a src, and add fetchpriority="high". The guide is blunt: "Never lazy-load your LCP image."
• If the hero must be a CSS background image, preload it with <link rel="preload">.
• Cut time to first byte: a CDN in front of the HTML, a proper cache-control policy, no redirect chains.
• Compress images, use modern formats, serve responsive sizes.
• Keep synchronous scripts out of the <head>; web.dev calls it "almost never necessary". Use defer or async, and defer non-critical CSS.

Interaction to Next Paint (INP) Copy Section

INP measures responsiveness. It observes every click, tap and key press during a visit and reports the slowest one: the time from the input until the next frame is painted. Hovering and scrolling do not count, and on pages with many interactions one outlier is ignored per 50 (web.dev).

Common causes:

• Long tasks. Anything that holds the main thread for more than 50 milliseconds is a long task, and while it runs the browser blocks interactions (web.dev).
• Too much JavaScript. Bundles, tag managers, chat widgets and A/B testing scripts all compete for one thread.
• Large DOMs. Rendering work scales with DOM size.

Fixes, from web.dev's Optimize INP guide:

• Break up long tasks. Yield to the main thread with scheduler.yield() or setTimeout() so input can be handled between chunks.
• Ship less JavaScript: code-split, drop unused code, audit every third-party tag.
• In handlers, paint first and defer the rest: requestAnimationFrame() followed by setTimeout().
• Keep the DOM small and avoid reading layout right after writing styles.

Cumulative Layout Shift (CLS) Copy Section

CLS measures how much visible content moves unexpectedly. Each shift is scored by how much of the viewport moved and how far, shifts that happen close together are grouped into a session window, and CLS is the largest window's total (web.dev). Shifts within 500 ms of a user input are excluded, so an accordion expanding on click does not count.

Common causes:

• Images and videos without dimensions, so the browser cannot reserve space.
• Ads, embeds and iframes that arrive late and push everything down.
• Content injected above existing content: cookie banners, notification bars.
• Web fonts that render larger or smaller than the fallback font.
• Animations that use layout properties like top and left.

web.dev reports that 66% of pages have at least one unsized image.

Fixes, from web.dev's Optimize CLS guide:

• Always set width and height attributes on img and video elements, or use CSS aspect-ratio.
• Reserve space for ads and embeds with min-height, and do not collapse the slot if no ad is returned.
• Do not insert content above the fold unless the user asked for it. Use an overlay for banners.
• Preload critical fonts, use font-display: optional where the design allows, and use size-adjust so the fallback font takes the same space.
• Animate with transform instead of layout properties.

Lab data vs field data Copy Chapter

Lab data is collected in a controlled environment with predefined device and network settings: one device, one network, one location. Field data, also called real user monitoring (RUM), comes from the people actually visiting your site, and it is a distribution rather than a single number (web.dev).

Lighthouse and a DevTools trace are lab tools. The Chrome User Experience Report (CrUX) is Google's field dataset and feeds both PageSpeed Insights and Search Console; your own real-user monitoring is field data too.

Google's assessment is based on field data; lab data is for diagnosis. A page can pass in the lab and fail in the field because:

• Viewports differ. A desktop test measures the hero image; on a phone the largest element may be a text block waiting on a web font.
• Devices differ. A lab run is a cold load on fast hardware; real visits include mid-range Android phones on cellular connections far from your server.
• The lab has no interactions. INP is missing entirely, and field CLS includes shifts from scrolling into lazy-loaded content.

There is also a coverage gap. CrUX only includes Chrome users who opted in to usage statistics reporting and history sync, on desktop and Android; Chrome on iOS, WebViews and other Chromium browsers do not contribute, and a page has to be publicly discoverable and "sufficiently popular" to appear at all (CrUX methodology).

Do Core Web Vitals affect rankings? Copy Chapter

Yes, but by less than most performance vendors imply. Google's page experience documentation states: "Core Web Vitals are used by our ranking systems." It also says, "There is no single signal. Our core ranking systems look at a variety of signals that align with overall page experience," and: "Google Search always seeks to show the most relevant content, even if the page experience is sub-par."

Read that as: relevance comes first, and Core Web Vitals help at the margin between comparable pages. They matter more directly for people: a page that takes four seconds to show anything loses visitors first, and that shows up in your bounce rate. When you investigate a drop in organic traffic, rule out a Core Web Vitals regression, but it is rarely the whole story.

How to measure Core Web Vitals Copy Chapter

PageSpeed Insights Copy Section

Enter a URL and you get CrUX field data for the previous 28 days plus a fresh Lighthouse lab run (PSI docs). When a URL lacks field data of its own, PSI falls back to origin-level data and says so.

Rybbit's Core Web Vitals checker runs the same PageSpeed Insights test for any public URL, mobile or desktop, and puts the 75th-percentile field metrics next to the Lighthouse lab metrics and largest opportunities.

Search Console's Core Web Vitals report Copy Section

The Core Web Vitals report groups your indexed URLs by status (Poor, Needs improvement, Good), metric and URL group, with separate mobile and desktop views. Two things trip people up: URL groups without enough LCP and CLS data are omitted, and only indexed URLs appear.

Chrome DevTools Copy Section

The Performance panel shows local LCP and CLS as soon as you open it, INP once you interact, and the CrUX field data for the URL alongside them (DevTools docs). Record a trace with CPU and network throttling to find the long tasks behind a bad INP.

Real-user monitoring Copy Section

Everything above is a snapshot or a 28-day aggregate of popular pages. Real-user monitoring gives you field numbers for every page, continuously; the web-vitals JavaScript library web.dev recommends is what Rybbit's tracking script uses.

Rybbit's Web Vitals report is real-user monitoring built into the analytics you already run. Enable Web Vitals in your site settings and the Performance tab starts collecting LCP, INP and CLS from your visitors, plus First Contentful Paint and Time to First Byte.

Each metric is graded against the same thresholds Google uses. A percentile selector switches between p50, p75, p90 and p99, each card shows the change from the previous period, and the breakdowns split every metric by page, device, browser, operating system and country. That is usually how the cause shows up: LCP is fine on desktop but poor on mobile, or fine everywhere except one region.

To make the business case, the page speed calculator turns current and target load times, monthly visitors, conversion rate and order value into an estimated revenue figure.

"Core Web Vitals assessment: Failed" and what to do first Copy Chapter

PageSpeed Insights passes a page only when the 75th percentiles of LCP, INP and CLS are all good over the last 28 days of CrUX data; with too little INP data it passes on LCP and CLS alone (PSI docs). "Failed" means at least one metric's 75th percentile is in the needs improvement or poor range. What to do, in order:

1. Check what the verdict covers. PSI says whether it is showing this URL or the whole origin; an origin-level failure is about the site, not the page.
2. Find the failing metric and device. It is usually one metric, and usually mobile.
3. Check the blast radius in Search Console. One failing URL group is one template; most groups failing is something shared, like hosting or a tag manager.
4. Reproduce it in the lab. Lighthouse for LCP and CLS; a throttled DevTools trace for INP.
5. Fix, deploy, then watch the field. CrUX is a trailing 28-day window, so PSI and Search Console reflect the fix slowly. Real-user monitoring shows it the same day.
6. Validate in Search Console. Start Tracking opens a 28-day monitoring session; if the issue does not reappear, it is marked fixed.

Core Web Vitals on WordPress Copy Chapter

WordPress sites fail for predictable reasons: a heavy theme, too many plugins, unoptimized images, and scripts that plugins inject into the <head>. Sliders, page builders and font loaders hurt LCP; ad and embed plugins that do not reserve space cause CLS; a stack of plugins each adding JavaScript is where poor INP comes from.

The fixes are the ones WordPress's own performance documentation recommends: a lightweight theme ("a fast lightweight theme will perform much more efficiently than a heavy graphic-laden inefficient one"), deactivating and deleting plugins you do not need, optimizing images and considering WebP, a caching plugin, a CDN, a current PHP version, and minified CSS and JavaScript.

WordPress core also helps with LCP. Since 6.3 it adds fetchpriority="high" to the image it determines is most likely the LCP image and omits loading="lazy" from the first few images on the page. That only covers images rendered through WordPress's own functions: a hero set as a CSS background image, or a slider that injects images with JavaScript, gets none of it, and a plugin that lazy-loads everything can undo it. Check the rendered HTML of your slowest template.

Search Console's URL groups usually map to templates, so fixing one template moves a whole group.

Monitor Core Web Vitals over time Copy Chapter

A one-off test is a single load on a single device on a single day. Sites change constantly: a new plugin, a new ad partner, a redesigned hero, a tag pasted into the tag manager. Any of them can push p75 LCP from 2.3 to 3 seconds, and a Lighthouse score from March will not tell you.

CrUX is a trailing 28-day window, so a regression deployed on Monday takes weeks to fully show in PageSpeed Insights and Search Console, and never shows for pages below CrUX's popularity threshold.

Real-user monitoring closes that gap. Track p75 per page, compare the week after a deploy with the week before, and treat a metric crossing from good to needs improvement as a bug. In Rybbit, the trend chart and the previous-period comparison make a regression visible quickly, and the breakdowns show whether it hit everyone or only one device, country or page.

FAQ Copy Chapter

What is a good Core Web Vitals score? Copy Section

A page is good when its 75th-percentile LCP is 2.5 seconds or less, INP 200 milliseconds or less, and CLS 0.1 or less, measured separately for mobile and desktop. Needs improvement runs up to 4 seconds, 500 milliseconds and 0.25; above that is poor. There is no combined score; the Lighthouse performance score is a lab number.

Do Core Web Vitals affect SEO? Copy Section

Yes. Google says Core Web Vitals are used by its ranking systems, and in the same breath that there is no single page experience signal and that it always seeks to show the most relevant content. Treat them as a tie-breaker and a user experience requirement, not a way to outrank better content.

How often are Core Web Vitals updated? Copy Section

PageSpeed Insights and Search Console report field data over the previous 28 days, so a change takes up to four weeks to be fully reflected. The metrics themselves change rarely: web.dev states that "developers should expect the definitions and thresholds of the Core Web Vitals to be stable, and updates to have prior notice and a predictable, annual cadence."

What replaced FID? Copy Section

Interaction to Next Paint (INP) replaced First Input Delay (FID) on March 12, 2024. FID only measured the delay before the first interaction's handler started; INP measures the full time to the next paint for every interaction, which is why pages that passed FID can fail INP.

Why does my page pass in Lighthouse but fail the Core Web Vitals assessment? Copy Section

Lighthouse is one simulated load on one device and cannot measure INP at all. The assessment is 28 days of real Chrome visits at the 75th percentile across every device and network your visitors use. Use field data to decide whether there is a problem, the lab to find the cause, and your own real-user monitoring to confirm the fix landed.

Content Blog Ecommerce Analytics (`docs/content/blog/ecommerce-analytics.mdx`) Copy Section

title: "Ecommerce Analytics: The Metrics and Reports That Matter" date: 2025-11-22 updated: 2026-09-28 keyword: "ecommerce analytics" tags: ["analytics", "ecommerce", "conversion"] author: Rybbit Team Copy Chapter

If you run an e-commerce website, understanding your customer behavior and sales funnel is crucial for growth. Whether you're running a small online store or a large marketplace, having the right analytics in place can mean the difference between scaling successfully and struggling to understand why your sales are declining.

E-commerce analytics are a specialized application of web analytics, focused specifically on understanding purchase behavior, conversion rates, and customer journeys through your store.

This is where Rybbit Analytics comes in. Unlike traditional analytics platforms that overwhelm you with data you don't need, Rybbit gives you actionable insights into your e-commerce metrics while respecting your customers' privacy and keeping your data under your control.

Why E-commerce Sites Need Better Analytics Copy Chapter

Most e-commerce platforms come with basic built-in analytics, but they're often limited in scope. You might see how many people visited your product pages, but can you easily answer these critical questions:

• Which marketing channels are actually driving purchases, not just traffic?
• What's the conversion rate for mobile vs desktop users?
• Are customers from certain countries more likely to complete a purchase?
• Which product pages have high traffic but low conversion rates?
• How is your site's performance affecting your sales?
• What's the customer journey from landing to checkout?

Traditional analytics tools like Google Analytics can answer some of these questions, but they come with significant downsides: complex setup, privacy concerns, cookie consent banners, data ownership issues, and an overwhelming interface that requires training to navigate effectively.

What Makes Rybbit Different for E-commerce Copy Chapter

Rybbit is built from the ground up to be simple, privacy-focused, and actionable. Here's what that means for your e-commerce business:

No Cookie Consent Banners Required - Rybbit doesn't use cookies, which means you don't need those annoying cookie banners that hurt your conversion rates. Your checkout flow stays clean and simple.

Lightning Fast - The Rybbit script is designed to be lightweight and minimize performance impact on your product pages and checkout process. Load time matters for e-commerce conversions.

You Own Your Data - With the self-hosted option, all your customer data stays on your servers. No third-party access, no data sharing, complete control.

Simple, Actionable Metrics - Rybbit focuses on the metrics that actually matter for e-commerce, without drowning you in vanity metrics.

Setting Up Rybbit for Your E-commerce Site Copy Chapter

Getting started with Rybbit is straightforward. You can either use the hosted version or self-host it (which many e-commerce businesses prefer for data sovereignty).

Installation Copy Section

Add the Rybbit tracking script to your site's header. For most e-commerce platforms, this goes in your theme's template file. Refer to the official Rybbit documentation for the correct installation steps.

That's it. No complex configuration, no tag managers required, no cookies to configure.

Tracking E-commerce Events Copy Section

While Rybbit automatically tracks page views, you'll want to track key e-commerce events like:

• Product views
• Add to cart
• Checkout initiated
• Purchase completed

See the Rybbit event tracking documentation for specific implementation details on how to track these events properly for your platform.

Key Metrics for E-commerce Success Copy Chapter

1. Traffic Sources and Quality Copy Section

Understanding where your traffic comes from is table stakes, but Rybbit makes it easy to see which sources actually convert.

Using Rybbit's channel filter, you can quickly see traffic from:

• Organic search
• Paid advertising
• Social media
• Email campaigns
• Direct traffic
• Referrals

But more importantly, you can combine this with your purchase events to see which channels drive actual revenue, not just visits. This helps you allocate your marketing budget more effectively.

2. Geographic Performance Copy Section

If you're selling internationally, geographic data is crucial. Rybbit makes it easy to analyze performance by country.

You can use geographic filtering to:

• Identify high-converting markets worth investing in
• Spot countries with high traffic but low conversion (maybe you need better shipping options or payment methods)
• Optimize your ad spend by focusing on profitable regions
• Plan inventory and shipping logistics based on where your customers are

3. Device and Platform Analysis Copy Section

E-commerce conversion rates often vary significantly between desktop and mobile. Rybbit lets you filter by device type to understand these differences.

Common insights you might discover:

• Mobile traffic is high but conversion is low → your mobile checkout might need work
• Tablet users have higher average order values → consider tablet-specific promotions
• Desktop users browse more pages before purchasing → optimize your navigation for desktop

4. Page Performance Analysis Copy Section

Page speed directly impacts e-commerce conversions.

Rybbit's performance tab shows you the Largest Contentful Paint (LCP) for each page. If your product pages or checkout pages have poor performance metrics, you should optimize them. The performance dashboard makes it easy to identify which pages need optimization.

What to look for:

• Product pages with high traffic but slow load times → optimize images, reduce scripts
• Checkout pages with performance issues → this is costing you direct sales
• Category pages that load slowly → customers will bounce before seeing your products

5. Conversion Funnel Insights Copy Section

One of the most powerful uses of Rybbit for e-commerce is tracking your conversion funnel. Similar to how content marketing funnels work for awareness and consideration stages, your e-commerce funnel tracks the path from product discovery to purchase. Using the pages tab, you can see the customer journey:

The embedded graphs make it easy to spot where customers are dropping off:

• High traffic to product pages but low "add to cart" pages → product pages need better CTAs
• Many add to cart events but few checkout initiations → shipping costs revealed too late?
• Checkout started but not completed → payment issues or complicated forms?

6. Time-Based Patterns Copy Section

Understanding when your customers shop helps you optimize promotions and advertising.

Using Rybbit's date range filters, you can:

• Compare this month vs last month to track growth
• Identify seasonal patterns in your business
• See if your recent marketing campaigns are working
• Spot unusual drops or spikes that need investigation

7. Referrer Analysis Copy Section

Beyond broad traffic sources, Rybbit lets you drill down into specific referrers to see exactly which sites, influencers, or affiliate partners are driving traffic.

This is especially valuable for:

• Affiliate programs - see which affiliates drive the most valuable traffic
• Influencer marketing - track which influencers actually drive sales
• Content marketing - identify which guest posts or mentions are worth pursuing
• Partner relationships - measure the value of co-marketing efforts

Real-World E-commerce Scenarios Copy Chapter

Scenario 1: Optimizing Marketing Spend Copy Section

When analyzing which traffic sources drive actual revenue (not just clicks), you can make more informed decisions about how to allocate your marketing budget. Using Rybbit's channel filtering combined with conversion tracking helps you see which acquisition channels produce the highest-quality users.

Scenario 2: Fixing Mobile Conversion Issues Copy Section

If you notice that mobile users make up a large portion of your traffic but a smaller portion of your conversions, Rybbit's device filtering helps you identify where the problem is. Common issues include:

• Checkout experience problems on mobile
• Performance issues on mobile devices
• Form complexity or navigation problems on small screens

By identifying where mobile users drop off, you can prioritize fixes to improve mobile conversion rates.

Scenario 3: International Expansion Copy Section

Using Rybbit's geographic filtering, you can see which countries or regions show strong engagement and conversion patterns. This helps you:

• Identify markets worth investing in
• Spot countries with traffic but low conversion (signaling a potential need for localization)
• Prioritize international optimizations based on data, not assumptions

Scenario 4: Product Page Optimization Copy Section

By analyzing individual product pages with Rybbit, you can identify patterns:

• Which pages get high traffic but have poor conversion rates
• What content attributes correlate with higher conversions (detailed descriptions, multiple images, videos, etc.)
• Which optimization efforts have the most impact

For a comprehensive guide on understanding your entire purchase journey, see our sales funnel guide, which covers how to track and optimize all stages from awareness to purchase.

Privacy and E-commerce: Why It Matters Copy Chapter

E-commerce businesses collect sensitive customer data - names, addresses, payment information. Using privacy-respecting analytics like Rybbit sends a positive signal to customers:

No Data Sharing - Customer behavior data stays with you, never sold to advertisers

GDPR and Privacy Compliant - Rybbit is built to respect privacy laws by default

No Cookie Banners - Better user experience means better conversion rates

Build Trust - Privacy-conscious customers appreciate businesses that respect their data

In an era where data breaches make headlines regularly, being able to tell your customers that you use privacy-first analytics is a competitive advantage.

Comparing Rybbit to Other E-commerce Analytics Copy Chapter

vs. Google Analytics Copy Section

Google Analytics:

• Requires complex e-commerce tracking setup
• Needs cookie consent banners
• Data belongs to Google
• Overwhelming interface with hundreds of metrics
• Slower script impacts page speed

Rybbit:

• Simple event tracking
• No cookie banners needed
• You own all data
• Focused on actionable metrics
• Minimal performance impact

vs. Platform Built-in Analytics (Shopify, WooCommerce, etc.) Copy Section

Built-in Analytics:

• Limited to basic metrics
• Can't easily track custom events
• Limited filtering and segmentation
• No performance metrics
• No data portability

Rybbit:

• Comprehensive yet simple analytics
• Custom event tracking
• Powerful filtering and segmentation
• Built-in performance monitoring
• Self-hostable with full data control

Advanced E-commerce Tracking with Rybbit Copy Chapter

For more detailed tracking beyond page views, refer to the Rybbit event tracking documentation for implementation guidance on:

Customer Lifetime Value (CLV) Tracking Copy Section

Track repeat purchases to understand customer lifetime value. The documentation covers best practices for tracking first-time purchases and repeat customer behavior.

Cart Abandonment Analysis Copy Section

Track the checkout flow to identify where customers are abandoning carts. By measuring events at key steps (add to cart, checkout started, purchase completed), you can calculate your cart abandonment rate and work to reduce it.

Product Category Performance Copy Section

Track which product categories perform best by recording category and product information when users interact with products. This helps you understand which categories drive the most engagement and sales.

Getting Started with Rybbit for Your E-commerce Store Copy Chapter

1. Sign up or self-host - Choose between the hosted version for convenience or self-hosting for complete data control

2. Add the script - Install the Rybbit tracking script on your e-commerce site (works with any platform)

3. Set up event tracking - Add events for your key conversion points (add to cart, checkout, purchase)

4. Define your metrics - Decide what success looks like for your business and set up your Rybbit dashboard accordingly

5. Start analyzing - Use the filtering and segmentation features to understand your customer behavior

6. Optimize and iterate - Use insights from Rybbit to make data-driven decisions about your store

Best Practices for E-commerce Analytics with Rybbit Copy Chapter

Track What Matters - Don't track everything, focus on metrics that drive business decisions

Segment Your Analysis - Use filters to understand different customer segments, devices, and channels

Compare Time Periods - Always look at trends over time, not just individual snapshots

Combine with Other Data - Rybbit analytics work best when combined with your e-commerce platform's sales data

Act on Insights - Analytics are only valuable if you use them to make changes

Monitor Performance - Keep an eye on page performance metrics - they directly impact conversion

Review Regularly - Set aside time weekly or monthly to review your analytics and spot trends

Conclusion Copy Chapter

Running a successful e-commerce business requires understanding your customers, your traffic, and your conversion funnel. Rybbit Analytics provides all the tools you need to make data-driven decisions without the complexity, privacy concerns, or performance impact of traditional analytics platforms.

Whether you're just starting out with a small online store or scaling a multi-million dollar e-commerce business, Rybbit gives you the insights you need to grow - in a simple, privacy-respecting package that your customers will appreciate.

The combination of Rybbit's clean interface, powerful filtering capabilities, performance monitoring, and privacy-first approach makes it the ideal analytics solution for modern e-commerce businesses. And with both hosted and self-hosted options, you can choose the setup that best fits your needs.

Ready to get better insights into your e-commerce business? Give Rybbit a try and see how much clearer your data becomes when you focus on what actually matters.

Related Reading:

• What Is Bounce Rate? How to Calculate and Reduce It
• Retention Analysis: How to Measure and Improve User Retention
• Why Did My Website Traffic Drop?
• Funnel Analysis: How to Find Where Users Drop Off
• What Is Web Analytics? A Complete Guide
• Behavior Analytics - Sessions
• Behavior Analytics - Events
• Behavior Analytics - Users
• Track Custom Events
• Product Analytics - Funnels
• Getting Started with Rybbit

Content Blog Fullstory Alternatives (`docs/content/blog/fullstory-alternatives.mdx`) Copy Section

title: "Best FullStory Alternatives in 2026: 11 Tools by Use Case" keyword: "fullstory alternatives" date: 2026-09-27 tags: ["session replay", "comparisons", "product analytics"] author: Rybbit Team Copy Chapter

FullStory is an enterprise digital experience platform: session replay, heatmaps, frustration signals and product analytics, bought through a sales conversation because none of its paid plans has a public price. Which of the FullStory alternatives fits depends on why you're leaving. For the same enterprise depth from another vendor, look at Contentsquare and Quantum Metric. If your engineers mainly use replay to debug, look at LogRocket, Sentry and OpenReplay. Product teams that want analytics with replay attached should compare PostHog, Amplitude and Heap. Microsoft Clarity and Mouseflow cover small budgets, and OpenReplay and Rybbit let you keep recordings on your own servers.

Disclosure up front: we build Rybbit, one of the eleven tools below. Every claim about FullStory and the other ten tools comes from that vendor's own pricing or documentation pages, linked inline and checked in September 2026. Where a vendor doesn't publish a number, we say so rather than guess.

FullStory alternatives at a glance Copy Chapter

"No" in the self-host column means the vendor's pricing and documentation pages we checked list no self-hosted or on-premises option. A dash in the other columns means those pages don't list the feature. If you only need replay, not FullStory's analytics, our session replay tools comparison goes deeper on replay pricing, masking defaults and retention, and what is session replay covers the basics.

What FullStory includes and what it costs Copy Chapter

FullStory's pricing page lists three analytics plans, Business, Advanced and Enterprise, and each one says "Request pricing & demo". None has a public price.

The published part is the free plan. FullstoryFree is "a permanent version of our platform designed for individuals and small teams": 30,000 sessions a month, 12 months of data retention, "Session Replay, basic analytics, and debugging tools for up to 10 users", and no credit card. Dashboards, StoryAI (FullStory's AI agents) and anything above 30,000 sessions need a paid plan. The paid plans' comparison table lists heatmaps, click and scroll maps, funnels, journeys, retention analysis, sentiment signals, co-browsing and retroactive data history, with mobile analytics and Guides and Surveys as add-ons on all three.

Three things make FullStory hard to replace one for one:

• Sentiment signals. FullStory flags rage clicks, error clicks, dead clicks and thrashed cursors (developer docs) and says these signals "are automatically prioritized by business impact" (sentiment signals).
• Dev Tools in the player. A Console and a Network view open beside any replay, on every plan including Free.
• Mobile coverage. The mobile SDKs cover iOS, Android, Flutter, React Native and Cordova/Capacitor.

If 30,000 sessions a month covers you, FullstoryFree may be all you need.

Why teams look for alternatives to FullStory Copy Chapter

• Price opacity and sales-led buying. Past 30,000 sessions, every route runs through a demo and a quote. Teams that budget from a price list, or pay by card, need a vendor that publishes one.
• Where the data lives. Private by Default is strict ("no text is captured or sent outside the user's browser unless it is explicitly allowlisted as safe to capture"), but you turn it on by asking FullStory's support team. Fullstory Relay routes capture through your own domain, yet the traffic is still "relayed immediately to the Fullstory servers for processing". Recordings that must stay on your infrastructure need a self-hosted tool.
• Debugging depth. Teams that mostly use replay to fix bugs want it inside the tool that already holds their errors, traces and logs.
• Paying for more than you use. Watching replays and running a few funnels doesn't need an enterprise contract.

Enterprise digital experience analytics Copy Chapter

These two cover most of what FullStory does, and both sell their top tiers through sales, as FullStory does.

Contentsquare Copy Section

Contentsquare is the closest like-for-like replacement: replay, heatmaps, funnels, journey analysis, JavaScript error and performance monitoring, surveys and an AI assistant called Sense, for "sites and mobile apps". Unlike FullStory, its lower tiers are self-serve. From the pricing page:

• Free: 200,000 monthly sessions, replays for 5% of them (up to 10,000), 1 project.
• Growth: from $49/month for 7,000 sessions to $409/month at 100,000, with 13 months of session data, 2 months of replays, 3 projects and zone-based heatmaps.
• Pro (from 1 million monthly sessions) and Enterprise: no published price.

Replay volume is the limit to understand. The replay allowance is "a fixed amount per month — it can't be increased", and on Growth every session is replayable up to 20,000 a month; above that, 15% of sessions are, with a floor of 20,000. Growth has a 15-day trial without payment details and 20% off when paid annually by card. Product analytics is still "a separate application for the next few months", and Contentsquare also owns Heap, which it acquired in December 2023.

Pick it if you want FullStory-level experience analytics with a free tier and public prices up to 200,000 sessions. Skip it if you need any session on demand: past 20,000 a month, most replays are sampled.

Contentsquare also runs Hotjar now; if Hotjar is what you're replacing, see our Hotjar alternatives guide.

Quantum Metric Copy Section

Quantum Metric is the other enterprise platform in this category, and FullStory's own alternatives article groups it with Contentsquare. There's no self-serve tier: the pricing page offers "Enterprise plans built around your business", priced on "your annual session volume, the digital properties where we are deployed, product add-ons and other things like the amount of professional services you're looking for".

Every plan includes the Felix AI analyst, analytics with anomaly detection and Core Web Vitals monitoring, journeys, and replay with AI summaries, plus implementation and PII remediation; contact center, data streaming and voice of customer are among the add-ons. Replay covers "web or native mobile applications", interaction heatmaps show "page-level clicks, scrolls, and attention", and Quantum Metric says "Everything is encrypted at the client device and exposed personal information is never sent across the network."

Pick it if you're a large company replacing FullStory with a peer and want onboarding and PII cleanup in the contract. Skip it if sales-led pricing is why you're leaving: the buying process is the same.

Developer debugging: replay tied to errors, console and network Copy Chapter

These three suit teams whose main use of FullStory is Dev Tools: reproducing bugs from real sessions.

LogRocket Copy Section

LogRocket pairs replay with debugging data. Each session carries "logs, network requests, JavaScript exceptions and performance data, as well as user and device metadata" (session replay for developers), and the mobile SDKs run on Android, iOS, React Native, Flutter, Ionic and Expo. Core also includes clickmaps, heatmaps, rage-click maps, path analysis, funnels and surveys.

The pricing page charges for sessions; analytics, error and log events are unlimited. Its calculator runs from a free tier at 1,000 sessions a month to $83/month for 10,000, $176/month for 25,000 and $717/month for 100,000 on Core, and the page notes that the final price also depends on seats, retention and add-ons. Pro adds Galileo AI (session summaries, issue detection) and is "included free above 100K sessions / mo"; Enterprise adds unlimited seats and a self-hosted option. The trial is 14 days with no card.

Pick it if engineers own replay and you need mobile apps covered. Skip it if you want a flat price: costs climb quickly past 25,000 sessions.

Sentry Session Replay Copy Section

If you already use Sentry for errors, its replay covers the debugging half of FullStory. "Errors, traces, network requests, and console logs are all connected to the replay timeline", and rage clicks and dead clicks are linked to replays too, per the Session Replay docs. It records the web plus Android, iOS, React Native and Flutter.

The pricing page lists Developer free for one user, Team at $26/month and Business at $80/month billed annually, each with 50 replays a month; new users get 5,000 free replays a month for their first 3 months. Extra replays start at $0.00375 each pay-as-you-go and get cheaper with volume (pricing docs), so 100,000 replays a month on Team comes to about $383 including the plan. Self-hosted Sentry is "Fair Source under the FSL (Functional Source License)" and needs 4 CPU cores and 16 GB of RAM plus 16 GB of swap (self-hosted docs).

Pick it if you want replays of the sessions that broke, next to the stack trace. Skip it if UX research is the main job: Sentry is an error-monitoring tool first.

OpenReplay Copy Section

OpenReplay is open-source, developer-first replay. Its DevTools show "JavaScript errors with full stack traces and sourcemaps", let you "Inspect API calls, track failing requests, and analyze response payloads with sensitive data sanitized", and track CPU, memory and application state through a session. The pricing page also lists co-browsing, heatmaps, funnels, journeys, product analytics and mobile.

The code defaults to AGPL-3.0, with the ee/ directory under its own license (LICENSE). "Open-Source is free — you host it on your own infrastructure", on at least 2 vCPUs, 8 GB of RAM and 50 GB of storage (Docker guide). The managed Dedicated plan starts at $199/month, billed hourly: a dedicated VM "with no limits on users, recordings, or retention", with a 7-day trial and no card. The page also lists a usage-based Serverless option and a self-hosted Enterprise tier.

Pick it if recordings must stay on your servers and developers are the main users. Skip it if you'd rather not run the infrastructure and $199/month is too much for a managed instance.

FullStory alternatives for product teams Copy Chapter

These three put product analytics first and attach replay to it, which suits teams that use FullStory mostly for funnels, retention and cohort questions.

PostHog Copy Section

PostHog is the broadest product-team option: product analytics, replay, heatmaps, feature flags, experiments, surveys and error tracking on one usage-based bill. Rybbit vs PostHog compares it with our product in detail.

Each month the pricing page gives 1 million analytics events, 5,000 recordings, 1 million feature-flag requests, 100,000 exceptions and 1,500 survey responses free, with no card. Replay pricing then runs from $0.0050 per web recording down to $0.0015 above 500,000, so 100,000 web recordings a month cost $272.50; mobile gets 2,500 free, then $0.0100 each. Replays can include console logs and the network waterfall, and recording works in React Native, iOS, Android and Flutter apps as well as on the web. Heatmap data, per PostHog, "is captured along with other events, so it doesn't contribute to your bill".

PostHog offers "a free Docker Compose deployment under an MIT license", but its self-host page calls self-hosted deployments "officially unsupported" and says it has no guarantees for self-hosted instances.

Pick it if your product team wants flags, experiments and replay in one tool. Skip it if you need supported self-hosting or a narrower tool.

Amplitude Copy Section

Amplitude is product analytics first, with replay, heatmaps, experimentation, and guides and surveys in one platform; its pricing page says "Every plan includes the full platform and unlimited seats". Free gives 2 million events and 10,000 session replays a month with no card. Plus "Starts at $0", keeps the first 2 million events free, scales to 70 million, and adds heatmaps and 2-year data retention; it needs a card. Growth and Enterprise are custom and include 20,000 and 50,000 monthly replays. Replays cover web and mobile but are kept for 1 month on every plan, with more retention sold as an add-on on Growth and Enterprise.

Pick it if analytics is the main job and replay is for spot checks. Skip it if you watch replays at volume or need more than a month of them.

Heap Copy Section

Heap is autocapture product analytics, owned by Contentsquare since December 2023. On its pricing page, Free covers up to 10,000 monthly sessions with 6 months of data history and SSO. Growth adds Contentsquare's Sense AI assistant, unlimited users and reports and 12 months of history, priced by estimate once you install the snippet; Pro and Premier have "Custom Session Pricing". Session replay, heatmaps and error analysis aren't available on Free or Growth; they're add-ons on Pro and Premier.

Pick it if you want autocapture analytics and already buy from Contentsquare. Skip it if replay is why you're shopping: here it's an add-on to an enterprise plan.

Free and low-cost options Copy Chapter

Microsoft Clarity Copy Section

Clarity is the zero-cost answer. Microsoft's FAQ says "Clarity is a free service forever. You never encounter traffic limits or are compelled to upgrade to a paid version", with no sampling. You get recordings, heatmaps and insights, and mobile SDKs cover Android, iOS, React Native, Flutter and Cordova/Ionic.

The trade-offs are retention and control. Data "is retained for the webmaster's consumption up to 30 days from the time of recording", the FAQ states that Microsoft has access to it, and for visitors in the EEA, UK and Switzerland you must pass a consent signal; without valid consent, Clarity "limits data collection in those regions".

Pick it if the budget is zero and 30 days of history is enough. Skip it if you need longer retention, or a large European audience would leave you with thin data.

Mouseflow Copy Section

Mouseflow publishes its prices and bundles session replay; click, scroll and geo heatmaps; friction and JavaScript error detection; funnels; journey and form analytics; and feedback surveys. Per the pricing page, Free covers 500 sessions a month with 1 month of retention. Essential is $25/month for 5,000 sessions and 3 months, Advanced $109/month for 25,000 and 6 months, and Premium $319/month for 100,000 and 12 months, adding API access, an MCP connection and SSO. Every plan has unlimited users, annual billing saves up to 35%, and paid plans start with a 14-day trial.

Pick it if you want heatmaps and 12 months of history at a published price. Skip it if you need product analytics or debugging depth: Mouseflow is built for UX and conversion work.

Privacy-first and self-hosted options Copy Chapter

OpenReplay, above, is the self-hosted pick for developer replay, and PostHog and Sentry self-host with the caveats in their sections. Rybbit fits if you want replay inside privacy-first web analytics.

Rybbit Copy Section

Rybbit is open-source web and product analytics with session replay on the Pro plan. The player's timeline marks page navigations, clicks, typing and rage clicks, so you can jump to where a visitor got stuck. Around it sit funnels, user journeys, goals, retention, user profiles, Web Vitals and error tracking, which groups uncaught JavaScript errors and unhandled promise rejections with stack traces and affected-session counts.

Input values are masked by default, and script attributes mask or block elements by class or selector. Analytics tracking is cookieless and needs no consent banner. The cloud is hosted in the EU, and you can self-host everything, replay included, free under AGPL-3.0.

Standard starts at $19/month for 100,000 events with funnels, journeys, error tracking and Web Vitals, but no replay. Pro starts at $39/month for 100,000 events and adds replay, unlimited sites and team members, and 5-year data retention; billed annually, it's $26/month (pricing). Both start with a 7-day trial, and a card is collected at signup. Replays are stored for 30 days.

Where it falls short of FullStory:

• No heatmaps, click maps or scroll maps.
• Rage clicks are marked in each replay, but there are no aggregated frustration reports and no error-click, dead-click or thrashed-cursor signals.
• Replays don't capture console output or network requests; errors live in the separate error tracking view.
• Web only: the React Native SDK tracks screens, events and errors, but session replay doesn't apply to mobile apps.
• No surveys, no AI session summaries and no FullStory importer; data import covers Plausible, Umami and Simple Analytics only.

Pick it if you want replay next to privacy-first analytics, at a published price, with the option to self-host. Skip it if heatmaps, mobile replay, frustration dashboards or console and network capture are why you use FullStory; LogRocket, Contentsquare or PostHog fit those better.

Switching from FullStory: what to plan for Copy Chapter

• History doesn't move. Rybbit has no FullStory importer, and none of the pages we checked for this article advertise one. Run both tools until the new one has enough history for your reports.
• Replay retention varies. FullstoryFree keeps 12 months of data. Clarity keeps 30 days, Amplitude 1 month, Contentsquare Growth 2 months of replays, Mouseflow 1 to 12 months by plan and Rybbit 30 days; OpenReplay's Dedicated plan sets no limit.
• Know what's capped. Contentsquare and Amplitude cap replays separately from sessions or events. Sentry, PostHog and LogRocket bill per replay or session past the free allowance.
• Rebuild privacy rules. FullStory's .fs-exclude, .fs-mask and .fs-unmask classes are FullStory's own. Map each to the new tool's equivalent before you record; in Rybbit, that's the block and mask options in the script docs.
• Mobile narrows the list. Contentsquare, Quantum Metric, LogRocket, Sentry, OpenReplay, PostHog, Amplitude and Clarity document mobile app replay; Rybbit records the web only.

Which FullStory alternative should you choose? Copy Chapter

• Same enterprise depth, different vendor: Contentsquare for a free tier and a price list to start with; Quantum Metric for implementation and PII remediation in the contract.
• Engineers debugging production issues: LogRocket for web and mobile; Sentry Session Replay if you already run Sentry; OpenReplay if recordings must stay on your servers.
• Product teams: PostHog for analytics, flags, experiments and replay together; Amplitude if analytics comes first; Heap if you already buy from Contentsquare.
• No budget: Microsoft Clarity, if 30 days of data and an EU consent signal are acceptable, or FullstoryFree, if 30,000 sessions a month is enough.
• Heatmaps and a year of history at a published price: Mouseflow Premium, $319/month for 100,000 sessions.
• Privacy-first analytics with replay and a self-hosted option: Rybbit, unless heatmaps or mobile replay are requirements.

FAQ Copy Chapter

What is the best free FullStory alternative?
Microsoft Clarity is free with no traffic limits, but keeps data for 30 days. PostHog (5,000 recordings and 1 million events a month), Amplitude (10,000 replays and 2 million events) and Contentsquare (200,000 sessions, up to 10,000 replays) also have free plans, and OpenReplay and Rybbit are free to self-host.

How much does FullStory cost?
FullstoryFree costs nothing for 30,000 sessions a month, 12 months of data and up to 10 users. Business, Advanced and Enterprise have no public price; the pricing page says "Request pricing & demo" for each.

Who are FullStory's main competitors?
Contentsquare and Quantum Metric in enterprise experience analytics; LogRocket, Sentry and OpenReplay in developer-focused replay; Amplitude, Heap and PostHog in product analytics. FullStory's own alternatives article also names Adobe Analytics, Mixpanel, Pendo, Datadog and Dynatrace.

Is there an open-source alternative to FullStory?
Yes. OpenReplay (AGPL-3.0 by default, with a separately licensed ee/ directory) and Rybbit (AGPL-3.0) self-host with replay included. PostHog's Docker Compose deployment is MIT-licensed but officially unsupported, and Sentry self-hosts under a license it calls Fair Source rather than open source.

Which FullStory alternatives have heatmaps?
Contentsquare, Quantum Metric, LogRocket, OpenReplay, PostHog, Microsoft Clarity and Mouseflow; Amplitude from its Plus plan; Heap as an add-on on Pro and Premier. Rybbit has none, and Sentry's pages we checked don't list them.

Content Blog Funnel Analysis (`docs/content/blog/funnel-analysis.mdx`) Copy Section

title: "Funnel Analysis: How to Find Where Users Drop Off" keyword: "funnel analysis" date: 2025-11-26 updated: 2026-09-28 tags: ["analytics", "funnels", "conversion", "optimization"] author: Rybbit Team Copy Chapter

Your site gets thousands of visitors a month. How many of them do the thing you built the site for?

Funnel analysis is how you answer that. You define the sequence of steps a user takes to reach a goal, count how many sessions reach each step, and find the step where most of them leave. Traffic numbers tell you how many people arrived. The funnel tells you where you lost them.

This guide covers what a conversion funnel is, the metrics that matter, how to set up and read a funnel, how to segment it by source and device, the patterns that point at specific problems, and how to fix them. Examples use Rybbit's funnels, but the method applies to any tool.

What is a conversion funnel? Copy Chapter

A conversion funnel is the path a visitor follows from arriving on your site to completing a goal: a purchase, a signup, a demo request, a download. It is called a funnel because it narrows. Many people enter at the top and a few come out the bottom.

Marketers often describe the same thing as a sales funnel with stages such as awareness, consideration, decision, and retention. In web analytics the stages are concrete: pages viewed and events fired, in order.

Some typical funnels:

• Ecommerce: product page → add to cart → checkout → payment complete
• SaaS: landing page → signup form → email verified → first key action
• Lead generation: landing page → form submitted → thank-you page
• Content: blog post → CTA click → form → download confirmed

Not everyone who enters completes the funnel, and that is normal. If 1,000 people view a product page, 300 add it to the cart, and 150 pay, the overall conversion rate is 15%. The opportunity is in the steps: lifting checkout completion from 50% to 60% yields 30 more orders from the same 300 carts, without buying a single extra visitor.

The funnel metrics that matter Copy Chapter

For every step you want four numbers:

• Sessions at the step. How many sessions reached it. The absolute count tells you how much is at stake at each stage.
• Step conversion rate. The share of sessions from the previous step that reached this one. This is the efficiency of the step.
• Drop-off rate. The inverse: the share that completed the previous step but not this one. The step with the highest drop-off and the most traffic is your first priority.
• Overall conversion rate. The share of sessions that entered the funnel and completed it. This is the number that connects the funnel to revenue.

Two more are worth knowing. Time to convert shows whether a step is slow as well as leaky. Conversion by segment (source, device, country, new vs returning) shows whether the funnel has one problem or several.

How to run a funnel analysis Copy Chapter

1. Start from the goal. Pick the single most important action on the site. If you cannot name one, you are not ready to build a funnel.

2. Map three to five steps backward from it. Every extra step adds noise. Start with the steps a user must pass through, and add optional pages later if they turn out to matter.

3. Decide how strict the order is. A strict funnel counts only sessions that hit the steps in sequence. Looser definitions count any session that eventually reached each step. Strict funnels are easier to act on; loose ones are more forgiving of real user behaviour. Know which one your tool uses.

4. Pick the time window. A checkout funnel should complete within a session. A B2B signup-to-activation funnel might take two weeks. If the window is too short you undercount conversions; too long and you blur the signal.

5. Segment before you conclude. A 40% drop-off at checkout might be 20% on desktop and 70% on mobile. Split by device, traffic channel, country, and landing page before deciding what is broken.

6. Compare to a previous period. The absolute drop-off matters less than whether it got better or worse after the change you shipped.

Funnel analysis in Rybbit Copy Chapter

Rybbit's funnel builder lets you define steps from page paths, custom events, or autocaptured interactions (outbound link clicks, button clicks, form submissions, and copied text), then shows sessions, conversion rate, dropped sessions, and drop-off rate for every step.

Define the steps. Path steps match pageviews by URL, with * wildcards for things like /products/*. Event steps match custom events such as add_to_cart. Each step can carry property filters, so "purchase where plan = pro" is one step, not a separate funnel.

Read the result. The visualization updates as you edit. For each step you see how many sessions arrived, the percentage of first-step sessions that made it this far, and how many were lost since the previous step. The biggest bar-to-bar drop is where to look first.

Drill into the sessions. Every step links to the sessions behind it, so when a number looks wrong you can open session replay and watch what people did at that step instead of guessing.

Track single-step conversions as goals. Not every conversion is multi-step. Goals track one action, such as a thank-you page view, a form submission, or a button click, and report conversions, conversion rate, and performance by channel and device.

Find the pages that feed the funnel. The Pages report shows traffic, bounce rate, and time on page for every URL. Click into a page to see only the sessions that visited it and check whether they convert more or less than average. This is how you learn which product pages produce cart additions and which blog posts produce signups.

Segment by channel and device. Any filter applies to the funnel. Filter by channel to compare organic search, paid, email, social, and referral; filter by device to compare mobile and desktop.

A common finding: two channels send the same traffic, but one converts twice as well. Another: mobile brings half the sessions and a tenth of the conversions, which makes mobile checkout the highest-value fix on the site.

Check the paths you did not define. A funnel assumes a sequence. Real users skip steps, loop back, and leave and return. The Journeys report shows the actual paths through the site, so you can work backward from a conversion to see what successful users did, or forward from a landing page to see where people actually go.

Reading the patterns Copy Chapter

A steep drop at one step. Something specific is wrong there: a confusing form, a bug, a slow page, an unexpected cost, a trust gap at payment, or a broken mobile layout. Watch replays of sessions that dropped at that step; the cause is usually visible within ten recordings.

Gradual erosion at every step. No single step looks terrible, but 30–40% leaks at each one add up. This usually means the value proposition is unclear or the traffic is poorly matched to the offer. Fix the message and the targeting before the UI.

Segments that disagree. Organic converts and paid does not; new visitors convert and returning ones do not; one country lags the rest. Each of these points at a specific audience or campaign rather than the funnel itself.

A drop that appeared on a date. Line the funnel up against your deploys and campaigns. A step that lost 20% overnight is a regression, not a design problem.

Fixing the leaks Copy Chapter

• Reduce friction. Every field, step, and second of load time costs conversions. Remove fields you do not need, merge steps, and measure page speed at the leaky step.
• Build trust where money changes hands. Security badges, transparent pricing, a clear privacy policy, and recognizable payment options matter most at checkout.
• Say what happens next. Progress indicators and a preview of the following step reduce abandonment from uncertainty.
• Fix mobile first if mobile is worse. It is usually where the largest gap is.
• Address the objection at the step where it appears. High price: show value. Long commitment: offer a trial. Confusing process: add one sentence of explanation.
• Change one thing and re-measure. Compare the funnel before and after, on the same segment, over the same window. If you change three things at once you will not know which one worked.

Typical funnel conversion rates Copy Chapter

Ranges vary enormously by industry and traffic quality, so use them to sanity-check, not to grade yourself:

For ecommerce specifically, the ecommerce analytics guide goes deeper on the metrics behind each step.

Funnel analysis tools Copy Chapter

Most analytics products can build a funnel; they differ in how much setup they need and what you can do with a leaky step once you find it.

• Rybbit defines steps from paths, events, or autocaptured clicks and forms, filters by any dimension, and links each step to session replays. Open source and self-hostable.
• Google Analytics 4 builds funnels in Explorations. Powerful, but every step must be an event you configured in advance, and the interface is the hardest of the group to learn.
• PostHog, Mixpanel, and Amplitude are product-analytics suites with deep funnel tooling, including strict ordering and conversion-time analysis. They assume an instrumented product and event schema.
• Matomo offers funnels as a paid plugin on self-hosted installs and as part of its cloud plans.

If you already track pageviews and a handful of events, you can build your first funnel in any of these in an afternoon. Pick the one whose data you already have.

Getting started Copy Chapter

1. Define the one conversion that matters most.
2. Map three to five steps backward from it.
3. Build the funnel and note the overall conversion rate and the biggest drop.
4. Segment by device and channel to see whether the drop is universal.
5. Watch a few replays at the leaky step.
6. Change one thing, wait a week or two, and compare.
7. Repeat.

Most sites do not need more traffic to grow. They need to convert more of the traffic they already have, and funnel analysis is how you find out where that traffic is going.

Related reading:

• Funnels documentation, Goals, and Journeys
• Retention Analysis: How to Measure and Improve User Retention
• What Is Bounce Rate? How to Calculate and Reduce It
• What Is Multivariate Testing?
• Best Marketing Attribution Tools

Content Blog Geographic Segmentation (`docs/content/blog/geographic-segmentation.mdx`) Copy Section

title: "Geographic Segmentation: How to Use Location Data in Analytics" keyword: "geographic segmentation" date: 2025-12-03 updated: 2026-09-28 tags: ['marketing', 'analytics', 'segmentation', 'targeting', 'geographic'] author: Rybbit Team Copy Chapter

Geographic segmentation divides your audience by location—country, region, city, or neighborhood. For marketers, it's one of the most practical segmentation strategies because location data reveals real behavioral differences across markets. Whether you're optimizing landing pages, adjusting ad spend, or localizing content, geographic insights drive better decisions.

What is Geographic Segmentation? Copy Chapter

Geographic segmentation groups your visitors, customers, or prospects based on where they're located. It's straightforward in concept but powerful in application.

Simple examples:

• US visitors might see pricing in USD with US shipping costs
• European visitors might see GDPR-compliant messaging
• Mobile-heavy regions might receive mobile-optimized experiences
• High-traffic regions might warrant dedicated marketing budgets

The core idea: Different locations have different needs, behaviors, and preferences. When you recognize and respond to those differences, your marketing becomes more effective.

Why Geographic Segmentation Matters Copy Chapter

Geographic segmentation isn't just about translation or currency conversion. It addresses fundamental marketing questions:

Market Penetration Copy Section

Some geographic markets are more mature than others. Your product might dominate in Germany but be relatively unknown in Brazil. Segmentation helps you identify which regions are underperforming and deserve more attention or different positioning.

Regional Preferences Copy Section

Consumer behavior varies by region. Payment methods differ, holidays differ, language preferences differ, seasonal patterns differ. What sells in summer in the Northern Hemisphere sells in winter in the Southern Hemisphere.

Resource Allocation Copy Section

Marketing budgets are finite. Geographic data shows you where your customer acquisition is most efficient. Instead of spreading spend evenly, you concentrate resources on high-performing regions and test carefully in emerging markets.

Regulatory Compliance Copy Section

Different regions have different rules. GDPR applies to Europe. Privacy laws differ in California, Canada, Australia. Geographic segmentation helps you understand where compliance requirements apply.

Competitive Positioning Copy Section

Competition isn't uniform globally. You might face different competitors in different regions. Knowing where competitors are strong helps you position strategically.

Common Applications of Geographic Segmentation Copy Chapter

Localized Marketing Campaigns Copy Section

Tailoring campaigns by region increases relevance. A campaign that resonates in New York might miss entirely in rural Montana. Geographic segmentation lets you test different messages in different places.

Pricing Strategy Copy Section

International pricing often varies based on local purchasing power, competition, and regulations. Geographic segmentation reveals whether your pricing strategy is competitive in each region.

Content Localization Copy Section

Beyond translation, content localization means adjusting tone, examples, references, and focus for different audiences. A tech product aimed at decision-makers in Japan might emphasize different benefits than the same product for German audiences.

Regional Product Focus Copy Section

Some product features resonate more in certain regions. Geographic segmentation shows you which features drive engagement where, informing your regional roadmap.

Event and Campaign Timing Copy Section

Geographic data reveals whether events and campaigns land better at certain times for certain regions. Holiday campaigns, seasonal promotions, and product launches can be timed regionally.

Paid Advertising Optimization Copy Section

With geographic performance data, you adjust ad spend per region, pause campaigns in underperforming areas, and double down on high-ROI locations.

How to Implement Geographic Segmentation in Your Analytics Copy Chapter

Analytics platforms that support geographic filtering let you slice your data by location. This reveals actual visitor behavior by region rather than guessing.

Accessing Geographic Data in Your Analytics Copy Section

Modern analytics tools display visitor locations automatically. This typically comes from IP geolocation data. Once you can see how your visitors distribute geographically, you can start segmenting your analysis.

The geographic filter lets you focus on specific regions. Rather than analyzing all visitors together, you can examine Germany separately from the US, which often reveals completely different behavior patterns.

Comparing Geographic Segments Copy Section

Once you can filter by location, comparison becomes possible. You can ask questions like:

• Which country has the highest bounce rate? If visitors from Brazil bounce 2x more than visitors from Canada, that signals either a targeting problem or a product-market fit issue in Brazil.

• Where do users spend the most time? Some regions might have significantly longer session durations, suggesting higher engagement.

• Which regions convert best? Conversion rates often vary dramatically by geography.

• Where do users engage most with specific features? Geographic data combined with event tracking shows which regions engage with which parts of your product.

Combining Geographic Filters with Other Dimensions Copy Section

Geographic data becomes even more powerful when combined with other segmentation dimensions:

• Geography + Traffic Source: Do visitors from organic search in Germany behave differently than paid visitors from Germany?
• Geography + Device Type: Is your mobile experience performing worse in specific regions?
• Geography + Traffic Channel: Which channels work best in which regions?

By layering filters, you discover specific insights that single-dimension analysis misses.

Challenges in Geographic Segmentation Copy Chapter

Geographic segmentation, while powerful, comes with practical challenges:

Data Quality Copy Section

IP geolocation isn't perfect. It's usually accurate to the country level, sometimes to the city level, but not to the street address. VPNs and proxies distort location data. Mobile networks sometimes mis-report location.

Sample Size Copy Section

If you're optimizing for 50 different countries, some might have tiny visitor volumes. Statistical significance becomes harder to achieve. You need enough traffic per region to draw reliable conclusions.

Cultural Complexity Copy Section

Just because two people live in the same country doesn't mean they're the same audience. Large countries like the US, India, and Brazil have significant cultural variation within their borders.

Implementation Complexity Copy Section

Localizing campaigns for 20 different regions requires 20x more marketing effort. It's powerful but expensive. Most companies focus on their top 5-10 regions rather than trying to personalize for everyone.

Privacy Considerations Copy Section

IP-based geolocation relies on collecting location data. Depending on your audience and jurisdiction, you may face privacy restrictions. Privacy-first analytics approaches need to balance geolocation with visitor privacy.

Real-World Example: Using Geographic Data to Optimize Copy Chapter

Here's how geographic segmentation might work in practice:

Your situation: You run a B2B SaaS tool. You notice overall bounce rates are 40%. That seems high.

Geographic breakdown reveals:

• US visitors: 35% bounce rate
• German visitors: 45% bounce rate
• Brazilian visitors: 65% bounce rate

This tells you:

• US is working fine
• Germany needs attention
• Brazil has a serious problem

Next steps:

• For Germany: Maybe pricing is unclear, or the mobile experience is poor. You dig deeper.
• For Brazil: Currency conversion, payment methods, or messaging might be off. Or maybe you're attracting wrong audience through ads.

By segmenting geographically first, you avoid the trap of "our bounce rate is too high" and instead ask "our bounce rate is too high in specific regions, and here's what I'll do about it."

Segmentation and Analytics Tools Copy Chapter

Not all analytics platforms handle geographic segmentation equally. Some key questions to ask:

• Can you filter your data by country and region in real time?
• Can you combine geographic filters with other dimensions (traffic source, device, custom properties)?
• How accurate is the location data?
• Can you set up comparisons between geographic segments?
• Does the tool support historical trend analysis by region?

Having geographic segmentation built into your analytics workflow means you can answer location-based questions quickly without exporting data or running custom reports.

Moving Beyond Basic Segmentation Copy Chapter

Once you master basic geographic segmentation (country-level filtering), more advanced approaches become possible:

Regional Cohort Analysis Copy Section

Track specific cohorts by region. Do monthly active users in Japan have different retention curves than monthly active users in the UK?

Regional Funnels Copy Section

Build funnels for specific regions. Does your checkout funnel drop off at different steps in different countries?

Regional Benchmarking Copy Section

As you expand into new markets, compare early performance against established markets. This reveals whether you're on track.

Geographic Performance Trends Copy Section

Watch how performance changes over time in specific regions. Is Germany growing or declining? When did that shift happen?

Common Mistakes in Geographic Segmentation Copy Chapter

Mistake 1: Over-Segmentation Copy Section

Trying to customize for 100 different locations dilutes your effort. Start with your top 5-10 regions.

Mistake 2: Ignoring Within-Country Variation Copy Section

Treating "Germany" as homogeneous misses important local differences. Large countries need sub-regional analysis.

Mistake 3: No Action on Geographic Insights Copy Section

Discovering that bounce rates differ by region only matters if you then act on it. Insights without action are just interesting facts.

Mistake 4: Assuming Causation Copy Section

If US visitors engage more than Brazil visitors, that could be many things—product-market fit, targeting, product maturity, time of day when they visit. Don't assume one cause.

Mistake 5: Static Segmentation Copy Section

Geographic markets change. Competition shifts, regulations evolve, audience preferences shift. Regular review of geographic performance prevents stale strategies.

Geographic Segmentation and Broader Analytics Strategy Copy Chapter

Geographic segmentation doesn't live in isolation. It connects to your broader web analytics approach.

Understanding traffic sources by geography reveals which channels work best where. Tracking bounce rates by region shows you where engagement is weakest. Analyzing session behavior by location reveals usage patterns.

For e-commerce businesses, geographic data combines with product-level analytics to show which products sell where. For content creators, geography reveals which content resonates in different markets.

Getting Started with Geographic Segmentation Copy Chapter

If you're new to geographic segmentation, start simple:

Week 1: Look at your visitor distribution. Which countries/regions send you the most traffic? Which are you surprised by?

Week 2: Compare performance metrics by region. Bounce rate, session duration, conversion rate—which regions stand out?

Week 3: Layer in traffic source. Which channels work best in which regions?

Week 4: Make one small change based on geographic insights and measure the result.

This four-week approach turns geographic data from "interesting dashboard numbers" into actionable insights.

Privacy-Conscious Geographic Segmentation Copy Chapter

If you're using Rybbit or another privacy-first analytics platform, geographic segmentation works through IP-based location data without tracking individual users across sites. You see regional patterns without collecting personally identifiable information.

This matters because geographic segmentation becomes both more useful (you get real data) and more ethical (you're not invading privacy to get it).

Final Thoughts Copy Chapter

Geographic segmentation is one of the most practical marketing optimizations available. It doesn't require expensive tools or complex infrastructure. It simply requires answering: How do different locations behave differently?

The answer often surprises you. What you assume is true for "your audience" might only be true for your largest geographic segment. What you think is a product problem might actually be a regional messaging problem.

By implementing geographic segmentation in your analytics, you move from "one-size-fits-all" marketing to location-aware marketing. You spend more where it works, test carefully where it doesn't, and optimize regionally rather than globally.

Start by exploring your geographic data. Segment by country. Compare performance. Act on what you learn.

Additional Resources:

• Best Marketing Attribution Tools
• What Is Bounce Rate? How to Calculate and Reduce It
• Ecommerce Analytics: The Metrics and Reports That Matter
• What Is Web Analytics? A Complete Guide
• Tracking Events and Custom Dimensions
• Getting Started with Rybbit