πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
docs: update product docs after the settings and site-page redesigns (#1342)
Goldflage69e843db903
diff --git a/docs/content/docs/(docs)/account-settings.mdx b/docs/content/docs/(docs)/account-settings.mdxindex 9bb3761bf..290c0df83 100644--- a/docs/content/docs/(docs)/account-settings.mdx+++ b/docs/content/docs/(docs)/account-settings.mdx@@ -5,72 +5,84 @@ description: Manage your personal account settings including profile, security,import { Callout } from 'fumadocs-ui/components/callout';-Access your account settings by clicking on "Account" or going to [app.rybbit.io/settings/account](https://app.rybbit.io/settings/account).+Open your account settings by clicking **Account** in the settings sidebar or going to [app.rybbit.io/settings/account](https://app.rybbit.io/settings/account). Your profile, sign-in and personal API keys go with you into every organization you belong to.-## Account+The page has five sections: **Profile**, **Preferences**, **Sign-in & security**, **Personal API keys** and **Danger zone**. The **Sign out** button sits at the top right.++## Profile### Name-Update your display name shown across the platform. This name is visible to other members in your organization.+Your display name, shown to teammates in member lists.-Update your email address for account notifications and login. This is the primary email associated with your account.--### Weekly Email Reports <span className="text-green-500 text-sm">(Cloud)</span>+The address you use to sign in and receive reports and invitations. To change it, click **Change email**, enter the new address and click **Send confirmation link**:-Enable or disable automatic weekly email reports. When enabled, you'll receive a summary of your analytics performance delivered to your inbox each week.+- If your current email is verified, Rybbit first emails a confirmation link to your current address, then a link to the new address. The new address takes over once you click both.+- If your current email isn't verified, Rybbit emails a link to the new address only. It takes over once you click that link.-### Sign Out+## Preferences-Sign out of your current session.+### Weekly email reports <span className="text-green-500 text-sm">(Cloud)</span>-## Security+Turn on to receive a weekly traffic summary for each site you can access.-### Change Password+### Language-Update your password to keep your account secure.+The language used for menus and labels in the dashboard.-### Delete Account+## Sign-in & security-Permanently delete your account and all associated data.+### Password-<Callout type="warn">- This action cannot be undone. If you have an active subscription, you must cancel it before deleting your account.-</Callout>+Click **Change password**, enter your current password and a new one, and confirm it. Passwords must be at least 8 characters.-## API Keys+## Personal API keys-Generate API keys to access Rybbit's analytics endpoints from your applications.+Personal API keys act as you, with your role in each organization, and stop working if you leave that organization. For an integration that should keep working when people leave, use an [organization API key](/docs/organization-settings#organization-api-keys) instead.-### Creating an API Key+### Creating an API key-1. Enter a name for your API key (e.g., "Production App", "Development")-2. Optionally enable **Restrict permissions** to limit the key to specific resources. Leave it off for a full-access key that can do everything you can.-3. Click "Create"-4. Copy and save the generated key immediately+1. Click **Create key**+2. Enter a **Key name** so you can tell your keys apart+3. Optionally turn on **Restrict permissions** to limit the key to specific resources. Leave it off for a full-access key that can do anything you can.+4. Click **Create key**+5. Copy and store the key right away<Callout type="warn">- On Rybbit Cloud, API keys require a Standard or Pro plan. On a free plan you'll see an upgrade prompt in place of the creation form.+ On Rybbit Cloud, API keys are available on Standard and Pro plans. On other plans you'll see an **Upgrade your plan** button instead of **Create key**.</Callout><Callout type="warn">- API keys are only shown once when created. Store your key securely as you won't be able to view it again.+ You see the key once, right after you create it. You can't view it again.</Callout>-### Managing API Keys+### Managing API keys-Your existing API keys are displayed in a table showing:-- **Name** - The name you assigned to the key+Your keys are listed in a table with these columns:+- **Name** - The name you gave the key- **Key** - A preview of the key (first few characters)-- **Permissions** - Whether the key has full access or is restricted to specific scopes+- **Permissions** - **Full access**, or the access and resources a restricted key has- **Created** - When the key was created- **Last used** - When the key last made a request-You can delete API keys that are no longer needed. Deleting a key immediately revokes access for any applications using it.+Delete a key you no longer need. Deleting a key revokes access immediately for anything using it.++### Using API keys++Send your API key with requests to Rybbit's API. See [API getting started](/docs/api/getting-started) for authentication and available endpoints.-### Using API Keys+## Danger zone-Include your API key in requests to Rybbit's API endpoints. See the [API documentation](/docs/api) for available endpoints and usage examples.+### Delete account++Deleting your account removes your profile, your sign-in and your personal API keys, and removes you from every organization. Organizations, their sites and their analytics data are not deleted.++To confirm, click **Delete account**, then press and hold **Hold to delete account**.++<Callout type="warn">+ This cannot be undone. If you're the only owner of an organization with an active subscription, you can't delete your account until you cancel that subscription in [Billing](/docs/billing-settings) or make someone else an owner.+</Callout>diff --git a/docs/content/docs/(docs)/annotations.mdx b/docs/content/docs/(docs)/annotations.mdxnew file mode 100644index 000000000..8601762d6--- /dev/null+++ b/docs/content/docs/(docs)/annotations.mdx@@ -0,0 +1,49 @@+---+title: Annotations+description: Pin notes to dates on your traffic chart so spikes and drops stay explainable+---++import { Callout } from 'fumadocs-ui/components/callout';++An annotation is a note pinned to a moment, or a date range, on the main traffic chart. Use them for launches, deploys, campaigns, outages, or anything else that explains why the line moved.++Annotations show as pins along the chart on the [Main dashboard](/docs/feature-guides/main-tab). They also show, read-only, on the [Performance](/docs/feature-guides/performance) chart.++## Add an annotation++1. Open the site's **Main** page.+2. Click **Annotate** above the chart, or click a point on the chart to start a note at that time.+3. Fill in the form:+ - **Title**: what happened, up to 120 characters.+ - **Date and time**: when it happened. Turn on **Date range** to set **Starts** and **Ends** instead. The end must be after the start.+ - **Note** (optional): more context, up to 2,000 characters.+ - **Color**: neutral, or one of five marker colors.+ - **Icon** (optional): an emoji shown in the pin.+ - **Applies to**: **This site** or **All sites** in the organization. You only see this choice if you can manage organization-wide annotations.+ - **Show on public dashboard and shared links**: off by default.+4. Click **Add annotation**.++## View, edit, and delete++Hover a pin to see its notes. Pins that land close together are grouped into one. Click a pin to open its notes, then use the edit or delete buttons on a note. Deleting asks you to confirm and can't be undone.++Notes that apply to every site carry an **All sites** badge. Notes visible to the public carry a **Public** badge.++## Who can do what++| Action | Role needed |+| --- | --- |+| See annotations | Anyone who can view the site |+| Add a site annotation, and edit or delete your own | Member or above |+| Edit or delete anyone's site annotations | Editor or above |+| Add, edit, or delete organization-wide (**All sites**) annotations | Editor or above in the organization |++See [Organization settings](/docs/organization-settings) for how roles work.++## Public dashboards and shared links++If a site is public, or you share it through a private link, visitors only see annotations with **Show on public dashboard and shared links** turned on. Everything else stays visible to your organization only. Private-link viewers can't add or edit annotations, even if they're signed in.++<Callout>+ Annotations are also available through the [API](/docs/api/annotations/list) and the `get_annotations` tool in the [MCP server](/docs/mcp).+</Callout>diff --git a/docs/content/docs/(docs)/autocapture.mdx b/docs/content/docs/(docs)/autocapture.mdxindex ce5088820..db65c4de2 100644--- a/docs/content/docs/(docs)/autocapture.mdx+++ b/docs/content/docs/(docs)/autocapture.mdx@@ -3,7 +3,7 @@ title: Autocapturedescription: Automatically track user interactions without writing code----Rybbit can automatically capture common user interactions without requiring any code changes. These features can be enabled in your [Site Settings](/docs/site-settings) under the "Auto Capture" section.+Rybbit can automatically capture common user interactions without requiring any code changes. You turn these features on and off in your [Site Settings](/docs/site-settings) under the "Auto Capture" section. Outbound link tracking is on by default; the others are off until you enable them.## Available Autocapture Features@@ -17,7 +17,7 @@ Rybbit can automatically capture common user interactions without requiring any## Outbound Links-When enabled, Rybbit automatically tracks clicks on links that navigate to external domains.+On by default. Rybbit tracks clicks on links that navigate to external domains.**Tracked properties:**- `url` - The destination URL@@ -26,10 +26,10 @@ When enabled, Rybbit automatically tracks clicks on links that navigate to exter## Error Tracking-Captures uncaught JavaScript errors and unhandled promise rejections from your site. Only errors originating from your domain are tracked (third-party script errors are filtered out).+Captures uncaught JavaScript errors and unhandled promise rejections from your site. Only errors originating from your domain are tracked (third-party script errors are filtered out). Browser `ResizeObserver loop` warnings are ignored, and an identical error (same name, message, file, line, and column) is sent at most once per 60 seconds.**Tracked properties:**-- `message` - The error message+- `message` - The error message (truncated to 500 characters)- `stack` - Stack trace (truncated to 2000 characters)- `fileName` - Source file where the error occurred- `lineNumber` - Line number@@ -42,8 +42,10 @@ Automatically tracks clicks on:- Elements with `role="button"`- `<input type="submit">` and `<input type="button">`+Repeat clicks on the same button within one second are recorded as a single click.+**Tracked properties:**-- `text` - The button's text content (falls back to `aria-label`, then `value` for input buttons, then `title`)+- `text` - The button's text content, up to 100 characters (falls back to `aria-label`, then `value` for input buttons, then `title`)### Adding Custom Properties@@ -112,7 +114,7 @@ You can add custom properties using `data-rybbit-prop-*` on the form element:### Input Changes (`input_change`)-Triggered when a user changes the value of an input, select, or textarea field. Disabled inputs are automatically excluded from tracking.+Triggered when a user changes the value of an input, select, or textarea field. Disabled and read-only fields are excluded.**Tracked properties:**- `element` - The element type (`input`, `select`, or `textarea`)@@ -137,7 +139,7 @@ You can add custom properties using `data-rybbit-prop-*` on the input element:</select>```-**Privacy note:** Hidden inputs, password fields, and disabled inputs are automatically excluded from tracking.+**Privacy note:** Field values are never sent. Hidden inputs, password fields, and disabled or read-only fields are excluded from tracking.## Enabling Autocapture@@ -145,7 +147,7 @@ You can add custom properties using `data-rybbit-prop-*` on the input element:2. Navigate to the **Auto Capture** section3. Toggle on the features you want to enable-Changes take effect immediately for new visitors. Existing sessions may need to refresh to pick up the new configuration.+The script reads these settings when the page loads, so changes apply on the next page load, within about a minute (site settings are cached briefly on the server). Pages that are already open keep the old settings until they reload.---diff --git a/docs/content/docs/(docs)/billing-settings.mdx b/docs/content/docs/(docs)/billing-settings.mdxindex 82ed93dd5..03c06adce 100644--- a/docs/content/docs/(docs)/billing-settings.mdx+++ b/docs/content/docs/(docs)/billing-settings.mdx@@ -5,7 +5,54 @@ description: Manage your subscription, billing, and usage for Rybbit Cloudimport { Callout } from 'fumadocs-ui/components/callout';-Access billing settings by hovering over the sidebar and clicking "Billing".+Billing exists on Rybbit Cloud only. Open it by clicking **Billing** in the settings sidebar or going to [app.rybbit.io/settings/billing](https://app.rybbit.io/settings/billing). Only organization owners see the **Billing** item; anyone else who opens the page is told that only the owner can manage the subscription.-Subscriptions are scoped to a single organization. If you have multiple organizations, each one requires its own subscription. Switching organizations will show that organization's subscription status.+Subscriptions belong to an organization. If you have several organizations, each one needs its own subscription, and the page shows the plan of the organization that's currently selected.+## Plans and limits++You pick a plan (**Standard** or **Pro**), a monthly event volume, and monthly or annual billing. Each plan has these site and member limits:++| Plan | Sites | Members |+|------|-------|---------|+| **Standard** | 5 | 3 |+| **Pro** | Unlimited | 100 |++Some features need a specific plan. For example, session replay needs Pro, and web vitals, error tracking and API keys need Standard or Pro. Older organizations may be on a **Basic** plan, which allows 1 site and 1 member.++## Free trial++Your first subscription starts with a 7-day free trial. Each organization gets one trial: if it has had a subscription before, checkout charges you right away.++The billing page shows when your trial ends. You can cancel during the trial with **Cancel trial**; you won't be charged, and the plan stays active until the trial ends.++### After a trial ends without payment++If you cancel during the trial, or the first charge fails, your sites keep collecting data for 60 more days at the event limit of the plan you trialed. Subscribe to a plan before then to keep tracking.++## Sites without a plan++Sites created on or after February 13, 2026 in an organization with no trial or paid plan don't collect any data. Start a trial or subscribe to begin tracking. Sites created before that date keep the legacy free tier.++## Usage++Events are counted per organization, across all of its sites, per calendar month in UTC. Usage resets on the 1st of each month.++These count toward your limit: pageviews, custom events, web vitals, outbound link clicks, and autocaptured button clicks, copies, form submits and input changes.++When an organization goes over its monthly event limit, its sites stop collecting until the next month or until you upgrade to a higher limit.++<Callout type="info">+ Bot traffic filtered by [bot detection](/docs/bot-detection) doesn't count toward your usage.+</Callout>++## What the billing page shows++- **Plan** - Your current plan, its event, site and member limits, the price, and when it renews, cancels or when the trial ends. Use **Change plan** or **Upgrade plan** to switch plans.+- **Usage this month** - Events used against your limit, with a projection of when you'll reach it at the current pace, plus the number of **Sites** and **Members** against your plan's limits. If you use organization API keys, it also shows **Org API requests today**.+- **Usage history** - Events per day over a range you choose.+- **Payment** - Click **Manage in Stripe** to change your card and billing email.+- **Cancel subscription** (or **Cancel trial**) - Takes effect at the end of the current period.+- **Invoices** - Past invoices with their date, amount and status.++You can also see a single site's usage under **Site Settings > Usage**. See [Site settings](/docs/site-settings#usage).diff --git a/docs/content/docs/(docs)/bot-detection.mdx b/docs/content/docs/(docs)/bot-detection.mdxindex 80278dc64..341588558 100644--- a/docs/content/docs/(docs)/bot-detection.mdx+++ b/docs/content/docs/(docs)/bot-detection.mdx@@ -6,30 +6,35 @@ description: How Rybbit identifies and filters bot traffic from your analyticsimport { Callout } from 'fumadocs-ui/components/callout';import { Steps, Step } from 'fumadocs-ui/components/steps';-Rybbit can filter bot traffic before it reaches your normal analytics. When **Block Bot Traffic** is enabled for a site, each incoming tracking request is checked by several detection layers. If any layer identifies the request as bot traffic, the request is excluded from the normal analytics tables and stored separately for bot traffic inspection.+Rybbit checks every incoming tracking request against several detection layers, on every site. The per-site **Block Bot Traffic** setting decides what happens to a request that a layer flags as a bot.-## Enabling Bot Detection+## Block Bot Traffic-Bot blocking is configured per site:+**Block Bot Traffic** is on by default for new sites. To change it:1. Open your site in the Rybbit dashboard2. Go to **Site Settings**-3. Enable **Block Bot Traffic**+3. Toggle **Block Bot Traffic**-When this setting is off, Rybbit does not block requests based on bot detection.+| Setting | What happens to a detected bot |+| --- | --- |+| **On** (default) | The request is kept out of your normal analytics and stored as a bot event instead. |+| **Off** | The request is tracked like any other visit and counts toward usage. It does not appear in bot events. |## What Happens to Detected Bots-Detected bot requests are not added to your normal analytics data. This keeps dashboard totals, reports, journeys, funnels, session lists, and usage metrics focused on human traffic.+With blocking on, detected bot requests are not added to your normal analytics data. This keeps dashboard totals, reports, journeys, funnels, session lists, and usage metrics focused on human traffic.-Detected bot visits also do not count toward billable analytics usage. If bot blocking filters a request, you are not charged for that bot visit.+Blocked bot requests also do not count toward billable usage, because usage is counted from your normal analytics events only. With blocking off, detected bots are tracked and billed like any other traffic.-Rybbit still stores a compact bot event record so you can inspect what was filtered. Bot event records include route, device, location, ASN, and which detection layers matched.+For blocked requests, Rybbit stores a compact bot event record so you can inspect what was filtered. Bot event records include route, device, location, ASN, and which detection layers matched.## Detection LayersRybbit runs all detection layers before making a final decision. A request can match multiple layers, and the bot event records every layer that matched.+For sites set up as mobile apps, the user-agent and header layers are skipped, because native app traffic legitimately looks like a non-browser HTTP client. The other layers still run.+<Steps><Step>@@ -77,14 +82,17 @@ Signals include:- Automation APIs- Zero or impossible window dimensions-- Default automation viewport sizes such as `800x600` and `1024x768`+- Default automation viewport sizes on desktop browsers: `800x600`, `1024x768`, and `1280x1200`+- Square screens (a heuristic: a few real monitors are square, but most square screens in traffic are renderer defaults)- Suspicious outer window dimensions- Missing browser APIs- Missing Chrome globals- SwiftShader renderer signals- Empty plugin lists-Rybbit combines these into a weighted score. Strong signals can identify bot traffic on their own, while weaker signals contribute supporting evidence.+The server also notes when a web hit arrives with no screen dimensions at all.++Rybbit combines these into a weighted score. Strong signals (automation APIs, impossible dimensions, the default viewports, and square screens) can identify bot traffic on their own. Weaker signals only add supporting evidence when another layer has already flagged the request.</Step>@@ -109,17 +117,24 @@ This avoids filtering every legitimate visitor who happens to browse through a cThe `rate_anomaly` layer watches for bursty or crawl-shaped behavior.-It tracks short rolling windows for patterns such as:+It watches rolling windows, from seconds to a day. Rules that describe a single visitor (one IP and user agent) can flag a request on their own:++- Too many events, or too many distinct paths, from the same IP and user agent in a short window+- Interaction events (clicks, copies, form events) faster than a person can produce them+- A busy browser fingerprint spread evenly across many browser versions, which real visitor populations don't produce+- During a traffic flood measured against the site's own normal volume, a burst of one-shot visitors arriving directly, or a single hosting-network address sending a large share of events+- Very high daily volume from a single address on a hosting or datacenter network++Rules about things many real visitors share, such as one IP address or one popular user agent, only add supporting evidence and never flag a request alone:-- Too many events from the same IP and user-agent- Too many events from the same IP-- Too many distinct paths visited quickly-- Too many different user-agents from one IP+- Too many different user agents from one IP- Too many hostnames from one IP-- High site-wide volume from one user-agent-- Large volumes of requests missing client-side bot scores+- High site-wide volume from one user agent+- High daily volume from one IP address+- A burst of requests missing the client-side bot score-This layer is designed to catch fast crawlers, floods, and replayed tracking requests that may not have obvious user-agent or browser fingerprint signals.+This layer is designed to catch fast crawlers, floods, slow distributed crawlers, and replayed tracking requests that may not have obvious user-agent or browser fingerprint signals.</Step>@@ -176,7 +191,7 @@ Because multiple layers can match the same request, per-layer bot counts can add## Server-Side Tracking-Requests sent to `/api/track` with `Authorization: Bearer <api key>` and a valid API key are treated as trusted server-side ingestion. Four of the five layers are skipped: the headers, the client signals, the network address, and the request rate all belong to your server, not to the visitor it is reporting, so scoring them would convict your own backend.+Requests sent to `/api/track` with `Authorization: Bearer <api key>` and a valid key for the site with the `ingest:write` scope (or an unrestricted key) are treated as trusted server-side ingestion. Four of the five layers are skipped: the headers, the client signals, the network address, and the request rate all belong to your server, not to the visitor it is reporting, so scoring them would convict your own backend.The user-agent layer still runs, on the `user_agent` you send. Nothing changes for ordinary backend events β a request reporting a real browser's user agent is tracked normally.@@ -195,7 +210,7 @@ If you want to see them, report them from the edge β middleware, a worker, or}```-A forwarded crawler user agent is classified and lands in your bot events with full identity, rather than in your analytics as a phantom visitor.+With **Block Bot Traffic** on, a forwarded crawler user agent is classified and lands in your bot events with full identity, rather than in your analytics as a phantom visitor. With blocking off, it is tracked as a normal visit.<Callout type="warn">Do not expose API keys in browser JavaScript. API keys are only for server-side requests.@@ -212,7 +227,9 @@ X-Real-IP: <visitor-ip>Also preserve the original `User-Agent`, `Referer`, and `Accept-Language` headers where possible.-If the proxy IP is sent instead of the visitor IP, traffic may be geolocated to the proxy location and may inherit the proxy provider's ASN.+If the proxy IP is sent instead of the visitor IP, traffic may be geolocated to the proxy location, may inherit the proxy provider's ASN, and many visitors can look like one busy address to the rate layer.++Then turn on **First-Party Proxy** in **Site Settings**. It tells Rybbit to read the visitor IP from the forwarded headers (`X-Real-IP`, then `X-Forwarded-For`) instead of inferring whether a proxy is in front.See the [proxy troubleshooting guide](/docs/proxy-guide/troubleshooting) for examples.diff --git a/docs/content/docs/(docs)/comparison.mdx b/docs/content/docs/(docs)/comparison.mdxindex cffe385af..2017865d4 100644--- a/docs/content/docs/(docs)/comparison.mdx+++ b/docs/content/docs/(docs)/comparison.mdx@@ -13,10 +13,10 @@ import { Check, Minus } from 'lucide-react';| **Cookieless & Privacy friendly** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> || **Advanced Maps** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> || **Advanced Filters** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <span className="inline-flex items-center gap-1">Limited</span> | <span className="inline-flex items-center gap-1">Limited</span> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |-| **Web Vitals** | <span className="inline-flex items-center gap-1">Paid</span> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Web Vitals** | <span className="inline-flex items-center gap-1">Cloud</span> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> || **Session Details** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> || **User Profiles** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |-| **Session Replays** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Session Replays** | <span className="inline-flex items-center gap-1">Pro</span> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> || **Funnels** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <span className="inline-flex items-center gap-1">Paid</span> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> || **User Journeys** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> || **Retention Analysis** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |@@ -29,3 +29,19 @@ import { Check, Minus } from 'lucide-react';| **Frog πΈ** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |\* Plausible's Community Edition has very limited features compared to their cloud version++In the Rybbit column, a check means the feature is in every current Rybbit Cloud plan (Standard and up) and in self-hosted Rybbit. **Pro** means the Pro plan on Rybbit Cloud; it's included when you self-host. **Cloud** means Rybbit Cloud only (custom dashboards and SQL can also be turned on in a self-built client image; see [that page](/docs/dashboards)). See [Billing](/docs/billing-settings) for plan details.++## Also in Rybbit++| Feature | Rybbit |+| ------- | ------ |+| **[Saved segments](/docs/segments)** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> |+| **[Chart annotations](/docs/annotations)** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> |+| **[Bot detection](/docs/bot-detection)** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> |+| **[Data import](/docs/data-import)** (Umami, Simple Analytics, Plausible) | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> |+| **[MCP server](/docs/mcp)** for AI assistants | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> |+| **[Custom dashboards and SQL](/docs/dashboards)** | <span className="inline-flex items-center gap-1">Cloud</span> |+| **[Bots page](/docs/feature-guides/bots)** (AI crawler and agent reports) | <span className="inline-flex items-center gap-1">Cloud</span> |+| **Google Search Console** on the dashboard | <span className="inline-flex items-center gap-1">Cloud</span> |+diff --git a/docs/content/docs/(docs)/dashboards.mdx b/docs/content/docs/(docs)/dashboards.mdxnew file mode 100644index 000000000..264508841--- /dev/null+++ b/docs/content/docs/(docs)/dashboards.mdx@@ -0,0 +1,74 @@+---+title: Custom dashboards and SQL+description: Query your raw events with SQL and build dashboards from the results+---++import { Callout } from 'fumadocs-ui/components/callout';++<Callout>+ Query and Dashboards are available on Rybbit Cloud. You'll find both under **Explore** in the site sidebar. The prebuilt self-hosted images don't include them: they only appear if you set `DEPLOYMENT` and build the client image yourself, because the client reads it at build time.+</Callout>++## Query++The **Query** page runs read-only ClickHouse SQL against the current site's events.++1. Open **Query** in the site sidebar.+2. Write SQL in the editor, or describe what you want in the **What do you want to query?** box and click **Generate** to have it written for you. Generating again refines the current query, so you can ask follow-ups.+3. Click **Run**. Results show in a sortable table below the editor.++Use the format button to tidy the SQL, the **+** button to open more query tabs, and the download button to export results as **CSV** or **JSON**.++### Rules++- Read from `scoped_events`. It holds every event for this site and is the only table you can query. You can define your own CTEs on top of it.+- Queries are read-only. Statements that write, change settings, or read other tables are rejected.+- Results are capped at 1,000 rows, and a query stops after 60 seconds.+- The Query page isn't limited by the date selector. Add your own `timestamp` conditions.++For example:++```sql+SELECT pathname, countIf(type = 'pageview') AS pageviews+FROM scoped_events+GROUP BY pathname+ORDER BY pageviews DESC+LIMIT 100+```++## Dashboards++A dashboard is a grid of cards, and each card runs its own query. Dashboards belong to a site.++### Create a dashboard++1. Open **Dashboards** in the site sidebar and click **New dashboard**.+2. Click **Add card**. Pick one of the built-in examples, or start from a blank card.+3. In the card editor, give the card a title, write or edit its SQL, and run it to see results.+4. Pick a **Chart type**: Line, Area, Bar, Bar list, Donut, Stat, Table, Map, or Calendar. Choose which columns to plot and a **Value format** (Number, Percent, Duration, or Bytes). You can also edit the card as JSON.+5. Click **Save card**, drag and resize cards to arrange the grid, then click **Save**.++A dashboard can have up to 20 cards. To change it later, click **Edit**. In edit mode you can duplicate or remove cards. Press <kbd>β</kbd> <kbd>S</kbd> (<kbd>Ctrl</kbd> <kbd>S</kbd>) to save, or <kbd>Esc</kbd> to cancel.++### Time range++Unlike the Query page, dashboard cards follow the date selector at the top of the dashboard. `scoped_events` only contains events in the selected range, so you don't need to filter by date yourself.++Two tokens help with time series cards:++- `{{bucket}}` becomes the interval chosen in the bucket selector (hour, day, week, and so on).+- `{{tz}}` becomes your timezone, so daily buckets line up with your calendar days.++```sql+SELECT toStartOfInterval(toTimeZone(timestamp, {{tz}}), INTERVAL {{bucket}}) AS time,+ countIf(type = 'pageview') AS pageviews+FROM scoped_events+GROUP BY time+ORDER BY time+```++## Who can use them++Anyone who can view the site can run queries and open its dashboards. Creating, editing, and deleting dashboards needs the Member role or above. Dashboards aren't shown on public dashboards or private share links.++You can also run SQL through the `run_query` tool in the [MCP server](/docs/mcp).diff --git a/docs/content/docs/(docs)/embeds/dashboard.mdx b/docs/content/docs/(docs)/embeds/dashboard.mdxindex f40dc7909..18825d61e 100644--- a/docs/content/docs/(docs)/embeds/dashboard.mdx+++ b/docs/content/docs/(docs)/embeds/dashboard.mdx@@ -26,7 +26,7 @@ Unlike [Widget Embeds](/docs/embeds/widget), dashboard embeds expose the full re## Setup-1. Open your site in the Rybbit dashboard and click the settings icon.+1. Open your site in the Rybbit dashboard and click **Site Settings** at the bottom of the sidebar.2. Go to the **Dashboard Embed** tab.3. Generate a private link if one does not already exist.4. Choose the embed theme: light, dark, or system.diff --git a/docs/content/docs/(docs)/embeds/widget.mdx b/docs/content/docs/(docs)/embeds/widget.mdxindex a9035c986..2f393c41e 100644--- a/docs/content/docs/(docs)/embeds/widget.mdx+++ b/docs/content/docs/(docs)/embeds/widget.mdx@@ -24,7 +24,7 @@ The widget needs a public read-only data endpoint, so you must enable **Widget E## Setup-1. Open your site in the Rybbit dashboard and click the settings icon.+1. Open your site in the Rybbit dashboard and click **Site Settings** at the bottom of the sidebar.2. Go to the **Widget Embeds** tab.3. Toggle **Widget Enabled** on.4. Pick your options: variant, time window, theme, accent color, and display settings.diff --git a/docs/content/docs/(docs)/experiments.mdx b/docs/content/docs/(docs)/experiments.mdxindex beec7ab36..bf82580f1 100644--- a/docs/content/docs/(docs)/experiments.mdx+++ b/docs/content/docs/(docs)/experiments.mdx@@ -20,8 +20,8 @@ An experiment has three moving parts:| Part | What it does || --- | --- || **Assignment** | A multivariate feature flag assigns each visitor to one stable variant (for example `control` or `variant_a`) based on its rollout percentages. |-| **Exposure** | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. The number of distinct sessions exposed to a variant is the denominator for its conversion rate. |-| **Conversion** | The experiment's primary goal β a page visit or a custom event β counts as a conversion for whichever variant the visitor was assigned. |+| **Exposure** | When your code reads the flag with `rybbit.flag()`, Rybbit records an exposure for that variant. A session counts toward the variant it was first exposed to, and the number of exposed sessions is the denominator for its conversion rate. |+| **Conversion** | The experiment's primary goal β a page visit or a custom event β counts as a conversion when it happens in the same session, at or after the session's first exposure. |Because assignment is sticky for a given visitor, a person sees the same variant on repeat visits, which keeps your results consistent.@@ -35,7 +35,7 @@ Open your site in the Rybbit dashboard, go to **Experiments**, and click **New eGive the experiment a **name** and, optionally, a **hypothesis** and **description**. The hypothesis is internal context for your team β something like *"Changing the CTA copy will increase signups."* It does not affect assignment or tracking.-New experiments are created as **drafts** so you can add the implementation code before any traffic is split.+New experiments are created as **drafts**. The status is a label for your team: it does not control traffic (see [Experiment Lifecycle](#experiment-lifecycle)).</Step><Step>@@ -64,7 +64,7 @@ Pick the conversion you want to compare variants against:<Step>### Review and Implement-Review the assignment flag and goal, then create the experiment. Rybbit creates any new flag or goal you configured, connects them, and shows you the **implementation code** for the flag. The experiment stays in **draft** until you start it from the experiment list.+Review the assignment flag and goal, then create the experiment. Rybbit creates any new flag or goal you configured, connects them, and shows you the **implementation code** for the flag. A new flag is created **enabled**, so traffic is split as soon as your code calls `rybbit.flag()`, even while the experiment is still a draft. Ship the implementation code when you want the test to begin.</Step></Steps>@@ -117,7 +117,7 @@ window.rybbit.onReady((rybbit) => {**Page goals** need no extra code β Rybbit counts sessions that reach the goal's path automatically.<Callout type="info">-Use a stable variant for the `rybbit.flag()` fallback (usually `"control"`) so visitors still get a sensible experience before the flag resolves or if the experiment is paused.+Use a stable variant for the `rybbit.flag()` fallback (usually `"control"`) so visitors get a sensible experience before flags resolve. If the flag is disabled, `rybbit.flag()` returns `false` rather than your fallback, so make sure any value other than a test variant renders the control experience, as in the examples above.</Callout>## Reading Results@@ -126,17 +126,20 @@ Each experiment shows a results panel comparing every variant. Results respect t| Metric | Description || --- | --- |-| **Variant** | The variant key, with the **Control** marked as the baseline. |+| **Variant** | The variant key. The variant keyed `control` is the baseline; if there is none, the flag's first variant is. || **Sessions** | Sessions exposed to that variant, alongside the number that converted. || **Conversion rate** | Conversions divided by the number of exposed sessions (the **Sessions** figure) for that variant. || **Lift** | The percentage change in conversion rate relative to the control. Positive lift is shown in green, negative in red. |-| **Confidence** | How confident Rybbit is that the variant's difference from the control is real, based on a two-proportion comparison. |+| **Confidence** | How confident Rybbit is that the variant's difference from the control is real, based on a two-proportion comparison. Shown only once both the variant and the control have at least 30 sessions. |++If no exposures were recorded for the flag (your code never calls `rybbit.flag()` for it), results fall back to sessions that were **assigned** a variant, using the flag values attached to every event. The panel notes when it is showing assigned rather than exposed visitors.Rybbit summarizes the state of each experiment at a glance:-- **Gathering data** β Not enough exposures or conversions yet to draw a conclusion.+- **No conversions yet** β No variant has a conversion in the selected range.+- **Gathering data** β No variant beats the control with 95% confidence yet. A completed experiment in this state shows **No clear winner**.- **Leading** β A variant is outperforming the control with at least **95% confidence**.-- **Winner** β The variant recorded as the winner once the experiment is decided.+- **Winner** β Shown when a winning variant has been recorded on the experiment.<Callout type="warn">Avoid stopping an experiment the moment a variant looks ahead. Let it run until it reaches 95% confidence with a meaningful number of conversions, otherwise early noise can masquerade as a real difference.@@ -144,16 +147,18 @@ Avoid stopping an experiment the moment a variant looks ahead. Let it run until## Experiment Lifecycle-Experiments move through four statuses, which you control from the experiment list:+Experiments have four statuses, which you set from the experiment list with **Start**, **Pause**, and **Complete**:| Status | Meaning || --- | --- |-| **Draft** | Created but not yet collecting results. Add your implementation code here. |-| **Running** | Actively splitting traffic and recording exposures and conversions. |-| **Paused** | Temporarily stopped. Visitors keep their existing assignments. |-| **Completed** | Finished. Use this once you have a result and have shipped (or rolled back) the change. |+| **Draft** | Created, not started. |+| **Running** | Started. Rybbit records when the experiment first started. |+| **Paused** | Marked as paused. |+| **Completed** | Finished. Rybbit records the end time, and a completed experiment can't be restarted. |-Use **Start**, **Pause**, and **Complete** on each experiment to move between states.+<Callout type="warn">+Status is bookkeeping only. It does not start, pause, or stop assignment, exposures, or conversions: the flag keeps serving variants and results keep accruing whatever the status is. To stop splitting traffic, disable the experiment's flag on the **Feature Flags** page (every visitor then gets `false`), or remove the `rybbit.flag()` branch from your code. A flag attached to an experiment can't be deleted until you delete the experiment.+</Callout>## Best Practicesdiff --git a/docs/content/docs/(docs)/feature-flags.mdx b/docs/content/docs/(docs)/feature-flags.mdxindex de06cd502..c3669f3ff 100644--- a/docs/content/docs/(docs)/feature-flags.mdx+++ b/docs/content/docs/(docs)/feature-flags.mdx@@ -119,10 +119,10 @@ If a visitor matches a boolean condition set but falls outside that set's rollou| Query parameter | A specific URL query parameter || Referrer | The document referrer || Language | Browser language, such as `en-US` |-| Country | Visitor country resolved from IP |-| Region | Visitor region resolved from IP |-| City | Visitor city resolved from IP |-| Device type | Device category derived from user agent and screen size |+| Country | Visitor country resolved from the IP of the request that asks for evaluation |+| Region | Visitor region resolved from the same IP |+| City | Visitor city resolved from the same IP |+| Device type | Device category derived from the requesting user agent and the reported screen size || User ID | The identified user ID, falling back to the anonymous visitor ID || User trait | A trait set through `identify()` or `setTraits()` |@@ -145,6 +145,10 @@ The tracking script automatically evaluates client and both-runtime flags when iThe anonymous visitor ID is a random ID that keeps percentage rollouts stable across page loads. As soon as a site has at least one client or both-runtime flag, the script stores it in `localStorage` under `<namespace>-visitor-id` (`rybbit-visitor-id` by default). Sites without feature flags never read or write this visitor-ID key. If you use feature flags on sites with EU visitors, treat this stored ID like a cookie under Art. 5(3) ePrivacy when you assess consent requirements.+Flags are evaluated again after `identify()`, `setTraits()`, and `clearUserId()`, and on every SPA navigation when SPA tracking is on, so path and query targeting follow the current page.++If you serve the script through a [proxy](/docs/proxy-guide), the proxy must also forward `POST /site/:siteId/feature-flags/evaluate` (under the same prefix as your other Rybbit routes). Without it, `rybbit.flag()` returns your fallback.+Use `onReady()` before reading flags if you need the evaluated value during page initialization:```javascript@@ -194,7 +198,7 @@ You can then target flags using **User ID** or **User trait** rules.## Server Runtime-Use server runtime for decisions that should not happen in the browser. The server endpoint returns server and both-runtime flags only.+Use server runtime for decisions that should not happen in the browser. The server endpoint returns server and both-runtime flags only. It requires an [API key](/docs/api/getting-started) with the `flags:read` scope (or an unrestricted key).```POST /api/sites/:siteId/feature-flags/evaluate@@ -248,6 +252,10 @@ POST /api/sites/:siteId/feature-flags/evaluate}}/>+<Callout type="warn">+The body has no IP address or user agent field. Country, region, city, and device type targeting use the IP and `User-Agent` of the request itself, so a call from your backend is evaluated as your server, not as the visitor. Rules on those fields won't match visitors reliably on the server runtime.+</Callout>+<Tabs items={['cURL', 'JavaScript']}><Tab value="cURL">```bash@@ -312,10 +320,13 @@ const newCheckout = data.flags.new_checkout?.value === true;"rolloutPercentage": 100}},+ "featureFlagsEnabled": true,"generatedAt": "2026-05-27T12:00:00.000Z"}```+`featureFlagsEnabled` is `false` (with an empty `flags` object) when the site has no flags for this runtime.+Assignment fields:| Field | Description |diff --git a/docs/content/docs/(docs)/feature-guides/bots.mdx b/docs/content/docs/(docs)/feature-guides/bots.mdxnew file mode 100644index 000000000..42017031d--- /dev/null+++ b/docs/content/docs/(docs)/feature-guides/bots.mdx@@ -0,0 +1,45 @@+---+title: Bots+description: See which bots and AI systems hit your site and how Rybbit caught them+---++import { Callout } from 'fumadocs-ui/components/callout';++The **Bots** page shows the traffic that [bot detection](/docs/bot-detection) kept out of your analytics. Open it from **Bots** under **Traffic** in the site sidebar.++<Callout>+ The Bots page is available on Rybbit Cloud only. Bot requests are only recorded while **Block Bot Traffic** is on in [site settings](/docs/site-settings). **Visits sent back** and **Visits back** come from your regular traffic, so they show either way.+</Callout>++These counts only cover bots that run JavaScript. Crawlers that fetch your HTML and run nothing, which includes most training crawlers, never reach Rybbit unless your server reports them through the [tracking API](/docs/bot-detection#reporting-crawlers-that-never-run-javascript).++The page has two views. Switch between them with the control at the top. Filters and the date selector apply to both.++## AI & agents++The default view answers which AI systems read your site, what they read, and whether they send people back.++- **AI requests**: every request from a named AI system.+- **AI agents**: an assistant opened a page because a person asked it to (ChatGPT-User, Claude-User, Perplexity-User, and similar).+- **AI crawlers**: background crawling to train a model or build an answer-engine index.+- **Visits sent back**: people who arrived on your site from an AI product in this period.++Below the totals:++- A chart of agents and crawlers over time.+- An operators table with **Agent**, **Answer engine**, **Training**, **Total reads**, **Visits back**, and **Reads per visit** for each operator (OpenAI, Anthropic, and so on).+- **AI bots**: tabs for **Bots**, **Purpose**, and **Operators**.+- **Pages read by AI**, with an **Agents only** tab for the pages assistants opened on someone's behalf.++## All bots++This view covers every blocked request, AI or not.++- **Bot requests blocked** and **Bot share of total events**.+- One card per detection layer: **UA pattern**, **Header heuristics**, **Client signals**, **Bot ASN**, and **Rate anomaly**. Click a layer to narrow the chart and breakdowns to requests that layer caught. Click it again to clear it.+- A chart of bot requests over time.+- Breakdowns by referrer, page, device, and location, plus a metadata card with tabs for **Bots**, **Operators**, **Purpose**, **ASN Orgs**, **Categories**, and **UA Patterns**.++A request can match more than one layer. Bots that only matched a broad pattern have no published name and show as **Unnamed**. See [Bot identity](/docs/bot-detection#bot-identity) for what operators and purposes mean.++Blocked bot requests don't count toward your monthly event usage.diff --git a/docs/content/docs/(docs)/feature-guides/errors.mdx b/docs/content/docs/(docs)/feature-guides/errors.mdxindex c501d4877..93de89b04 100644--- a/docs/content/docs/(docs)/feature-guides/errors.mdx+++ b/docs/content/docs/(docs)/feature-guides/errors.mdx@@ -3,23 +3,23 @@ title: Errorsdescription: Track JavaScript errors on your website----The Errors tab shows JavaScript errors occurring on your website, helping you identify and fix bugs that affect user experience.+The Errors tab shows JavaScript errors occurring on your website, helping you identify and fix bugs that affect user experience. On Rybbit Cloud, error tracking needs a Standard plan or higher.## Enabling Error Tracking-Enable error tracking in your [site settings](/docs/site-settings).+Turn on **Error Tracking** in the **Tracking** tab of your [site settings](/docs/site-settings), or click **Enable** on the Errors page if you can configure the site.## Error Information-For each error, you'll see:+Errors are grouped by message. Errors of different types with the same message share one row, which shows one of their types. For each error, you'll see:- **Error Type** - ReferenceError, TypeError, SyntaxError, NetworkError, etc.- **Error Message** - The specific error message-- **Stack Trace** - The chain of function calls that led to the error-- **Affected Sessions** - Number of unique sessions in which this error occurred-- **Occurrence Count** - How many times the error was triggered-Expanding an error shows its individual occurrences, including the timestamp and page for each event.-- **Browser & Device** - Which environments experience this error+- **Occurrences** - How many times the error was triggered+- **Sessions** - Number of unique sessions in which this error occurred+- A sparkline of occurrences over the selected period++Click an error to expand it and see its individual occurrences. Each one shows the timestamp, page, browser, device, and location, plus the stack trace when the browser recorded one. Use **Copy stack trace** to paste it into your issue tracker.## Using Error Datadiff --git a/docs/content/docs/(docs)/feature-guides/events.mdx b/docs/content/docs/(docs)/feature-guides/events.mdxindex 4d3c89215..0a6a2bddf 100644--- a/docs/content/docs/(docs)/feature-guides/events.mdx+++ b/docs/content/docs/(docs)/feature-guides/events.mdx@@ -11,25 +11,41 @@ See the [Track Events guide](/docs/track-events) for implementation details.## Events Page-The events page includes:-- **Events Chart** - Visualize event trends over time-- **Event Log** - Recent individual event occurrences (click any row to open a details sheet)+On Rybbit Cloud the Events page needs a Standard plan or higher.-The **Custom Events List** β all tracked events with counts β lives in the Events section of the main dashboard.+### Stat band-## Event Metrics+The top of the page shows:+- **Events** - Custom events in the selected period+- **Users with an event** - People who sent at least one event, and their share of all users+- **Events per session** - Average events per session+- **Event names** - Distinct event names, and how many are new compared with the comparison period+- **Autocaptured** - Clicks, links, forms, copies, and inputs captured by [autocapture](/docs/autocapture)-For each event in the Custom Events List:-- **Event Name** - The name you assigned to the event-- **Count** - Total times triggered in the selected period-- **Percentage** - Share of total events+### Chart-## Event Properties+The chart groups events by **Event type** or **Event name**. When grouped by name, choose how many of the top events to plot. Click a series in the legend to show or hide it. Pageviews are hidden by default.-In the Custom Events List, click the expand arrow on any event to view its properties. Properties show the key-value pairs attached to events, helping you understand event context (e.g., which product was purchased, what button was clicked).+### Event names table++Every custom event name in the period, with these columns:+- **Event** - The event name. Expand a row to see its properties and their values.+- **Events** - Total times it fired+- **Users** - Distinct users who sent it+- **Per user** - Events per user+- **Trend** - A sparkline of the event over the period+- **Change** - Change against the comparison period, when a comparison is on+- **Last seen** - When it last fired+- **Used in** - The goals and saved funnels built on this event. If nothing uses it yet, **Create goal** turns it into a goal in one step.++Click the filter icon on a row to filter the dashboard to that event. Use **Search event names** to find one.++### Event log++The **Event log** lists individual events, newest first. Click any row to open its details, including properties, page, user, and device. **Live** is on by default: the log shows the latest events, updates every 2 seconds, and ignores the date range you picked (filters still apply). Scroll down to pause it. Turn **Live** off to see only events from the selected period.## Filtering-- Click any event name to filter the dashboard to sessions containing that event+- Filter the dashboard to an event from the Event names table- Use the filter panel to combine event filters with other dimensions-- Filter by time range to analyze event trends+- Change the time range to analyze event trendsdiff --git a/docs/content/docs/(docs)/feature-guides/globe.mdx b/docs/content/docs/(docs)/feature-guides/globe.mdxindex 376b52850..ec7b353ed 100644--- a/docs/content/docs/(docs)/feature-guides/globe.mdx+++ b/docs/content/docs/(docs)/feature-guides/globe.mdx@@ -3,7 +3,7 @@ title: Globedescription: Visualize geographic traffic distribution----The Globe tab shows where your visitors connect from on an interactive map.+The Globe tab shows where your visitors connect from on an interactive map. On Rybbit Cloud, it needs a Standard plan or higher.## View Modes@@ -18,12 +18,13 @@ Same four views as 2D, plus:- Rotate by dragging- Zoom in and out- Traffic hotspots glow+- Pick a map **Style**, such as Standard, Satellite, or Outdoors-The 3D view requires a Mapbox API token. Self-hosted installations need `MAPBOX_TOKEN` in environment variables. Cloud includes this automatically.+The 3D view requires a Mapbox API token. On a self-hosted installation, set `MAPBOX_TOKEN` in your `.env` and run `./restart.sh` (or `docker compose up -d`) so the backend picks it up. Rybbit Cloud includes a token.## Time Controls-Pick date ranges to see how geographic distribution changes over time.+Pick date ranges to see how geographic distribution changes over time. In the **Timeline** view, drag the scrubber or press **Play** to watch sessions appear over the range, and click a session to see its details.## Filteringdiff --git a/docs/content/docs/(docs)/feature-guides/journeys.mdx b/docs/content/docs/(docs)/feature-guides/journeys.mdxindex 43a4e9dfc..1deb0101a 100644--- a/docs/content/docs/(docs)/feature-guides/journeys.mdx+++ b/docs/content/docs/(docs)/feature-guides/journeys.mdx@@ -5,35 +5,56 @@ description: Visualize how users navigate your site-User journeys show the actual paths people take as they move through your website, revealing how they flow from page to page.+User journeys show the actual paths people take as they move through your website, revealing how they flow from page to page. Journeys cover sessions that visit two or more pages, starting from the first page of the session. On Rybbit Cloud, journeys need a Standard plan or higher.++## Controls++- **Goal** - Pick a goal to see how many sessions reach it, and to filter the top paths by it+- **Group pages** - **Exact path** keeps every page separate; **By section** groups pages into their site sections+- **Starts at** and **Ends at** - Only show paths that start or end on a page or pattern. `*` matches one path segment, `**` matches several.+- **Steps** - How many steps deep to map, from 2 to 10+- **Show** - How many top paths to draw++You can also filter each step column by page.++## Stats++The band above the diagram shows **Multi-page sessions**, **Avg path length**, **Top entry page**, **Top exit after 2+ pages**, and, when a goal is selected, the share of sessions that **Reach** it.## Reading the Visualization### Nodes-Each bar represents a page or event. Its height indicates how many users reached that point.+Each bar represents a page. Its height is the number of sessions on the paths shown that reached that point. Click a page name to open it on the [Pages](/docs/feature-guides/pages-tab) tab.### Connections-Lines between nodes show user flow. Thicker connections mean more users took that path.+Lines between nodes show the flow. Thicker connections mean more sessions took that path.### Flow Direction-The visualization flows left to right, showing progression through time.+The visualization flows left to right, from the first page of the session onward.++### Pinning a path+Click a path to pin it. The pinned path shows, step by step, how many sessions got that far and how many continued. Click **Unpin path** to clear it.++## Top Paths++Below the diagram, **Top paths** lists the most common exact page sequences with their sessions, share, and change against the comparison period. Use **Filter paths by page** to find paths that contain a page, and, when a goal is selected, choose **All paths**, **Reach** the goal, or **Never reach it**.++Each path has these actions:++- **Sessions** - List the sessions that took the path. Switch to **With a replay** to see only sessions you can watch.+- **Replays** - List replays of sessions on the path, when [session replay](/docs/feature-guides/session-replay) is on+- **Save as funnel** - Open **Create Funnel** with the path as the steps, so you can save it as a [funnel](/docs/funnels)## Key Patterns to Look For- **Happy Path** - The most common route to conversion-- **Drop-off Points** - Where many users enter but few continue-- **Backtracking** - Users moving backward, often indicating confusion+- **Drop-off Points** - Where many sessions enter but few continue+- **Backtracking** - Sessions moving backward, often indicating confusion- **Alternative Routes** - Unexpected paths to important pages## Using Journey Insights- **Simplify complex paths** - Create shortcuts to important pages-- **Fix drop-off points** - Investigate why users leave at certain pages+- **Fix drop-off points** - Investigate why visitors leave at certain pages- **Amplify successful paths** - Make high-converting routes easier to follow-- **Reduce backtracking** - Improve navigation where users get lost--## Analysis Types--- **Entry point analysis** - Where do users go from a specific page?-- **Goal-based analysis** - How did converting users get there?-- **Full journey mapping** - Overall flow from entry to exit+- **Reduce backtracking** - Improve navigation where visitors get lostdiff --git a/docs/content/docs/(docs)/feature-guides/main-tab.mdx b/docs/content/docs/(docs)/feature-guides/main-tab.mdxindex 6199dcfa3..b37746ae3 100644--- a/docs/content/docs/(docs)/feature-guides/main-tab.mdx+++ b/docs/content/docs/(docs)/feature-guides/main-tab.mdx@@ -10,15 +10,40 @@ The main dashboard is your home base in Rybbit Analytics, showing all key metric## Top Metrics- **Unique Users** - Different people who visited your site-- **Total Sessions** - Number of visits (30-minute inactivity starts a new session)-- **Total Pageviews** - Every page load from every visitor+- **Sessions** - Number of visits (30 minutes of inactivity starts a new session)+- **Pageviews** - Every page load from every visitor+- **Pages per Session** - Average pages viewed per visit- **Bounce Rate** - Percentage of single-page sessions-- **Pages Per Session** - Average pages viewed per visit- **Session Duration** - Average time spent per visit+Click a metric to plot it on the main chart.+## Time Controls-Select date ranges: Today, Yesterday, Last 7/30/60 days, This Week, This Month, All Time, or a custom range.+The date selector offers these presets: **Last 30 Minutes**, **Last 24 Hours**, **Today**, **Yesterday**, **Last 7 Days**, **Last 30 Days**, **This Week**, **This Month**, **This Year**, and **All Time**. Use **Custom range** to pick dates in the calendar.++To get any other window counted back from now, type it into the selector's search box, for example `90m`, `6h`, `60d`, or `2w`. Minutes and hours go up to a week; days and weeks go up to a year.++Each preset except This Week has a single-key shortcut when you're not typing in a field:++| Key | Range |+| --- | --- |+| `D` | Today |+| `E` | Yesterday |+| `H` | Last 24 Hours |+| `W` | Last 7 Days |+| `T` | Last 30 Days |+| `M` | This Month |+| `Y` | This Year |+| `A` | All Time |+| `R` | Last 30 Minutes |+| `C` | Custom range |++See [keyboard shortcuts](/docs/keyboard-shortcuts) for the full list.++### Comparison++Compare the current range against another one. Choose **Previous period**, **Matching weekdays**, **Same period last year**, or **Custom range**, or **No comparison** to turn it off. The comparison shows on the chart and in the change figures on the top metrics.## Filters@@ -32,27 +57,27 @@ A set of filters you use often can be saved as a [segment](/docs/segments) from## Main Chart-Shows your selected metric over time. Click the metric selector to switch between Users, Sessions, Pageviews, Bounce Rate, Pages Per Session, or Session Duration.+Shows the selected metric over time. Pick the time bucket (from **Min** up to **Year**) next to the chart. Drag across the chart to zoom into that range; double-click to zoom back out.-## Traffic Sources+### Annotations-See where your traffic comes from:-- **Direct** - Typed URL or bookmarks-- **Search** - Google, Bing, DuckDuckGo, etc.-- **Social** - Twitter, Facebook, LinkedIn, Reddit-- **Referral** - Other websites+Click **Annotate**, or click a point on the chart, to pin a note to a moment, such as a launch, a deploy, or an outage. Pins appear along the chart; hover or click one to read it. See [Annotations](/docs/annotations).-Click any source to filter the entire dashboard to that traffic.+## Referrers and Channels-## UTM Parameters+The **Referrers** tab lists the sites that sent you traffic. The **Channels** tab groups every visit into one of 29 channels based on its referrer and UTM tags: Direct, Organic Search, Paid Search, Organic Social, Paid Social, AI, Paid AI, Email, SMS, Push, Referral, Affiliate, Display, Cross-Network, Organic Video, Paid Video, Organic Shopping, Paid Shopping, Audio, Paid Audio, Influencer, Paid Influencer, News, Content, Productivity, Event, Internal, Paid Unknown, and Unknown.-View campaign data: utm_campaign, utm_source, utm_medium, utm_term, utm_content.+The **Source**, **Medium**, **Campaign**, **Term**, and **Content** tabs show UTM parameters.++Click any row to filter the entire dashboard to that traffic.## Additional Breakdowns-- **Top Pages** - Most visited URLs with pageviews, visitors, time on page, and bounce rate-- **Entry/Exit Pages** - Where visits begin and end-- **Devices & Browsers** - Desktop/mobile/tablet split, browser and OS breakdown-- **Screen Resolutions** - What sizes your visitors use-- **Geographic Data** - Countries and regions-- **Custom Events** - Click any event to filter to sessions containing it+- **Pages** - Most visited paths, plus tabs for **Titles**, **Entries**, **Exits**, and **Hostnames**+- **Devices** - **Browsers**, **Devices**, **Operating Systems**, and **Screen Dimensions**+- **Countries** - **Countries**, **Regions**, **Cities**, **Languages**, **Timezones**, and a **Map**+- **Events** - **Custom Events** and **Outbound** links, plus **Buttons**, **Forms**, and **Copies** when [autocapture](/docs/autocapture) is on+- **Weekly Trends** - A heatmap of the selected metric by weekday and hour+- **Search Console** (Rybbit Cloud) - **Keywords**, **Pages**, **Countries**, and **Devices** from Google Search Console, once you connect it with **Connect Google Search Console**++Click any row to filter the dashboard to it.diff --git a/docs/content/docs/(docs)/feature-guides/meta.json b/docs/content/docs/(docs)/feature-guides/meta.jsonindex 3dff67352..de3512838 100644--- a/docs/content/docs/(docs)/feature-guides/meta.json+++ b/docs/content/docs/(docs)/feature-guides/meta.json@@ -2,6 +2,7 @@"title": "Feature Guides","pages": ["errors",+ "bots","events","globe","journeys",diff --git a/docs/content/docs/(docs)/feature-guides/pages-tab.mdx b/docs/content/docs/(docs)/feature-guides/pages-tab.mdxindex 2ae71d7cd..860f36d5b 100644--- a/docs/content/docs/(docs)/feature-guides/pages-tab.mdx+++ b/docs/content/docs/(docs)/feature-guides/pages-tab.mdx@@ -5,24 +5,43 @@ description: Analyze page performance-The Pages tab shows detailed analytics for every URL on your site.+The Pages tab shows detailed analytics for every URL on your site. It is available on Rybbit Cloud, on the Standard plan or higher.-## Page Metrics+## Stat Band-Each page displays:-- **Page URL** - The full path-- **Sessions** - Number of sessions that viewed this page-- **Average Time on Page** - How long visitors spend there+The top of the page shows **Pageviews**, **Pages with traffic**, **Views per session**, **Avg time on page** (exit views excluded), and **Entry bounce rate**.++## Pages Table++Each row shows:+- **Views** - Pageviews in the selected period+- **Sessions** - Sessions that viewed the page+- **Entries** - Sessions that started on the page+- **Exits** - Sessions that ended on the page+- **Avg time** - Average time on page+- **Bounce** - Entry bounce rate: sessions that started here and viewed nothing else+- **Change** - Change in views against the comparison period, when a comparison is on+- **Trend** - Views over the period++Click a column header to sort. Use **Search title or path** to find a page.++### Entry and exit pages++Switch between **All pages**, **Entry pages**, and **Exit pages** to list every page, only pages where sessions started, or only pages where they ended.++### Sections++By default the table groups pages by section (the first part of the path), so `/blog/a` and `/blog/b` roll up under `/blog/`. Expand a section to see its pages, or use **Expand all**. Set the breakdown to **None** to list every page flat. Searching always lists matching pages individually.## Filtering-Use the same filters as the main dashboard to analyze specific segments:+Click a page to filter the dashboard to it. Use the same filters as the main dashboard to analyze specific segments:- Mobile users from social media- Desktop users who converted- Users who triggered specific events## Identifying Issues-- Scan for pages with low time on page to find content that isn't engaging-- Look for pages with few sessions to find underperforming pages-- Compare entry pages to see which content attracts traffic+- Sort by **Bounce** to find entry pages that lose visitors right away+- Sort by **Exits** to see where sessions end+- Use **Change** with a comparison period to spot pages gaining or losing trafficdiff --git a/docs/content/docs/(docs)/feature-guides/performance.mdx b/docs/content/docs/(docs)/feature-guides/performance.mdxindex eb62ce36d..fcc4997c2 100644--- a/docs/content/docs/(docs)/feature-guides/performance.mdx+++ b/docs/content/docs/(docs)/feature-guides/performance.mdx@@ -5,11 +5,11 @@ description: Track Core Web Vitals and site speed-The Performance tab tracks Core Web Vitals from real user data.+The Performance tab tracks Core Web Vitals from real user data. It is available on Rybbit Cloud, on the Standard plan or higher, for websites (not mobile apps).## Enabling Performance Tracking-Enable Web Vitals in your [site settings](/docs/site-settings).+Turn on **Web Vitals** in the **Tracking** tab of your [site settings](/docs/site-settings), or click **Enable** on the Performance page if you can configure the site. Web Vitals events count toward your monthly event usage.## Web Vitals@@ -43,9 +43,13 @@ How long until the server responds.- **Needs Improvement**: 800-1800ms- **Poor**: Over 1800ms-## Percentile Selector+## Percentiles-Choose which percentile to view (p50, p75, p90, p99). The p75 is commonly used for Core Web Vitals assessment.+Choose which percentile the metric cards show (p50, p75, p90, p99). p75 is the default and is what Core Web Vitals assessments use. On the chart, toggle each percentile on or off to compare them.++## Annotations++Click **Annotations** to show your [annotations](/docs/annotations) on the performance chart, so you can line up a change in speed with a deploy or launch.## Comparison@@ -53,7 +57,8 @@ Each metric shows the change from the previous period, with green indicating imp## Breakdowns-- **By Page** - Find your slowest pages-- **By Device** - Compare mobile vs desktop performance-- **By Browser** - Identify browser-specific issues-- **By Country** - See geographic performance differences+- **Pages** - Find your slowest pages+- **Countries**, **Regions**, and **Map** - See geographic performance differences+- **Devices** - Compare mobile vs desktop performance+- **Browsers** - Identify browser-specific issues+- **Operating systems** - Compare performance across operating systemsdiff --git a/docs/content/docs/(docs)/feature-guides/retention.mdx b/docs/content/docs/(docs)/feature-guides/retention.mdxindex 9a921bc94..9e1dd2f53 100644--- a/docs/content/docs/(docs)/feature-guides/retention.mdx+++ b/docs/content/docs/(docs)/feature-guides/retention.mdx@@ -5,27 +5,38 @@ description: Measure how many users return over time-Retention analysis shows how many users come back to your site over time, revealing whether users find lasting value.+Retention analysis shows how many users come back to your site over time, revealing whether users find lasting value. On Rybbit Cloud, retention needs a Standard plan or higher.## Understanding Cohorts-A cohort is a group of users who share a common start date. For example, all users who first visited on January 15th form one cohort.+A cohort is a group of new users who share a first-visit date. For example, all users who first visited on January 15th form one cohort. A user counts as new if they had no visit in the 90 days before the selected range. Someone returning after a longer gap counts as new again. Filters apply to each user's first visit.++Switch **Cohort period** between **Daily** and **Weekly**. Weekly cohorts start on Monday.++## Stats++The band at the top shows the average retention for the first periods (for example **Day 1 retention**), **Avg. cohort size**, and **Best cohort**: the cohort with the highest day 1 or week 1 retention among cohorts at least half the average size. With a comparison period on, each figure shows its change.++The chart shows average retention by period since first visit. Day 0 (or Week 0) is always 100%, so the curve starts at period 1.## Reading the Retention Table### Rows-Each row is a different cohort, grouped by first visit date.+Each row is a cohort, grouped by first visit date.### Columns- **Day/Week 0** - Starting point (always 100%)-- **Day/Week 1, 2, 3...** - Users who returned after that period+- **Day/Week 1, 2, 3...** - Users who were active again in that period### Numbers-Percentages show what portion of the original cohort returned. 40% in the "Day 7" column means 40% of users came back after a week.+Use **Show cells as** to switch between percentages (**%**) and **Users**. 40% in the "Day 7" column means 40% of that cohort was active again seven days after their first visit. Click a cell for details on who came back.++Cells for periods that haven't finished yet are marked as in progress, and their figures can still rise.### Color Coding-- Lighter colors = higher retention-- Darker colors = more drop-off+Stronger color means higher retention. The legend above the table shows the scale.++Click **Export CSV** to download the table.## Key Insightsdiff --git a/docs/content/docs/(docs)/feature-guides/session-replay.mdx b/docs/content/docs/(docs)/feature-guides/session-replay.mdxindex 77ab09079..9cdbde6e6 100644--- a/docs/content/docs/(docs)/feature-guides/session-replay.mdx+++ b/docs/content/docs/(docs)/feature-guides/session-replay.mdx@@ -11,14 +11,22 @@ Session replay lets you watch anonymized recordings of real user sessions, showiEnable session replay in your [site settings](/docs/site-settings). The tracking script picks the setting up automatically β no script tag changes are needed. (Script-tag attributes like `data-replay-batch-size` and the `data-replay-mask-*` options only tune replay behavior; the on/off switch lives in site settings.)+On Rybbit Cloud, session replay is a Pro feature. Pro trials with a monthly limit of 500,000 events or more don't include replay. Self-hosted instances have no plan gate.++Recording makes the tracking script about 8x larger and sends more data from the browser, so only turn it on if you plan to watch replays.+## What You'll See- Mouse movements and clicks- Scrolling behavior- Page navigation-- Form interactions (with PII masked)+- Form interactions (inputs masked by default)- User details: country, device, browser+Next to the player, the **Timeline** lists what happened in the session: clicks, rage clicks, navigations, typing, and window resizes. Switch between **Key** and **All** to change how much detail it shows. Use the **Min Duration** filter on the Replay page to hide short sessions.++While a replay plays, press `β` or `β` to skip 10 seconds and `Space` to play or pause. See [keyboard shortcuts](/docs/keyboard-shortcuts).+## Using Session Replay- **UX optimization** - Identify where users get stuck or confused@@ -28,4 +36,16 @@ Enable session replay in your [site settings](/docs/site-settings). The tracking## Privacy-Session replay automatically masks sensitive information. Enable PII protection in your settings for additional masking of form inputs and text content.+There is no masking switch in site settings. You control masking with attributes on the script tag:++- `data-replay-mask-all-inputs` masks every input value. It is on by default; set it to `"false"` to record input values.+- `data-replay-mask-text-selectors` takes a JSON array of CSS selectors whose text is masked, for example `'[".user-name", "#email"]'`.+- `data-replay-block-selector` and the `rr-block` class leave elements out of the recording entirely.++See the [script reference](/docs/script) for every `data-replay-*` option.++## Limits++Rybbit stops storing a session's replay once it reaches 50 MB. The rest of the session still shows up in your analytics; only the recording stops. On a self-hosted instance you can change the cap with the `SESSION_REPLAY_MAX_MB_PER_SESSION` environment variable (`0` turns it off).++On Rybbit Cloud, each plan also has a monthly replay quota: the number of recorded sessions is capped at 10% of the plan's monthly event limit (for example, 10,000 replays on a 100,000-event plan). The quota covers all sites in the organization and resets at the start of each calendar month. Once it's used up, new replays aren't recorded until the next month, but the rest of your analytics keeps working. Self-hosted instances have no replay quota.diff --git a/docs/content/docs/(docs)/feature-guides/sessions.mdx b/docs/content/docs/(docs)/feature-guides/sessions.mdxindex a3e6e64fe..8fe2a9012 100644--- a/docs/content/docs/(docs)/feature-guides/sessions.mdx+++ b/docs/content/docs/(docs)/feature-guides/sessions.mdx@@ -3,29 +3,39 @@ title: Sessionsdescription: Analyze individual user sessions----The Sessions tab shows individual user visits to your website, including all page views, interactions, and events during each session.+The Sessions tab shows individual visits to your website, including all page views, interactions, and events during each session. On Rybbit Cloud, it needs a Standard plan or higher.-## Session Metrics+## Stats-Each session displays:+The band at the top shows **Sessions**, **Avg duration**, **Pages per session**, **Bounce rate**, **Converted** (sessions that completed any [goal](/docs/goals)), and **With errors**.-- **Duration** - Time spent on site-- **Pages Visited** - Number of pages viewed-- **Events Triggered** - Custom events fired during the session-- **Device & Browser** - Technical environment-- **Location** - Geographic location based on IP-- **Entry/Exit Page** - Where the session started and ended-- **Bounce Status** - Whether the user left after one page+## Session List++Sessions are listed by day, newest first. Each row shows:++- The user, and their location and device+- **Entry and exit page** - Where the session started and ended, or "single page" if it bounced+- Channel and source+- Pages, events, and duration+- JavaScript errors, if any+- Goals the session completed++Click a page or channel in a row to filter by it. Expand a row to see the session's timeline and counts of custom events, button clicks, copies, form submits, and input changes. Click **Watch replay** to open the session's [replay](/docs/feature-guides/session-replay), when it has one.++Use **Sort** to order by **Started**, **Duration**, **Pages**, **Events**, or **Errors**.## Filtering Sessions-Filter by:+Use the view tabs to show **All** sessions, or only **Identified**, **Has replay**, **Converted**, **Bounced**, or **With errors** sessions.++Set a range for **Pageviews**, **Events**, or **Duration** (for example, at least 3 pages or at most 30 seconds). These combine with the standard dashboard filters:-- Duration, pages visited, or events triggered- Device type, browser, or location- Referrer or traffic source- Date range+Click **Save as segment** to keep the current filters as a [segment](/docs/segments).+## Session Replay-If [session replay](/docs/product-analytics/replay-session) is enabled, you can watch a recording of any session to see exactly what the user did.+If [session replay](/docs/feature-guides/session-replay) is enabled, you can watch a recording of any session that has one to see exactly what the user did.diff --git a/docs/content/docs/(docs)/feature-guides/users.mdx b/docs/content/docs/(docs)/feature-guides/users.mdxindex 25eadd153..685ae31d2 100644--- a/docs/content/docs/(docs)/feature-guides/users.mdx+++ b/docs/content/docs/(docs)/feature-guides/users.mdx@@ -3,19 +3,31 @@ title: Usersdescription: Analyze individual users across sessions----The Users tab shows unique visitors and their behavior across multiple sessions.+The Users tab shows unique visitors and their behavior across multiple sessions. On Rybbit Cloud, it needs a Standard plan or higher.-## User Metrics+## Stats-For each user, you'll see:+The band at the top shows:-- **User ID** - Anonymized identifier-- **First/Last Visit** - When they first and most recently visited-- **Total Sessions** - Number of separate visits-- **Pages Viewed** - Total pages across all sessions-- **Events Triggered** - Total custom events-- **Device Type** - Desktop, mobile, or tablet-- **Location** - Geographic location+- **Users** - Users active in the period+- **Identified** - Users you've [identified](/docs/identify-users), and their share of all users+- **New** - Users with no visit in the 90 days before the period. Someone returning after a longer gap counts as new.+- **Returning** - Users who also visited in the days before the period+- **Sessions per user** - Average sessions per user+- **Active now** - Users seen in the last few minutes++## Users Table++Each row is a user, with these columns:++- **Last seen** and **First seen**+- **Sessions**, **Pageviews**, and **Events** in the period+- **First source** - Where the user first came from+- **Location** and **Device**++Use **Columns** to choose which columns to show, including any [traits](/docs/identify-users) you've sent. Click a column header to sort.++Use the quick filters to narrow the list to **Identified** users, **New** users, or **Power users** (users with at least a set number of sessions in the period; hover the filter to see the number). Search identified users by **Name**, **Username**, **Email**, or **User ID**.## Filtering Users@@ -28,6 +40,21 @@ Filter by the standard dimension filters:Session count, pageviews, events, and first/last seen aren't filters, but you can sort the user list by those columns.+## User Profiles++Click a user to open their profile. It shows:++- **Traits** for identified users. Click **Edit traits** to change them.+- **Activity** - The days the user started a session, and their sessions in the range+- **Goals completed** in the period+- **Journeys** - The first pages of each of their sessions+- **Top pages** and events+- **Acquisition** - First touch and latest channel+- **Location & device** - Where they visit from and what they use+- **Segments** the user belongs to++Use **Identify User** to attach your own user ID to an anonymous visitor, and **Delete User** to remove a user's data.+## Identified UsersIf you use the [identify API](/docs/identify-users), you can see your own user IDs alongside the anonymous identifiers.diff --git a/docs/content/docs/(docs)/filter-traffic.mdx b/docs/content/docs/(docs)/filter-traffic.mdxindex 4d47f54e9..c5992476f 100644--- a/docs/content/docs/(docs)/filter-traffic.mdx+++ b/docs/content/docs/(docs)/filter-traffic.mdx@@ -1,6 +1,6 @@---title: Filter traffic-description: Exclude traffic by IP address, country, path, hostname, or user agent+description: Exclude traffic by IP address, network (ASN), country, path, query parameter, hostname, or user agent---import { Callout } from 'fumadocs-ui/components/callout';@@ -15,7 +15,9 @@ Filters are configured from **Site Settings β Exclusions**.| --- | --- | --- | --- || **IP Exclusions** | Your home, office, VPN, or internal network traffic | Single IPs, CIDR ranges, and IPv4 ranges | 100 entries || **Country Exclusions** | Regional filtering or compliance requirements | Two-letter ISO country codes, such as `US`, `GB`, or `DE` | 250 entries |+| **ASN Exclusions** | A corporate VPN, a hosting provider, or another whole network | Autonomous system numbers, with or without the `AS` prefix | 100 entries || **Path Exclusions** | Admin pages, private pages, preview routes, or test pages | Case-insensitive glob patterns using `*` | 100 entries |+| **Query Param Exclusions** | Preview links, internal UTM tags, test flags in the URL | A parameter name, or `name=value` with `*` in the value | 100 entries || **Hostname Exclusions** | Localhost, staging domains, preview deployments, or temporary domains | Case-insensitive glob patterns using `*` | 100 entries || **User Agent Exclusions** | Monitoring tools, headless browsers, or custom crawlers | Case-insensitive substring matching | 100 entries |@@ -32,8 +34,16 @@ Supported formats:- **CIDR notation**: `192.168.1.0/24`, `2001:db8::/32`- **IPv4 ranges**: `192.168.1.1-192.168.1.10`+IP exclusions are checked against every client IP the request reports in its headers (`CF-Connecting-IP`, `X-Real-IP`, and each `X-Forwarded-For` entry), not only the IP Rybbit resolves as the visitor's. The address of the direct network connection is not checked when forwarding headers are present. That keeps "exclude my own IP" working behind proxies, at the cost of also excluding anyone whose request passes through an excluded address.+For setup instructions and best practices, see [Hiding Your Own Traffic](/docs/hiding-own-traffic).+## ASN Exclusions++Exclude every request from a network, identified by its autonomous system number. Enter `AS13335` or `13335`. Like IP exclusions, ASN exclusions match if any of those client IPs belongs to an excluded network.++Use this for networks that don't have a stable IP range you can list, such as a corporate VPN or a hosting provider that sends you unwanted traffic. Excluding a large consumer ISP or mobile carrier removes real visitors too.+## Country ExclusionsBlock all traffic geolocated to specific countries. Rybbit resolves the visitor IP address with the MaxMind GeoLite2 database, then compares the resulting country code to your exclusion list.@@ -75,6 +85,26 @@ Use path exclusions for pages that should not appear in analytics at all, such aFor client-side-only pageview skipping, you can also use the tracking script's `data-skip-patterns` option. Site-level path exclusions are enforced on the server and also apply to session replay ingestion.</Callout>+## Query Param Exclusions++Exclude page URLs that carry a specific query parameter.++Examples:++```txt+preview+utm_source=internal+ref=test-*+```++- A name on its own (`preview`) matches whenever the parameter is present, whatever its value.+- `name=value` matches only that value. The value supports `*` wildcards.+- Parameter names and values match case-insensitively.++<Callout type="warning">+Query param exclusions need **URL Parameters** tracking turned on for the site. With it off, analytics events are sent without their query string, so these exclusions don't match them. Session replay batches still carry the full page URL, so replay from a matching URL is still excluded.+</Callout>+## Hostname ExclusionsExclude traffic from specific hostnames. This is useful when the same site ID is used across production, staging, preview, and local environments.@@ -122,10 +152,12 @@ Traffic filters run before normal analytics data is stored. They apply to:Rybbit checks exclusions in this order:1. IP address-2. Country-3. Path-4. Hostname-5. User agent+2. ASN+3. Country+4. Path+5. Query parameter+6. Hostname+7. User agentIf any filter matches, the event is accepted with a `200` response but is not tracked. Changes usually take effect within 60 seconds because site configuration is cached briefly on the server.diff --git a/docs/content/docs/(docs)/funnels.mdx b/docs/content/docs/(docs)/funnels.mdxindex 4aa0cbf4f..5272a2765 100644--- a/docs/content/docs/(docs)/funnels.mdx+++ b/docs/content/docs/(docs)/funnels.mdx@@ -9,12 +9,14 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';Funnels let you define a sequence of steps β page visits, custom events, or autocaptured interactions β and measure how many users progress through each stage. You can see where users convert, where they drop off, and drill into the sessions at each step to understand why.+On Rybbit Cloud, funnels need a Standard plan or higher.+## Creating a Funnel<Steps><Step>-### Click "Create Funnel"+### Click "Create funnel"Each funnel has:- **Name** β A label for the funnel (e.g., "Signup Flow", "Checkout Process")@@ -85,39 +87,54 @@ Button click, form interaction, and copy tracking are disabled by default. Enabl-Each step has additional configuration options:+Click **Show advanced options** on a step to configure:- **Label** (optional) β A friendly display name for the step- **Hostname** (optional) β Restrict matching to a specific domain, useful for multi-domain sites-- **Property Filters** (optional) β Filter by URL parameters (for path steps) or event properties (for all other step types). Multiple filters can be added per step, and all must match.+- **Property Filters** (optional) β **Filter by URL parameter** (for path steps) or **Filter by event property** (for all other step types). Multiple filters can be added per step, and all must match.</Step></Steps>++You can also build a funnel from a path on the [Journeys](/docs/feature-guides/journeys) page with **Save as funnel**.++## The Funnels List++Saved funnels appear as rows you can expand. A summary band at the top shows **Funnels tracked**, **Sessions entering any funnel**, **Highest conversion**, **Biggest gain** against the comparison period, and **Biggest drop-off**. Use **Sort** to order funnels by **Sessions entered**, **Conversion**, **Change in conversion**, **Name**, or **Date created**, and **Filter funnels** to search by name.++Each expanded funnel has these actions:++- **Explore paths** β Open [Journeys](/docs/feature-guides/journeys) to see the paths sessions actually take+- **Clone** β Copy the funnel as a starting point for a new one+- **Edit funnel** β Change the funnel's name and steps++If the funnel's last step matches one of your [goals](/docs/goals), a **Goal:** link to it appears under that step.+## Reading Funnel Results-The funnel visualization updates in real time as you configure steps. For each step, you'll see:+For each step, you'll see:- **Sessions** β How many sessions reached this step-- **Conversion Rate** β Percentage of the first step's sessions that reached this step-- **Dropped** β How many sessions completed the previous step but not this one-- **Dropoff Rate** β Percentage of the previous step's sessions lost at this point+- **Of start** β Percentage of the first step's sessions that reached this step+- How many sessions dropped off between this step and the next+- The median time from the first step, and to the next step-The horizontal bar for each step shows two layers:-- **Solid bar** β Overall conversion from the first step-- **Striped overlay** β Conversion from the immediately previous step+When a comparison period is on, each step also shows how its numbers changed.Steps are evaluated sequentially β each step must occur after the previous one within the same session.-## Viewing Sessions+## Viewing Sessions and Replays-Click any step to expand it and view the sessions associated with that step:+Click any step row except the last to list the sessions that reached that step.++Next to each drop-off count, and next to the final **converted** count, click:-- **Reached** tab β Sessions that completed this step-- **Dropped Off** tab β Sessions that reached the previous step but didn't make it to this one (available for step 2 and beyond)+- **Sessions** β List the sessions that dropped off after that step, or that converted+- **Replays** β List only those sessions that have a replay, when [session replay](/docs/feature-guides/session-replay) is on-Each session shows entry/exit pages, duration, location, device info, referrer, UTM parameters, and user ID if identified. Sessions are paginated.+Each session shows entry/exit pages, duration, location, device info, referrer, UTM parameters, and user ID if identified.---diff --git a/docs/content/docs/(docs)/goals.mdx b/docs/content/docs/(docs)/goals.mdxindex 6e0b9ca97..701a98be6 100644--- a/docs/content/docs/(docs)/goals.mdx+++ b/docs/content/docs/(docs)/goals.mdx@@ -9,13 +9,15 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';Goals let you define specific actions β from visiting a page to clicking a button β and measure how often your visitors complete them. Each goal tracks a conversion rate against total sessions, giving you a clear picture of how effectively your site drives key outcomes.+On Rybbit Cloud, goals are available on every paid plan.+## Creating a Goal<Steps><Step>-### Click "Create Goal"-Every goal has:+### Click "New goal"+The goal form opens inline at the foot of the goals table. Every goal has:- **Name** (optional) β A friendly label like "Completed Checkout" or "Signed Up"- **Type** β Page, custom event, outbound link, button click, form submission, or copied text@@ -92,33 +94,51 @@ You can narrow a goal to only count conversions when specific properties match:- **Custom event goals** β Filter by event properties (e.g., only count events where `plan=premium`)- **Autocaptured interaction goals** β Filter by captured properties such as `url`, `text`, `formName`, `formId`, or `formAction`-Toggle **Match specific URL parameters** or **Match specific event properties** to add filters. You can add multiple filters per goal β all filters must match for a session to count as a conversion.+Turn on **Match a URL parameter** or **Match an event property** to add filters. You can add multiple filters per goal β all filters must match for a session to count as a conversion.++</Step>+<Step>+### Check the preview and save++As you fill in the form, a preview shows how many sessions would have converted in the selected period, drawn from events you already have. Click **Create goal** to save.</Step></Steps>++To start from an existing goal, open its row menu and choose **Clone goal**. The copy opens in the form with "(Copy)" added to the name. The same menu has **Edit goal** and **Delete goal**.++You can also turn a custom event into a goal from the [Events page](/docs/feature-guides/events) with **Create goal**.+## Goal Metrics-Each goal card displays:+A summary band at the top shows:++- **Sessions** β All sessions in the period, the denominator of every rate+- **Converting sessions** β Sessions that completed at least one goal+- **Goal completions** β Conversions across all goals+- **Best mover** β The goal that gained the most conversions against the comparison period+- **Slipping** β The goal whose conversion rate dropped the most++Below it, each goal is a row in the goals table with:-- **Total Conversions** β The number of distinct sessions that completed the goal-- **Conversion Rate** β Conversions divided by total sessions in the selected time period, shown as a percentage with a visual progress bar+- **Conversions** β The number of distinct sessions that completed the goal+- **Rate** β Conversions divided by total sessions in the selected period+- **Change** β Change in conversions and rate against the comparison period, when a comparison is on+- A trend of conversions over the period-Goals respect the global date range and filters (country, device, browser, etc.) applied on the page.+Click a column header to sort, and use **Filter goals** to find a goal by name. Goals respect the global date range and filters (country, device, browser, etc.) applied on the page.## Viewing Converted Sessions-Click a goal card to expand it and see the sessions that converted. Each session shows:+Click a goal row to expand it. You'll see:-- Entry and exit pages-- Session duration-- Location (country, region, city)-- Device, browser, and OS-- Referrer, channel, and UTM parameters-- User ID (if identified)+- A chart of conversions over time, against the comparison period when one is on+- The funnels that use the goal's page or event, under **Also in**+- **Converted sessions**, most recent first, with each session's pages, duration, location, device, and referrer. Click the replay button on a session to watch it when [session replay](/docs/feature-guides/session-replay) is on.-Sessions are sorted by most recent first and paginated.+Click **Open in Sessions** to see every converted session on the [Sessions](/docs/feature-guides/sessions) page with the goal applied as a filter.---diff --git a/docs/content/docs/(docs)/hiding-own-traffic.mdx b/docs/content/docs/(docs)/hiding-own-traffic.mdxindex e58509f33..cc2e6ff3f 100644--- a/docs/content/docs/(docs)/hiding-own-traffic.mdx+++ b/docs/content/docs/(docs)/hiding-own-traffic.mdx@@ -51,7 +51,8 @@ There are several ways to disable Rybbit tracking to hide your own visits from a- **Server-side filtering**: Traffic is blocked before it reaches your analytics, providing highly accurate exclusion- **Multiple formats**: Supports individual IPs, CIDR notation, and ranges- **IPv4 and IPv6**: Full support for both IP versions- - **Near real-time updates**: Changes take effect within seconds+ - **Fast updates**: Changes take effect within about a minute (site settings are cached briefly on the server)+ - **Forwarded hops count**: Rybbit checks every client IP the request reports in its forwarding headers (such as each `X-Forwarded-For` entry), so your IP is excluded even when it isn't the one Rybbit picks as the visitor's IP- **No browser dependency**: Works regardless of browser or device<Callout type="info">@@ -111,6 +112,10 @@ There are several ways to disable Rybbit tracking to hide your own visits from alocalStorage.setItem('disable-rybbit', 'true');```+ The script only checks that the key exists, so any value works, even `'false'`. If you set `data-namespace` on the script tag, the key is `disable-<namespace>` instead (for example `disable-analytics`). The opt-out applies on the next page load.++ You can also opt out from your own code by setting `window.__RYBBIT_OPTOUT__ = true` before the script loads.+### 3. Re-enable tracking (when needed)If you want to re-enable tracking later, enter:diff --git a/docs/content/docs/(docs)/identify-users.mdx b/docs/content/docs/(docs)/identify-users.mdxindex bf2d91f40..b94dba228 100644--- a/docs/content/docs/(docs)/identify-users.mdx+++ b/docs/content/docs/(docs)/identify-users.mdx@@ -20,7 +20,7 @@ By default, Rybbit assigns an anonymous ID to each visitor based on their device- Store user metadata (traits) like email, name, and custom fields- View identified users in your dashboard with their real names-When a new alias is created (i.e., the first time `identify()` is called for a given device), Rybbit retroactively updates all past anonymous events from that device to include the identified user ID. This means pre-login pageviews and events are attributed to the user once they identify themselves.+When a new alias is created (i.e., the first time `identify()` is called for a given device), Rybbit retroactively updates that device's anonymous events from the last 30 days to include the identified user ID. This means recent pre-login pageviews and events are attributed to the user once they identify themselves. Older events stay anonymous.## Special Trait Fields@@ -45,7 +45,7 @@ You can also include any custom fields you need for segmentation and analysis.Sets a custom user ID for tracking logged-in users across devices and sessions, with optional user traits (metadata).-- `userId` (String): The unique identifier for the user. This will be stored in localStorage and persist across browser sessions. **Note: Custom user IDs are stored exactly as provided without any hashing or modification.**+- `userId` (String): The unique identifier for the user. This will be stored in localStorage and persist across browser sessions. **Note: Custom user IDs are not hashed. Leading and trailing whitespace is trimmed; otherwise the ID is stored as provided.**- `traits` (Object, Optional): An object containing user metadata like email, name, username, or any custom fields. This data is stored in Rybbit and can be used to identify users in the dashboard. Setting a trait to `null` removes it from the user's profile.```javascript@@ -114,7 +114,7 @@ if (currentUserId) {- **Identified sessions**: When a custom user ID is present, session assignment includes both the anonymous device fingerprint and the custom user ID. Different identified users therefore remain in separate sessions even when they share the same IP address and user agent.- **Shared devices**: If multiple users log in from the same device (same IP address and user agent), calling `identify()` with a new user ID updates the alias to point to the new user. Future events will be attributed to the most recently identified user. Past events that were already backfilled retain their original attribution.- **Cross-device tracking**: Identifying the same user on different devices creates separate aliases. Events from each device are linked to the user independently via the `identified_user_id` field.-- **Retroactive backfill**: The backfill runs asynchronously when a new alias is first created. ClickHouse mutations may take a short time to propagate depending on table size. Subsequent `identify()` calls from the same device (even with a different user ID) do not re-backfill old events.+- **Retroactive backfill**: The backfill covers the last 30 days and runs asynchronously when a new alias is first created. Backfills are batched and applied every 5 minutes, so pre-login events can take several minutes (longer on large tables) to show the user. Subsequent `identify()` calls from the same device (even with a different user ID) do not re-backfill old events.- **`clearUserId()` behavior**: Calling `clearUserId()` removes the user ID from localStorage so future events are anonymous. It does not delete the alias in the database or modify previously attributed events.## Complete Examplediff --git a/docs/content/docs/(docs)/index.mdx b/docs/content/docs/(docs)/index.mdxindex 6b2c8579a..fa0271a1e 100644--- a/docs/content/docs/(docs)/index.mdx+++ b/docs/content/docs/(docs)/index.mdx@@ -17,6 +17,15 @@ Choose the option that's right for you:And then learn how to add the [tracking script](/docs/script) to your website to start collecting data.+## Using the dashboard++- [Feature guides](/docs/feature-guides/main-tab) walk through each page of a site's dashboard, from the main dashboard to sessions, replays, errors, and [bots](/docs/feature-guides/bots).+- [Goals](/docs/goals), [funnels](/docs/funnels), and [segments](/docs/segments) turn raw traffic into conversions and saved views.+- [Annotations](/docs/annotations) pin launches, deploys, and outages to the traffic chart.+- [Rollup](/docs/rollup) shows every site in your organization on one page.+- [Custom dashboards and SQL](/docs/dashboards) let you query raw events directly (Rybbit Cloud, or a client image you build yourself).+- [Keyboard shortcuts](/docs/keyboard-shortcuts) cover the <kbd>β</kbd> <kbd>K</kbd> command palette and the date range hotkeys.+## CodeRybbit is open sourced under the AGPL-3.0 license. You can find the code on [GitHub](https://github.com/rybbit-io/rybbit).diff --git a/docs/content/docs/(docs)/inviting-users.mdx b/docs/content/docs/(docs)/inviting-users.mdxindex 97f7bcf98..548ebb4e5 100644--- a/docs/content/docs/(docs)/inviting-users.mdx+++ b/docs/content/docs/(docs)/inviting-users.mdx@@ -6,15 +6,19 @@ description: Invite team members to your Rybbit organization and control their aimport { Steps, Step } from 'fumadocs-ui/components/steps';import { Callout } from 'fumadocs-ui/components/callout';+Only admins and owners can add people to an organization.+<Callout type="info">- On self-hosted instances, this workflow is slightly different. Instead of inviting users, you can create a new user and set their password directly since self-hosted instances don't send emails.+ On self-hosted instances you don't send invitations. Instead, click **Create User** in the **People** section of **Settings > Organization**, enter the person's email, name, password and role, and click **Create User**. The account is created right away. Site restrictions and team assignments aren't part of this dialog: set them afterwards by editing the member (see [below](#managing-site-access-for-existing-members)) or adding them to a [team](/docs/teams). The steps below are for Rybbit Cloud.</Callout><Steps><Step>### Add the user to your organization-Go to **Settings > Organization** and click the "Invite Member" button. Enter the user's email address.+Go to **Settings > Organization** and click **Invite people** in the **People** section. Enter the user's email address.++On Rybbit Cloud your plan limits how many members an organization can have (for example, 3 on Standard and 100 on Pro; see [Billing](/docs/billing-settings#plans-and-limits)). When you reach the limit, the **Invite people** button is disabled until you upgrade.</Step><Step>@@ -32,7 +36,7 @@ See [Member Roles](/docs/organization-settings#member-roles) for the full list.#### Restricting site access-For editors, members and viewers you can restrict access to specific sites. Check "Restrict access to specific sites" and select the sites they should see. If you don't, they can see every site in your organization (except sites that belong to a [team](/docs/teams) they aren't on).+For editors, members and viewers you can restrict access to specific sites. Turn on **Restrict access to specific sites** and select the sites they should see. If you don't, they can see every site in your organization (except sites that belong to a [team](/docs/teams) they aren't on).You can also pick a **role on these sites** to raise their role on the selected sites only. For example, invite a client as a **Viewer**, restricted to their own site, with **Editor** on that site: they can configure their site and nothing else. The site role only ever raises the organization role, never lowers it.@@ -44,7 +48,7 @@ You can also pick a **role on these sites** to raise their role on the selected<Step>### Assign teams (optional)-If your organization has [teams](/docs/teams) set up, you can assign the new member to a team during the invitation. When the member accepts the invitation, they will automatically be added to the selected team.+If your organization has [teams](/docs/teams) set up, you can pick one under **Team** during the invitation. When the member accepts the invitation, they will automatically be added to the selected team.This is useful for ensuring new members immediately have access to the right group of sites without needing to configure access separately.</Step>@@ -52,7 +56,7 @@ This is useful for ensuring new members immediately have access to the right gro<Step>### Send the invite-Click the "Invite" button. The user will receive an email with a link to sign up for Rybbit. You can manage all pending invitations in the Organization settings page.+Click **Invite**. The user receives an email with a link to sign up for Rybbit. Pending invitations appear in the **People** table, marked **Pending**, where you can **Resend** or **Cancel** them.</Step></Steps>@@ -61,12 +65,12 @@ Click the "Invite" button. The user will receive an email with a link to sign upYou can change a member's site access at any time after they've joined your organization.1. Go to **Settings > Organization**-2. Find the member in the list and click the edit (pencil) icon in the Actions column for that member-3. Toggle "Restrict access to specific sites", select the sites they should have access to, and optionally a role on those sites-4. Click "Save changes"+2. Find the member in the **People** table and click the edit (pencil) icon at the end of their row+3. Turn on **Restrict access to specific sites**, select the sites they should have access to, and optionally a **Role on these sites**+4. Click **Save Changes**The member will immediately only see the sites you've selected. If you disable the restriction, they'll regain access to all sites.<Callout type="info">- A person can belong to several organizations, each with its own role. To hand a site over to someone so they can manage it in their own organization, [transfer the site](/docs/site-settings#transfer-site) instead.+ A person can belong to several organizations, each with its own role. To hand a site over to someone so they can manage it in their own organization, [transfer the site](/docs/site-settings#transfer-to-someone-else) instead.</Callout>diff --git a/docs/content/docs/(docs)/keyboard-shortcuts.mdx b/docs/content/docs/(docs)/keyboard-shortcuts.mdxnew file mode 100644index 000000000..44d5a9f69--- /dev/null+++ b/docs/content/docs/(docs)/keyboard-shortcuts.mdx@@ -0,0 +1,75 @@+---+title: Keyboard shortcuts+description: The command palette and every keyboard shortcut in the Rybbit dashboard+---++import { Callout } from 'fumadocs-ui/components/callout';++Rybbit has a command palette for jumping around and single-key shortcuts for the date range. Press <kbd>?</kbd> anywhere in the dashboard to see the full list.++<Callout>+ The command palette and the shortcut sheet are only available when you're signed in. Signed-out visitors to a public dashboard, anyone on a private share link, and embeds don't get them.+</Callout>++## Command palette++Press <kbd>β</kbd> <kbd>K</kbd> on macOS or <kbd>Ctrl</kbd> <kbd>K</kbd> on Windows and Linux. You can also click **Search** at the top of the site sidebar. The shortcut works even while you're typing in a field, and pressing it again closes the palette.++Type to search, use the arrow keys to pick a row, and press <kbd>Enter</kbd> to run it. The palette lists:++- **This site**: every page in the site sidebar you have access to (Main, Pages, Sessions, Goals, Query, and so on). Switching pages keeps your date range and filters.+- **Switch site**: the other sites in your organization. You land on the same page of the other site.+- **Goals**, **Funnels**, and **Dashboards**: the open site's saved goals, funnels, and custom dashboards.+- **Date range**: the date presets, on pages that have a date selector.+- **Navigate**: Home, Rollup, Account, and the Organization, Teams, and Billing settings if your role can open them.+- **Theme**: Light, Dark, or System.+- **Preferences**: opens the keyboard shortcut sheet.++Before you type, the palette shows up to five sites, goals, funnels, and dashboards. Typing searches all of them.++## Shortcut sheet++Press <kbd>?</kbd> to open the **Keyboard shortcuts** sheet. Press <kbd>?</kbd> or <kbd>Esc</kbd> to close it. It doesn't open while you're typing in a field.++### General++| Action | Keys |+| --- | --- |+| Open command palette | <kbd>β</kbd> <kbd>K</kbd> / <kbd>Ctrl</kbd> <kbd>K</kbd> |+| Show keyboard shortcuts | <kbd>?</kbd> |++### Date range++These work on any page with a date selector. They're ignored while you're typing in a field.++| Range | Key |+| --- | --- |+| Last 30 Minutes | <kbd>R</kbd> |+| Last 24 Hours | <kbd>H</kbd> |+| Today | <kbd>D</kbd> |+| Yesterday | <kbd>E</kbd> |+| Last 7 Days | <kbd>W</kbd> |+| Last 30 Days | <kbd>T</kbd> |+| This Month | <kbd>M</kbd> |+| This Year | <kbd>Y</kbd> |+| All Time | <kbd>A</kbd> |+| Custom range | <kbd>C</kbd> |++This Week has no key. The letters follow Plausible's scheme, so they'll feel familiar if you've used it.++### Session replay++| Action | Key |+| --- | --- |+| Back 10 seconds | <kbd>β</kbd> |+| Forward 10 seconds | <kbd>β</kbd> |+| Play or pause | <kbd>Space</kbd> |++### Dashboard editing++While you edit a [custom dashboard](/docs/dashboards):++| Action | Keys |+| --- | --- |+| Save changes | <kbd>β</kbd> <kbd>S</kbd> / <kbd>Ctrl</kbd> <kbd>S</kbd> |+| Cancel editing | <kbd>Esc</kbd> |diff --git a/docs/content/docs/(docs)/meta.json b/docs/content/docs/(docs)/meta.jsonindex 7d1558193..a66d37e3b 100644--- a/docs/content/docs/(docs)/meta.json+++ b/docs/content/docs/(docs)/meta.json@@ -23,10 +23,14 @@"filter-traffic","bot-detection","segments",+ "annotations","goals","funnels",+ "dashboards","embeds",+ "rollup","feature-guides",+ "keyboard-shortcuts","---Self-hosting---","self-hosting","managing-your-installation",diff --git a/docs/content/docs/(docs)/organization-settings.mdx b/docs/content/docs/(docs)/organization-settings.mdxindex 844c07459..f2f5e0a0e 100644--- a/docs/content/docs/(docs)/organization-settings.mdx+++ b/docs/content/docs/(docs)/organization-settings.mdx@@ -5,32 +5,30 @@ description: Manage your organization, team members, roles, and permissionsimport { Callout } from 'fumadocs-ui/components/callout';-Access organization settings by clicking on "Organization" or going to [app.rybbit.io/settings/organization](https://app.rybbit.io/settings/organization).+Open organization settings by clicking **Organization** in the settings sidebar or going to [app.rybbit.io/settings/organization](https://app.rybbit.io/settings/organization). Only admins and owners see the **Organization** and **Teams** items.-## Organization+The page has four sections: **General**, **People**, **Organization API keys** and **Danger zone**.-### Organization Name+## General-Update your organization's display name. Owners and admins can change this setting.+- **Name** - Shown in the navigation and on invitations. Admins and owners can change it.+- **Slug** - Set when the organization is created. It can't be changed.+- **Created** - When the organization was created.-### Delete Organization+## People-Permanently delete the organization and all associated data including sites, analytics, reports, and member associations. Only owners can delete an organization.+The **People** table lists everyone in the organization, with a search box to find someone by name or email. It has these columns:-<Callout type="warn">- This action cannot be undone. You must type the organization name to confirm deletion. If you have an active subscription, you must cancel it before deleting the organization.-</Callout>+- **Person** - Name and email+- **Role** - Owner, Admin, Editor, Member, or Viewer+- **Site access** - **All sites**, or how many of the organization's sites they can reach, with the teams and direct grants that give them access+- **Joined** - When they joined-## Members+Pending invitations appear in the same table, marked **Pending**, with who sent them and when they expire. Use **Resend** to send an invitation again or **Cancel** to revoke it.-View and manage all members in your organization. The members table shows:-- **Name** - Member's display name-- **Email** - Member's email address-- **Role** - Owner, Admin, Editor, Member, or Viewer-- **Site Access** - Which sites the member can access-- **Joined** - When they joined the organization+Click a member's edit button to change their role or site access, or to remove them from the organization with **Remove Member**. Only system admins (accounts with the instance-wide admin role) can also change a member's name there.### Member Roles@@ -39,7 +37,7 @@ Each role can do everything the roles below it can.| Role | What it adds ||------|-------------|| **Owner** | Billing and plans, deleting the organization, making other owners |-| **Admin** | Inviting and managing members and teams, organization API keys, creating, deleting and [transferring](/docs/site-settings#transfer-site) sites |+| **Admin** | Inviting and managing members and teams, organization API keys, creating, deleting and [moving](/docs/site-settings#move-to-organization) sites || **Editor** | Site configuration: tracking settings, exclusions, public and private links, feature flags, experiments, data imports, Google Search Console, deleting session replays and tracked users, and editing anyone's segments and annotations || **Member** | Building reports: goals, funnels, dashboards, and their own segments and annotations || **Viewer** | Viewing analytics, sessions, replays and reports, without changing anything |@@ -50,8 +48,26 @@ A member's role can also be raised on individual sites: when you restrict someon### Inviting Members-Owners and admins can invite new members or create user accounts. See the [Inviting Users](/docs/inviting-users) guide for detailed instructions. A person can belong to several organizations.+Owners and admins can invite new members (Rybbit Cloud) or create user accounts (self-hosted) with the button next to the search box. See the [Inviting Users](/docs/inviting-users) guide for detailed instructions. A person can belong to several organizations.### TeamsYou can organize sites into teams to control which members have access to which sites. See the [Teams](/docs/teams) guide for details.++## Organization API keys++Organization API keys belong to the organization rather than a person, so they keep working when people leave. Only admins and owners can see or create them. A full-access organization key can reach all of the organization's sites; turn on **Restrict permissions** to limit it to specific resources. On Rybbit Cloud they share the organization's daily request budget and need a Standard or Pro plan.++Creating and managing them works the same way as [personal API keys](/docs/account-settings#personal-api-keys). For keys that act as you, with your own role, use personal keys instead.++## Danger zone++### Delete organization++Deleting an organization removes its members, teams and organization API keys. It does not delete sites: an organization that still has sites can't be deleted. Delete each site, or move it to another organization from its [site settings](/docs/site-settings), before you delete the organization. Only owners can delete an organization.++To confirm, click **Delete organization**, type the organization's name, then press and hold **Hold to delete organization**.++<Callout type="warn">+ This cannot be undone. If the organization has an active subscription, cancel it in [Billing](/docs/billing-settings) first.+</Callout>diff --git a/docs/content/docs/(docs)/roadmap.mdx b/docs/content/docs/(docs)/roadmap.mdxindex 2d386a634..25ee49e49 100644--- a/docs/content/docs/(docs)/roadmap.mdx+++ b/docs/content/docs/(docs)/roadmap.mdx@@ -8,8 +8,8 @@ Rybbit is a quickly growing project. We already have quite a few features, but t## Planned features-- Data import from Google Analytics, PostHog, and more+- Data import from Google Analytics, PostHog, and more. Imports from Umami, Simple Analytics, and Plausible are already available: see [Data import](/docs/data-import).- More tracking script/SDK integration guides- Custom themes-Once again, join our [Discord server](https://discord.gg/DEhGb4hYBj) or follow me on [X](https://x.com/yang_frog) to share your feedback and ideas. We would love to hear from you!\ No newline at end of file+Once again, join our [Discord server](https://discord.gg/DEhGb4hYBj) or follow me on [X](https://x.com/yang_frog) to share your feedback and ideas. We would love to hear from you!diff --git a/docs/content/docs/(docs)/rollup.mdx b/docs/content/docs/(docs)/rollup.mdxnew file mode 100644index 000000000..6e1b69572--- /dev/null+++ b/docs/content/docs/(docs)/rollup.mdx@@ -0,0 +1,24 @@+---+title: Rollup+description: See traffic across every site in your organization on one page+---++**Rollup** shows combined analytics for the sites in your organization, so you can compare them without opening each one. Open it from **Rollup** in the left navigation, below **Properties**, or search for it in the [command palette](/docs/keyboard-shortcuts).++## Choose which sites to include++- **Team**: pick a team to limit the page to that team's sites, **No Team** for sites without a team, or **All Teams**.+- **Tags**: pick one or more site tags to limit the page to sites with any of them. To tag a site, click the tag icon on its card on the home page.+- **Site chips**: each site in the current set has a colored chip. Click a chip to leave that site out or bring it back.++The date selector and the **Filter** button work like they do on a site's dashboard. Filters on the Rollup page are separate from the ones on your site dashboards.++## What it shows++- Totals for **Unique Users**, **Sessions**, **Pageviews**, **Pages per Session**, **Bounce Rate**, and **Session Duration**. Click one to chart it.+- A chart with one color per site. Users, sessions, and pageviews stack, since they add up across sites. Pages per session, bounce rate, and session duration show side by side instead.+- **Referrers** and **Channels**, plus UTM breakdowns.+- **Browsers**, **Devices**, **Operating Systems**, and screen dimensions.+- **Countries**, **Regions**, **Cities**, **Languages**, and **Timezones**.++You only see the sites you have access to.diff --git a/docs/content/docs/(docs)/sdks/web.mdx b/docs/content/docs/(docs)/sdks/web.mdxindex 6ddb7092f..7ea179a16 100644--- a/docs/content/docs/(docs)/sdks/web.mdx+++ b/docs/content/docs/(docs)/sdks/web.mdx@@ -35,7 +35,7 @@ The `rrweb` package is only required if you enable session replay in your Rybbit## Initialization<Callout type="warning">-`rybbit.init()` **must** be called once before any other tracking methods (`pageview`, `event`, etc.) can be used. Attempting to call other methods before `init` will result in errors or no tracking.+`rybbit.init()` **must** be called once before any other tracking methods (`pageview`, `event`, etc.) can be used. Calls made before `init` finishes are dropped, not queued. The SDK reports problems like this only when `debug: true` is set; otherwise it fails silently.</Callout>### Syntax@@ -71,9 +71,9 @@ These options are configured in your code and control SDK behavior locally:| Option | Type | Default | Description || :--------------------- | :------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `debounceDuration` | `number` | `500` | Debounce time in milliseconds for tracking pageviews after route changes. Set to `0` to disable debouncing (track immediately). |-| `skipPatterns` | `string[]` | `[]` | Array of path patterns. Pageviews whose path matches any pattern will **not** be tracked. See [Path Matching](#path-matching). |-| `maskPatterns` | `string[]` | `[]` | Array of path patterns. For matching pageview paths, the original path will be **replaced** by the pattern itself in tracked data. See [Path Matching](#path-matching). |-| `debug` | `boolean` | `false` | Enable detailed logging to the browser console. |+| `skipPatterns` | `string[]` | `[]` | Array of path patterns. Analytics events from a matching path (pageviews, custom events, errors, autocapture) are dropped. Web vitals and session replay are not affected. See [Path Matching](#path-matching). |+| `maskPatterns` | `string[]` | `[]` | Array of path patterns. On a matching path, analytics events have their path **replaced** by the pattern itself and their query string dropped. Web vitals and session replay keep the real URL. See [Path Matching](#path-matching). |+| `debug` | `boolean` | `false` | Log to the browser console. Warnings and errors (for example, calling methods before `init`) are only printed when this is on. || `replayPrivacyConfig` | `object` | - | Privacy settings for session replay. See [Session Replay](#session-replay). |#### Remote Configuration@@ -82,12 +82,12 @@ These settings are controlled through your Rybbit dashboard and cannot be set in| Dashboard Setting | Description | Default || :--------------------- | :--------------------------------------------------------- | :------ |-| Track Initial Pageview | Track pageview on initial page load | `true` |+| Track Initial Pageview | Track pageview on initial page load. Turning this off also turns off SPA navigation tracking and `onPageChange` callbacks in the SDK. | `true` || Track SPA Navigation | Track pageviews on Single Page Application route changes | `true` || Track URL Parameters | Include URL query strings in tracked data | `true` |-| Track URL Fragments | Keep ordinary URL fragments, such as `#shipping`, in paths | `false` |+| Track URL Fragments | Not read by the SDK: it always appends the URL fragment (such as `#shipping`) to the tracked path | - || Track Outbound Links | Automatically track clicks on external links | `true` |-| Track Web Vitals | Track Core Web Vitals performance metrics | `false` |+| Track Web Vitals | Track Core Web Vitals performance metrics. The SDK sends one snapshot when all metrics are in, 20 seconds after `init()`, or on `beforeunload`, whichever comes first. Without `reportAllChanges`, LCP is only reported after the first click or key press or when the page is hidden, and CLS only when the page is hidden, so both are often missing from SDK-sent vitals. | `false` || Capture Errors | Enable automatic error tracking | `false` || Session Replay | Enable session replay recording | `false` || Track Button Clicks | Automatically track button click interactions | `false` |@@ -96,6 +96,10 @@ These settings are controlled through your Rybbit dashboard and cannot be set inIf fetching settings fails or times out, the SDK uses sensible defaults.+<Callout type="info">+The SDK has no feature flag API (`flag()`, `flagPayload()`, and so on). To use [feature flags](/docs/feature-flags) in the browser, use the tracking script, or call the server evaluation endpoint from your backend.+</Callout>+## Tracking PageviewsPageviews are tracked automatically based on your dashboard settings. This includes the initial page load and subsequent route changes in Single Page Applications (SPAs).@@ -292,7 +296,7 @@ async function fetchUserData(userId) {```<Callout type="info">-Manual error capture only works when error tracking is enabled in your dashboard settings. If it's disabled, calling `error()` will log a warning.+Manual error capture only works when error tracking is enabled in your dashboard settings. If it's disabled, `error()` does nothing (with `debug: true` it logs why).</Callout>## Session Replay@@ -307,7 +311,7 @@ npm install rrweb### Enabling Session Replay-Session replay must be enabled in your Rybbit dashboard under. Once enabled, recording starts automatically when the SDK initializes.+Session replay must be enabled in your site settings in the Rybbit dashboard. Once enabled, recording starts automatically when the SDK initializes.### Manual Controls@@ -487,12 +491,12 @@ rybbit.onPageChange((newPath, previousPath) => {```<Callout type="info">-Callbacks are only triggered when the pathname actually changes. Multiple calls to the same path won't trigger callbacks repeatedly.+Callbacks are only triggered when the pathname actually changes. Multiple calls to the same path won't trigger callbacks repeatedly. They only run when **Track Initial Pageview** is on in your dashboard, since the SDK sets up its navigation listeners only then.</Callout>## Opting Out-Users can opt out of all tracking by setting a flag in `localStorage` or on the `window` object. When opted out, all tracking calls are silently ignored.+Users can opt out of all tracking by setting a flag in `localStorage` or on the `window` object. When opted out, all tracking calls are silently ignored. The SDK checks both flags once, when it loads, so setting one on a page that is already tracking takes effect on the next page load.```javascript// Opt out via localStorage (persists across sessions)@@ -521,27 +525,24 @@ rybbit.cleanup();### What Gets Cleaned Up- SPA route change listeners (`popstate`, `hashchange`)-- Outbound link click listeners-- Data attribute click listeners-- Error tracking listeners+- Outbound link and data attribute click listeners (only when automatic pageview tracking was set up)+- Error, button click, copy, and form tracking listeners- Session replay recording- Page change callbacks-- Resets initialization state++`cleanup()` does not stop all tracking:++- The patched `history.pushState` and `history.replaceState` are not restored, so SPA navigations keep sending pageviews.+- A web vitals snapshot that hasn't been sent yet is still sent.+- The SDK's configuration is not reset, so calling `init()` again fails with "already initialized" (logged only with `debug: true`).++Call `init()` once per page load. The SDK has no way to fully stop tracking mid-page. To honor a consent withdrawal, set the [opt-out flag](#opting-out) and reload the page.### Example```javascript-// In React-useEffect(() => {- rybbit.init({- analyticsHost: "https://app.rybbit.io/api",- siteId: "1",- });-- return () => {- rybbit.cleanup();- };-}, []);+// Remove the SDK's listeners and stop session replay+rybbit.cleanup();```## Path Matching@@ -566,7 +567,7 @@ skipPatterns: [### `skipPatterns`-If a page's path matches any pattern in `skipPatterns`, the pageview for that path will **not** be sent.+If a page's path matches any pattern in `skipPatterns`, analytics events from that path are dropped: pageviews, custom events, outbound clicks, errors, and autocapture events. Web vitals are still sent, and session replay (if enabled) keeps recording and uploading on skipped paths.**Examples:**@@ -588,7 +589,7 @@ await rybbit.init({### `maskPatterns`-If a page's path matches a pattern in `maskPatterns`, the pageview **will** be sent, but the `pathname` will be **replaced** by the pattern string itself. This is useful for grouping similar pages or hiding sensitive IDs.+If a page's path matches a pattern in `maskPatterns`, events **will** be sent, but the `pathname` will be **replaced** by the pattern string itself and the query string is dropped. This applies to analytics events only: web vitals and session replay recordings keep the original URL, including the query string. It is useful for grouping similar pages or hiding sensitive IDs.<Callout type="warning">If a path matches both a `skipPatterns` and a `maskPatterns` pattern, **skipping takes priority**.diff --git a/docs/content/docs/(docs)/site-settings.mdx b/docs/content/docs/(docs)/site-settings.mdxindex 1c5661438..16888bc7b 100644--- a/docs/content/docs/(docs)/site-settings.mdx+++ b/docs/content/docs/(docs)/site-settings.mdx@@ -5,10 +5,18 @@ description: Configure your site settings including privacy options, analytics fimport { Callout } from 'fumadocs-ui/components/callout';-Access your site settings by clicking the settings icon in your site's Rybbit dashboard.+Open your site's dashboard and click **Site Settings** at the bottom of the sidebar.+Settings are split into tabs: **General**, **Tracking**, **Exclusions**, **Integrations** (Cloud), **Tracking Script**, **Widget Embeds**, **Dashboard Embed**, **Import** and **Usage**.++## General++### Site Name and Domain++**Site Name** is the display name for the site. **Domain** is the domain used for tracking. Click **Update** next to either to save it. Changing the domain doesn't affect existing data; all historical analytics are kept.+## Privacy & Security### Public Analytics@@ -34,6 +42,10 @@ Enable "User ID Salting" to have Rybbit forget about unique users every day. IfEnable "Block Bot Traffic" to prevent detected bot traffic from being tracked in your normal analytics. See [Bot detection](/docs/bot-detection) for how Rybbit identifies and stores bot traffic.+### First-Party Proxy++Turn on **First-Party Proxy** if tracking requests reach Rybbit through your own proxy or CDN (for example a Cloudflare Worker, CloudFront or nginx). Rybbit then always reads visitor IPs from forwarded headers. Leave it off if the script talks to Rybbit directly. Without Cloudflare in front, as on most self-hosted installations, Rybbit reads forwarded headers either way, so the setting has no effect. See the [proxy guide](/docs/proxy-guide).+### Track IP AddressEnable "Track IP Address" to store the IP address of visitors.@@ -42,13 +54,15 @@ Enable "Track IP Address" to store the IP address of visitors.This is not GDPR compliant. Only enable if you have a legitimate need and proper consent mechanisms in place.</Callout>-## Analytics Features+## Tracking++### Analytics Features-### Session Replay <span className="text-green-500 text-sm">(Pro)</span>+#### Session Replay <span className="text-green-500 text-sm">(Pro)</span>Record and replay user sessions to understand user behavior. This feature allows you to see exactly how users interact with your site.-### Web Vitals <span className="text-green-500 text-sm">(Standard)</span>+#### Web Vitals <span className="text-green-500 text-sm">(Cloud, Standard)</span>Track Core Web Vitals metrics including:- **LCP** (Largest Contentful Paint)@@ -57,27 +71,47 @@ Track Core Web Vitals metrics including:- **FCP** (First Contentful Paint)- **TTFB** (Time to First Byte)-### Error Tracking <span className="text-green-500 text-sm">(Standard)</span>+#### SPA Navigation [#track-spa-navigation]-Capture JavaScript errors and exceptions from your site to identify and fix issues affecting your users.+Automatically track navigation in single-page applications (SPAs). Enabled by default. This detects URL changes via the History API and tracks them as page views.-### Track Outbound Links+#### URL Parameters [#track-url-parameters]-Track when users click on external links leaving your site. Enabled by default.+Include query string parameters in page tracking. Enabled by default. Disable if you want cleaner URLs in your analytics or need to exclude sensitive parameters.-### Track URL Parameters+#### Track URL fragments-Include query string parameters in page tracking. Enabled by default. Disable if you want cleaner URLs in your analytics or need to exclude sensitive parameters.+Keep fragments such as `#shipping` in page paths, so checkout stages or tabs are tracked as separate pages. Off by default.-### Track Initial Page View+#### Initial Page View [#track-initial-page-view]Automatically track the first page view when the tracking script loads. Enabled by default.-### Track SPA Navigation+### Auto Capture-Automatically track navigation in single-page applications (SPAs). Enabled by default. This detects URL changes via the History API and tracks them as page views.+#### Outbound Links [#track-outbound-links]++Track when users click on external links leaving your site. Enabled by default.++#### Error Tracking <span className="text-green-500 text-sm">(Standard)</span>++Capture JavaScript errors and exceptions from your site to identify and fix issues affecting your users.++#### Button Clicks <span className="text-green-500 text-sm">(Standard)</span>++Automatically track clicks on all buttons.-## Traffic Filtering+#### Copy Events <span className="text-green-500 text-sm">(Standard)</span>++Track when users copy text from your site.++#### Form Interactions <span className="text-green-500 text-sm">(Standard)</span>++Automatically track form submissions and input and select changes.++See [Autocapture](/docs/autocapture) for what each of these records.++## Exclusions### IP Exclusions@@ -90,10 +124,22 @@ Block specific IP addresses or ranges from being tracked. Supports:Block all traffic from specific countries using ISO country codes (e.g., `US`, `DE`, `FR`).+### ASN Exclusions++Exclude traffic from specific networks by autonomous system number, such as a corporate VPN or hosting provider. Enter the number with or without the `AS` prefix (e.g., `AS13335` or `13335`). Up to 100 ASN exclusions are allowed.+### Path ExclusionsExclude traffic to specific pages. Use `*` as a wildcard (e.g., `/admin/*` or `/preview`). Matching is case-insensitive. Up to 100 path exclusions are allowed.+### Query Param Exclusions++Exclude traffic to URLs containing specific query parameters. Use a parameter name alone (e.g., `preview`) to match whenever it's present, or `name=value` (e.g., `utm_source=internal`) to match a specific value. Values support `*` as a wildcard, and matching is case-insensitive. Up to 100 query param exclusions are allowed.++<Callout type="info">+ Query param exclusions need **URL Parameters** turned on in the **Tracking** tab. With it off, events are sent without their query string and these exclusions can't match.+</Callout>+### Hostname ExclusionsExclude traffic from specific hostnames such as staging or preview domains. Use `*` as a wildcard (e.g., `localhost` or `*.vercel.app`). Matching is case-insensitive. Up to 100 hostname exclusions are allowed.@@ -104,6 +150,10 @@ Exclude traffic from user agents containing any of these terms. Matching is a caAll of these exclusions work at the server level, ensuring blocked traffic never reaches your analytics database.+## Tracking Script++The **Tracking Script** tab shows the snippet to add to the `<head>` of your website, with an **AI agent** tab holding a prompt you can paste into a coding agent. Under **Options** you can set **Skip Patterns** (URLs to exclude from tracking), **Mask Patterns** (URLs to anonymize, e.g. `/users/*/profile`) and the **Debounce Duration (ms)** before a pageview is tracked after a URL change. See [Tracking script](/docs/script) for every option.+## EmbedsShow Rybbit data on another site with an embeddable iframe.@@ -111,20 +161,31 @@ Show Rybbit data on another site with an embeddable iframe.- **Widget Embeds** show a compact live visitor widget. Enable them from the **Widget Embeds** tab. This is independent of Public Analytics and only exposes the data the widget displays. See the [Widget Embeds guide](/docs/embeds/widget) for details.- **Dashboard Embed** shows the analytics dashboard in an iframe. Configure it from the **Dashboard Embed** tab. It uses a generated private link, not Public Analytics. See the [Dashboard Embed guide](/docs/embeds/dashboard) for details.-## Google Search Console <span className="text-green-500 text-sm">(Cloud)</span>+## Integrations <span className="text-green-500 text-sm">(Cloud)</span>++### Google Search ConsoleConnect your Google Search Console account to see search performance data alongside your analytics.-## Change Domain+## Import++Import historical data from another analytics tool. See [Data import](/docs/data-import).++## Usage++The **Usage** tab shows this site's events for the current calendar month, its share of your organization's events, the organization's event limit, a projection to month end, and a **Daily Events** chart. Usage resets at the start of each calendar month. See [Billing](/docs/billing-settings#usage) for what counts.++## Moving a site++Admins and owners can move a site to another organization from the **General** tab. Its analytics data, goals, funnels, dashboards, segments, annotations and settings go with it, and the tracking script keeps working unchanged. Site access granted in the old organization (restricted-member grants and team assignments) is reset.-Update the domain for your site. Changing domains does not affect existing data - all historical analytics are preserved.+### Move to Organization-## Transfer Site+To move a site to another organization you manage, pick the organization under **Move to Organization**, click **Move** and confirm with **Yes, move site**. You need to be an admin or owner of both organizations.-Admins and owners can move a site to another organization. Its analytics data, goals, funnels, dashboards, segments, annotations and settings go with it, and the tracking script keeps working unchanged. Site access granted in the old organization (restricted-member grants and team assignments) stays behind.+### Transfer to someone else-- **To another organization you manage:** pick the organization under **Transfer Site** and confirm. You need to be an admin or owner of both organizations.-- **To someone else:** enter their email under **Transfer to someone else**. They get an email with a link (you can also copy it and send it yourself); they open it signed in with that address (on Rybbit Cloud it must be verified; the page offers to send the verification email), choose one of their organizations, and accept. The link is valid for 7 days, and you can cancel it until it's accepted. Neither of you needs to join the other's organization.+Enter the recipient's email under **Transfer to someone else** and click **Send transfer**. They get an email with a link (you can also use **Copy link** and send it yourself); they open it signed in with that address (on Rybbit Cloud it must be verified; the page offers to send the verification email), choose one of their organizations, and accept. The link is valid for 7 days, and you can **Cancel transfer** until it's accepted. Neither of you needs to join the other's organization.<Callout type="info">When someone else accepts a transfer, the site's Google Search Console connection is removed, since it uses the sender's Google account; the new owner can connect their own. On Rybbit Cloud the receiving organization's plan must have room for another site.@@ -132,7 +193,7 @@ Admins and owners can move a site to another organization. Its analytics data, g## Delete Site-Permanently delete a site and all associated data. Only admins and owners can delete sites.+Permanently delete a site and all associated data from the **Danger Zone** at the bottom of the **General** tab. Only admins and owners can delete sites. Click **Delete Site**, then press and hold **Hold to delete site** to confirm.<Callout type="warn">This action cannot be undone. All analytics data, reports, funnels, and goals will be permanently deleted.diff --git a/docs/content/docs/(docs)/teams.mdx b/docs/content/docs/(docs)/teams.mdxindex 6810b2b77..53fea9fea 100644--- a/docs/content/docs/(docs)/teams.mdx+++ b/docs/content/docs/(docs)/teams.mdx@@ -7,7 +7,7 @@ import { Callout } from 'fumadocs-ui/components/callout';Teams let you group sites together and control which organization members can access them. This is useful for organizations managing multiple properties where different people are responsible for different sites.-Access teams by clicking on "Teams" or going to [app.rybbit.io/settings/teams](https://app.rybbit.io/settings/teams).+Open teams by clicking **Teams** in the settings sidebar or going to [app.rybbit.io/settings/teams](https://app.rybbit.io/settings/teams). Only admins and owners see the **Teams** item.@@ -29,8 +29,8 @@ When a member is assigned to a team, they can access all sites within that team.## Creating a Team1. Go to **Settings > Teams**-2. Click the **Create Team** button-3. Enter a team name+2. Click **Create team**+3. Enter a **Team Name**4. Select which members should belong to the team5. Select which sites the team should have access to6. Optionally pick a role the team's members get on those sites@@ -40,18 +40,26 @@ You can also create a team directly from the team filter on the home page.## Managing Teams+The **Teams** table lists each team with its **Members**, **Sites** and **Role on its sites**. Click a row to expand it and see what the team does for each member, which sites it covers, and **Add people** or **Add sites** shortcuts.+### Editing a Team-Click the edit icon on any team card to update its name, members, or site assignments.+Click the edit (pencil) icon at the end of a team's row to update its name, members, sites, or role on its sites, then click **Save Changes**.### Deleting a Team-Click the delete icon on a team card. Sites assigned to the team will become unassigned and visible to all members.+Click the delete (trash) icon at the end of a team's row and confirm with **Delete Team**. Sites assigned to the team become unassigned and visible to all members.<Callout type="warn">Deleting a team removes all member-to-site associations through that team. Members who only had access via the deleted team will lose access to those sites.</Callout>+## Access by site++Below the teams table, **Access by site** lists every site with who can open it, with what role, and why: through a team (shown by the team's name) or a **Direct** grant. When a site role is higher than the person's organization role, the original role is shown as "from" that role. Owners and admins always reach every site, so they're summarized as people with all-site access rather than listed per site.++Use it to check access before and after you change a team.+## Filtering by TeamOn the home page, use the team selector in the toolbar to filter the site list by team. The options are:diff --git a/docs/content/docs/(docs)/track-events.mdx b/docs/content/docs/(docs)/track-events.mdxindex 18d431bda..3f5608051 100644--- a/docs/content/docs/(docs)/track-events.mdx+++ b/docs/content/docs/(docs)/track-events.mdx@@ -32,7 +32,7 @@ This approach requires no JavaScript and works on any clickable element.Tracks a custom event with optional properties.* `eventName` (String): The name of the custom event (max 256 characters).-* `properties` (Object, Optional): An object containing custom data (max 2KB characters). Only strings numbers are supported as values.+* `properties` (Object, Optional): A flat object of custom data. Serialized as JSON it must be at most 2048 characters; larger events are rejected, not truncated. Keep values to strings and numbers.```javascript// Track a simple custom event@@ -55,6 +55,23 @@ Tracks a pageview. Useful when automatic SPA navigation tracking is disabled inwindow.rybbit.pageview();```+### `window.rybbit.error(error, properties)`++Reports an error you caught yourself as an `error` event. It goes through the same filtering as automatic [error tracking](/docs/autocapture#error-tracking): errors from other origins are skipped and identical errors are sent at most once per 60 seconds.++* `error` (Error): The error object. Its `name` becomes the event name.+* `properties` (Object, Optional): Extra context, such as `filename`, `lineno`, and `colno`, plus any custom fields.++```javascript+try {+ riskyOperation();+} catch (err) {+ window.rybbit.error(err, { feature: "checkout" });+}+```++For identifying users, see [Identify Users](/docs/identify-users). For feature flags, see [Feature Flags](/docs/feature-flags). Session replay can also be started and stopped manually with `startSessionReplay()`, `stopSessionReplay()`, and `isSessionReplayActive()`.+## TypeScript SupportPut this as `rybbit.d.ts` anywhere in your project to avoid having to do `(window as any).rybbit.event()` everywhere.@@ -73,6 +90,13 @@ interface Rybbit {*/event: (name: string, properties?: Record<string, any>) => void;+ /**+ * Reports a caught error as an error event+ * @param error The error object+ * @param properties Optional context (filename, lineno, colno, custom fields)+ */+ error: (error: Error, properties?: Record<string, any>) => void;+/*** Sets a custom user ID for tracking logged-in users* @param userId The user ID to set (will be stored in localStorage)@@ -109,7 +133,8 @@ interface Rybbit {* Evaluates a feature flag and returns its value. Reading a flag records a* feature flag exposure once per flag value/version.* @param key The flag key- * @param fallback Value returned before flags resolve or if the flag is inactive+ * @param fallback Value returned before flags resolve or if the flag doesn't exist+ * (a disabled flag returns false)*/flag: <T = unknown>(key: string, fallback?: T) => T;@@ -137,6 +162,21 @@ interface Rybbit {* @param callback Receives the ready rybbit instance*/onReady: (callback: (rybbit: Rybbit) => void) => void;++ /**+ * Starts session replay recording, if session replay is enabled for the site+ */+ startSessionReplay: () => void;++ /**+ * Stops session replay recording+ */+ stopSessionReplay: () => void;++ /**+ * Returns whether session replay is currently recording+ */+ isSessionReplayActive: () => boolean;}declare global {