Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

docs: fix nav, data import limits, and platform guide errors (#1339)

Goldflag972b6c7e0348
diff --git a/docs/content/docs/(docs)/data-import.mdx b/docs/content/docs/(docs)/data-import.mdx
index f45ccd3cd..684d53fab 100644
--- a/docs/content/docs/(docs)/data-import.mdx
+++ b/docs/content/docs/(docs)/data-import.mdx
@@ -29,8 +29,8 @@ Additional platforms may be added in the future based on user demand.
| Plan | Access | Historical Window | Monthly Event Limit |
|------|--------|-------------------|---------------------|
| Free | ❌ Not available | - | - |
-| Standard | βœ… Available | 36 months (3 years) | Plan limit applies |
-| Pro | βœ… Available | 60 months (5 years) | Plan limit applies |
+| Standard | βœ… Available | 24 months (2 years) | Plan limit applies to each month |
+| Pro | βœ… Available | 60 months (5 years) | Plan limit applies to each month |
### Self-Hosted Version
@@ -45,7 +45,7 @@ Self-hosted installations have **unlimited** access to data imports with no rest
The historical data window determines how far back you can import data:
-- **Standard plans**: Import data from the past 36 months (3 years)
+- **Standard plans**: Import data from the past 24 months (2 years)
- **Pro plans**: Import data from the past 60 months (5 years)
- **Self-hosted**: Unlimited - import data from any date
@@ -53,18 +53,19 @@ Events outside your plan's historical window will be automatically skipped durin
### Event Quotas
-Imported events count toward your monthly event limit:
+Each imported event counts against the calendar month it happened in, not the month you run the import. Every month can hold up to your plan's monthly event limit, including the events Rybbit already tracked for your organization that month and anything imported earlier:
-- If you're close to your monthly limit, imports may be partially skipped
+- Events that would push their month over the limit are skipped
- Skipped events are counted and displayed in the import history
-- Consider upgrading your plan if you need to import large amounts of data
+- Importing older data doesn't use up the current month's quota; only events dated this month count toward it
+- If a month in your source data is busier than your plan allows, upgrade to a plan with a higher event limit before importing
### Concurrent Imports
For cloud users:
- **Maximum 1 active import per organization**
- New imports are blocked until the current one completes
-- Maximum 2-hour timeout per import
+- An import that hasn't finished after 2 hours is marked **Failed** and no longer blocks new imports
Self-hosted users have no concurrent import restrictions.
@@ -120,13 +121,13 @@ Self-hosted users have no concurrent import restrictions.
### Monitor Import Progress
-Your import will begin processing in the background. You can:
+Your browser reads the file and uploads it to Rybbit in batches, so keep the tab open until the import finishes. While it runs you can:
- View the import status in the "Import History" section
- Monitor the number of imported, skipped, and invalid events
-- Continue using Rybbit while the import runs
+- Keep using Rybbit in the same tab, as long as you don't close or reload it
<Callout type="info">
- Large imports may take several minutes to complete. The page will automatically refresh to show updated progress.
+ Large imports may take several minutes to complete. The Import History updates automatically to show progress.
</Callout>
</Step>
@@ -148,7 +149,7 @@ Each import shows three key metrics:
- Events that were excluded during import
- Common reasons:
- Outside your plan's historical data window
- - Would exceed your monthly event quota
+ - Would push the month they happened in over your plan's monthly event limit
**Invalid Events**
- Events that failed validation during import
@@ -164,8 +165,8 @@ Each import shows three key metrics:
### Managing Imports
-**Deleting Completed Imports**
-- Click the trash icon next to any completed import
+**Deleting Imports**
+- Click the trash icon next to any completed or failed import
- Confirm the deletion in the dialog
- This will permanently remove the import record **and all associated events** from your analytics
- Active imports cannot be deleted
@@ -178,12 +179,13 @@ Each import shows three key metrics:
### Events Skipped Due to Quota Limits
-**Cause:** Importing the events would exceed your monthly event limit.
+**Cause:** The months those events happened in already reached your plan's monthly event limit, counting the events Rybbit tracked then and earlier imports.
**Solution:**
-- Wait until the next billing cycle when your quota resets
-- Upgrade to a plan with a higher event limit
-- Import smaller date ranges to stay within quota
+- Upgrade to a plan with a higher monthly event limit
+- After upgrading, delete the import, then import the whole file again. Importing it again without deleting stores the events it already imported twice
+- Start the new import at least 2 hours after the original one finished. Until then its events still count against your limit, even after you delete it
+- Waiting for the next billing cycle doesn't help: imported events count against the months they happened in, and past months don't reset
### Events Skipped Due to Date Range
@@ -206,12 +208,12 @@ Each import shows three key metrics:
### Import Appears Stuck
-**Cause:** Very large files can take time to process, or a timeout occurred.
+**Cause:** Very large files take time to upload, or the browser tab was closed or lost its connection before the upload finished.
**Solution:**
-- Wait up to 2 hours for the import to complete
-- If still stuck after 2 hours, the import will be automatically marked as complete
-- Check the imported event count to see if any data was processed
+- Keep the tab open while a large file uploads
+- An import that hasn't finished after 2 hours is marked **Failed**, and you can start a new one
+- Events imported before it stopped stay in your analytics. Delete the failed import to remove them before importing the file again
- Contact support if no events were imported
## Best Practices
@@ -220,7 +222,7 @@ Each import shows three key metrics:
1. **Export a complete backup** from your current analytics platform
2. **Test with a small sample** (first 1,000 rows) before importing your full dataset
-3. **Check your event quota** to ensure you have sufficient capacity
+3. **Check each month in your source data** against your monthly event limit, minus what Rybbit already tracked or imported that month
4. **Verify date ranges** match your plan's historical window
5. **Review CSV format** matches the required structure for your platform
diff --git a/docs/content/docs/(docs)/definitions.mdx b/docs/content/docs/(docs)/definitions.mdx
index 62eb8de98..b8abf7388 100644
--- a/docs/content/docs/(docs)/definitions.mdx
+++ b/docs/content/docs/(docs)/definitions.mdx
@@ -19,7 +19,7 @@ The total number of times visitors have viewed pages on your website. Each time
The average number of pages viewed during a session. Calculated by dividing the total number of pageviews by the total number of sessions.
### Bounce Rate
-The percentage of sessions where a user leaves your site after viewing only one page without any interaction. A high bounce rate might indicate that landing pages aren't relevant to visitors.
+The percentage of sessions with exactly one pageview. Custom events, outbound clicks and other interactions don't change this, so a visitor who views one page and clicks a button still counts as a bounce. A high bounce rate might indicate that landing pages aren't relevant to visitors.
### Session Duration
The average length of time users spend on your site during a session. Longer sessions typically indicate more engaged visitors.
diff --git a/docs/content/docs/(docs)/feature-guides/meta.json b/docs/content/docs/(docs)/feature-guides/meta.json
index f3f99ff7d..3dff67352 100644
--- a/docs/content/docs/(docs)/feature-guides/meta.json
+++ b/docs/content/docs/(docs)/feature-guides/meta.json
@@ -5,8 +5,8 @@
"events",
"globe",
"journeys",
- "main",
- "pages",
+ "main-tab",
+ "pages-tab",
"performance",
"session-replay",
"retention",
diff --git a/docs/content/docs/(docs)/guides/angular.mdx b/docs/content/docs/(docs)/guides/angular.mdx
index f1191394d..2bd54a1d1 100644
--- a/docs/content/docs/(docs)/guides/angular.mdx
+++ b/docs/content/docs/(docs)/guides/angular.mdx
@@ -78,7 +78,7 @@ export class FeatureComponent {
## Troubleshooting
-- **Pageviews missing after navigation**: this is rare. If it happens, subscribe to `Router.events`, filter for `NavigationEnd` and call `window.rybbit.pageview()`; test the default behaviour first.
+- **Pageviews missing after navigation**: this is rare. If it happens, subscribe to `Router.events`, filter for `NavigationEnd` and call `window.rybbit.pageview()`, skipping the first `NavigationEnd` because the script already tracks the landing page; test the default behaviour first.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/aspnet.mdx b/docs/content/docs/(docs)/guides/aspnet.mdx
index a93f0b0a9..bdb76e20e 100644
--- a/docs/content/docs/(docs)/guides/aspnet.mdx
+++ b/docs/content/docs/(docs)/guides/aspnet.mdx
@@ -23,7 +23,7 @@ ASP.NET Core MVC and Razor Pages apps share one layout file, `_Layout.cshtml`, t
Add a `Rybbit` section to `appsettings.json`:
-```json filename="appsettings.json"
+```json title="appsettings.json"
{
"Rybbit": {
"InstanceUrl": "https://app.rybbit.io",
@@ -43,7 +43,7 @@ Open the layout file:
Inject `IConfiguration` at the top and add the tag inside `<head>`:
-```razor filename="Views/Shared/_Layout.cshtml"
+```razor title="Views/Shared/_Layout.cshtml"
@inject IConfiguration Configuration
@{
var rybbitSiteId = Configuration["Rybbit:SiteId"];
diff --git a/docs/content/docs/(docs)/guides/blazor.mdx b/docs/content/docs/(docs)/guides/blazor.mdx
index 14524368a..75f146c6f 100644
--- a/docs/content/docs/(docs)/guides/blazor.mdx
+++ b/docs/content/docs/(docs)/guides/blazor.mdx
@@ -24,7 +24,7 @@ Where the snippet goes depends on the Blazor hosting model: a Blazor Web App kee
<Tab>
`App.razor` is rendered on the server, so it can read the site ID from `appsettings.json`. Add a `Rybbit` section:
-```json filename="appsettings.json"
+```json title="appsettings.json"
{
"Rybbit": {
"InstanceUrl": "https://app.rybbit.io",
@@ -35,7 +35,7 @@ Where the snippet goes depends on the Blazor hosting model: a Blazor Web App kee
Then inject `IConfiguration` in `Components/App.razor` and add the tag inside `<head>`:
-```razor filename="Components/App.razor"
+```razor title="Components/App.razor"
@inject IConfiguration Configuration
@{
var rybbitSiteId = Configuration["Rybbit:SiteId"];
@@ -64,7 +64,7 @@ Override the value per environment with `appsettings.Production.json` or the env
<Tab>
A standalone WebAssembly app ships `wwwroot/index.html` as a static file, so add the tag directly inside `<head>`:
-```html filename="wwwroot/index.html"
+```html title="wwwroot/index.html"
<head>
<base href="/" />
<link rel="stylesheet" href="css/app.css" />
@@ -79,7 +79,7 @@ The site ID is public on every platform (it is in the page source), so a static
<Tab>
Add the `Rybbit` section to `appsettings.json` as in the Blazor Web App tab, then open `Pages/_Host.cshtml` (or `Pages/_Layout.cshtml` in .NET 6 projects, where the `<head>` lives) and add the tag:
-```razor filename="Pages/_Host.cshtml"
+```razor title="Pages/_Host.cshtml"
@page "/"
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration
diff --git a/docs/content/docs/(docs)/guides/chrome-extension.mdx b/docs/content/docs/(docs)/guides/chrome-extension.mdx
index 0026642d0..57426703e 100644
--- a/docs/content/docs/(docs)/guides/chrome-extension.mdx
+++ b/docs/content/docs/(docs)/guides/chrome-extension.mdx
@@ -37,12 +37,10 @@ await rybbit.init({
analyticsHost: "https://app.rybbit.io/api",
siteId: "YOUR_SITE_ID",
});
-
-// Extension pages have URLs like chrome-extension://<id>/popup.html.
-// Report a readable path instead:
-rybbit.pageview("/popup");
```
+`init()` records a pageview for the page by itself (unless [Initial Page View](/docs/site-settings#track-initial-page-view) is turned off for the site), so don't call `rybbit.pageview()` as well or each open counts twice. Extension pages have URLs like `chrome-extension://<id>/popup.html`, so the popup shows up as `/popup.html`.
+
3. Grant the extension permission to call the analytics host. Requests from extension pages to origins listed in `host_permissions` are not subject to CORS:
```json title="manifest.json"
@@ -87,7 +85,7 @@ document.getElementById("save")?.addEventListener("click", () => {
- **`Refused to load the script` in the popup console**: the fixed `extension_pages` CSP blocked a remote tag. Remove it and use the SDK.
- **`POST /api/track` blocked by CORS**: `host_permissions` is missing or does not match. The pattern must include the path wildcard: `https://app.rybbit.io/*`.
- **Self-hosted Rybbit**: replace `https://app.rybbit.io` in both `analyticsHost` and `host_permissions` with your own instance URL.
-- **Every pageview shows the extension ID as hostname**: expected. Extension pages live on `chrome-extension://<id>`; use `rybbit.pageview("/name")` for readable paths.
+- **Every pageview shows the extension ID as hostname**: expected. Extension pages live on `chrome-extension://<id>`; the path (`/popup.html`, `/options.html`) still tells pages apart. For custom paths, turn off [Initial Page View](/docs/site-settings#track-initial-page-view) under **Site Settings β†’ Tracking** and call `rybbit.pageview("/name")` after `init()` in each page you track. The setting applies to every page using this site ID, not only the popup.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/django.mdx b/docs/content/docs/(docs)/guides/django.mdx
index 9c5de9dee..fbdc139fa 100644
--- a/docs/content/docs/(docs)/guides/django.mdx
+++ b/docs/content/docs/(docs)/guides/django.mdx
@@ -23,7 +23,7 @@ Django pages extend a base template, so the snippet goes into the `<head>` of th
Add the Rybbit values to `settings.py`, reading from the environment:
-```python filename="settings.py"
+```python title="settings.py"
import os
RYBBIT_INSTANCE_URL = os.environ.get("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
@@ -36,7 +36,7 @@ Set `RYBBIT_SITE_ID=YOUR_SITE_ID` in your production environment (or your `.env`
Create a context processor that adds both settings to every template context:
-```python filename="myproject/context_processors.py"
+```python title="myproject/context_processors.py"
from django.conf import settings
@@ -49,7 +49,7 @@ def rybbit(request):
Register it under `TEMPLATES` in `settings.py`:
-```python filename="settings.py"
+```python title="settings.py"
TEMPLATES = [
{
"BACKEND": "django.template.backends.django.DjangoTemplates",
@@ -71,7 +71,7 @@ TEMPLATES = [
Open the template that every page extends, usually `templates/base.html`, and add the tag inside `<head>`:
-```jinja filename="templates/base.html"
+```jinja title="templates/base.html"
<head>
<meta charset="utf-8">
<title>{% block title %}My Site{% endblock %}</title>
diff --git a/docs/content/docs/(docs)/guides/docusaurus.mdx b/docs/content/docs/(docs)/guides/docusaurus.mdx
index 91430e5f3..b499867c6 100644
--- a/docs/content/docs/(docs)/guides/docusaurus.mdx
+++ b/docs/content/docs/(docs)/guides/docusaurus.mdx
@@ -22,7 +22,7 @@ Docusaurus has a `scripts` option in `docusaurus.config.js` that adds a `<script
Open `docusaurus.config.js` (or `docusaurus.config.ts`) at the root of your project and add the script to the `scripts` array:
-```javascript filename="docusaurus.config.js"
+```javascript title="docusaurus.config.js"
/** @type {import('@docusaurus/types').Config} */
const config = {
// ... title, url, baseUrl, presets, themeConfig
@@ -40,7 +40,7 @@ module.exports = config;
If you already manage tags through `headTags`, this form is equivalent:
-```javascript filename="docusaurus.config.js"
+```javascript title="docusaurus.config.js"
headTags: [
{
tagName: "script",
@@ -70,7 +70,7 @@ Docusaurus builds a single-page app on React Router. Rybbit detects client-side
Docusaurus pages are React, so you can fire events from a component and use it in MDX:
-```jsx filename="src/components/TrackedButton.jsx"
+```jsx title="src/components/TrackedButton.jsx"
import React from "react";
export default function TrackedButton({ children, eventName, eventData }) {
@@ -94,19 +94,9 @@ import TrackedButton from "@site/src/components/TrackedButton";
</TrackedButton>
```
-For site-wide listeners, use a [client module](https://docusaurus.io/docs/advanced/client-modules). `onRouteDidUpdate` runs after every navigation once the DOM is ready:
+You don't need a listener for links to other sites. Rybbit records clicks on external links as outbound events by default, controlled by [Outbound Links](/docs/site-settings#track-outbound-links) under **Site Settings β†’ Tracking**.
-```javascript filename="src/client-modules/rybbit-events.js"
-export function onRouteDidUpdate() {
- document.querySelectorAll('a[target="_blank"]').forEach((link) => {
- link.addEventListener("click", () => {
- window.rybbit?.event("external_link_click", { href: link.href });
- });
- });
-}
-```
-
-Register it in `docusaurus.config.js` under `clientModules: [require.resolve("./src/client-modules/rybbit-events.js")]`. Client modules also run during server-side rendering, so guard any `window` access.
+If you add other site-wide code through a [client module](https://docusaurus.io/docs/advanced/client), keep in mind that `onRouteDidUpdate` runs after every navigation while the navbar and footer stay mounted, so listeners attached to them there pile up. Client modules also run during server-side rendering, so guard any `window` access.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/ecwid.mdx b/docs/content/docs/(docs)/guides/ecwid.mdx
index 8e6f4e750..6c3a36452 100644
--- a/docs/content/docs/(docs)/guides/ecwid.mdx
+++ b/docs/content/docs/(docs)/guides/ecwid.mdx
@@ -57,7 +57,7 @@ Ecwid's storefront JavaScript API fires `Ecwid.OnOrderPlaced` with the order rig
<script>
Ecwid.OnAPILoaded.add(function () {
Ecwid.OnOrderPlaced.add(function (order) {
- window.rybbit.event('purchase', {
+ window.rybbit?.event('purchase', {
transaction_id: order.vendorNumber,
value: order.total,
tax: order.tax,
@@ -79,7 +79,7 @@ Ecwid also has a **Custom tracking code on Order Confirmation page** field under
<script>
<#noescape>
document.addEventListener('DOMContentLoaded', function () {
- window.rybbit.event('purchase', { transaction_id: "${order.number}", value: ${order.total} });
+ window.rybbit?.event('purchase', { transaction_id: "${order.number}", value: ${order.total} });
});
</#noescape>
</script>
diff --git a/docs/content/docs/(docs)/guides/electron.mdx b/docs/content/docs/(docs)/guides/electron.mdx
index 2ec13af5b..18998d3e0 100644
--- a/docs/content/docs/(docs)/guides/electron.mdx
+++ b/docs/content/docs/(docs)/guides/electron.mdx
@@ -6,7 +6,6 @@ icon: SiElectron
---
import { Steps, Step } from "fumadocs-ui/components/steps";
-import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
An Electron renderer is a Chromium page, so Rybbit runs in it the same way it runs in a browser. For a renderer built with a bundler (Vite, webpack, the Electron Forge templates) install the `@rybbit/js` SDK and initialise it in the renderer entry file; for a plain HTML renderer put the snippet in the `<head>` of the HTML file the window loads. In both cases allow `https://app.rybbit.io` in the renderer's Content Security Policy.
diff --git a/docs/content/docs/(docs)/guides/fastapi.mdx b/docs/content/docs/(docs)/guides/fastapi.mdx
index f33f8f660..b2431185c 100644
--- a/docs/content/docs/(docs)/guides/fastapi.mdx
+++ b/docs/content/docs/(docs)/guides/fastapi.mdx
@@ -34,7 +34,7 @@ pip install pydantic-settings jinja2
Define the settings, reading from the environment and an optional `.env` file:
-```python filename="config.py"
+```python title="config.py"
from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -48,7 +48,7 @@ class Settings(BaseSettings):
settings = Settings()
```
-```bash filename=".env"
+```bash title=".env"
RYBBIT_INSTANCE_URL=https://app.rybbit.io
RYBBIT_SITE_ID=YOUR_SITE_ID
```
@@ -57,7 +57,7 @@ RYBBIT_SITE_ID=YOUR_SITE_ID
`Jinja2Templates` exposes its environment as `templates.env`, so add the settings as globals once, next to where you create the templates object:
-```python filename="main.py"
+```python title="main.py"
from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates
@@ -79,7 +79,7 @@ async def index(request: Request):
Open the template your pages extend, usually `templates/base.html`, and add the tag inside `<head>`:
-```jinja filename="templates/base.html"
+```jinja title="templates/base.html"
<head>
<meta charset="utf-8">
<title>{% block title %}My App{% endblock %}</title>
diff --git a/docs/content/docs/(docs)/guides/flask.mdx b/docs/content/docs/(docs)/guides/flask.mdx
index 0d71dc33c..23c599c93 100644
--- a/docs/content/docs/(docs)/guides/flask.mdx
+++ b/docs/content/docs/(docs)/guides/flask.mdx
@@ -21,21 +21,23 @@ Flask renders Jinja templates, and most apps extend a shared base layout, so the
#### Configure the site ID
-Flask loads any environment variable prefixed with `FLASK_` into `app.config` when you call `from_prefixed_env()`. Set the values in your environment (`flask run` also reads a `.env` file when python-dotenv is installed):
+Set the values in your environment (`flask run` also reads a `.env` file when python-dotenv is installed):
-```bash filename=".env"
-FLASK_RYBBIT_INSTANCE_URL=https://app.rybbit.io
-FLASK_RYBBIT_SITE_ID=YOUR_SITE_ID
+```bash title=".env"
+RYBBIT_INSTANCE_URL=https://app.rybbit.io
+RYBBIT_SITE_ID=YOUR_SITE_ID
```
-Then load them where you create the app:
+Then copy them into `app.config` where you create the app:
+
+```python title="app.py"
+import os
-```python filename="app.py"
from flask import Flask, render_template
app = Flask(__name__)
-app.config.setdefault("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
-app.config.from_prefixed_env()
+app.config["RYBBIT_INSTANCE_URL"] = os.environ.get("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")
+app.config["RYBBIT_SITE_ID"] = os.environ.get("RYBBIT_SITE_ID")
@app.route("/")
@@ -43,7 +45,7 @@ def index():
return render_template("index.html")
```
-`from_prefixed_env()` parses values as JSON where it can, so a numeric site ID arrives as an `int`. It renders the same in the template.
+Read the site ID with `os.environ` rather than `app.config.from_prefixed_env()`. That method parses values as JSON, which turns some site IDs, such as `123456e78901`, into floats that no longer match your site.
If you keep configuration in a Python file or class instead, add `RYBBIT_INSTANCE_URL` and `RYBBIT_SITE_ID` there and load it with `app.config.from_object()`.
@@ -51,7 +53,7 @@ If you keep configuration in a Python file or class instead, add `RYBBIT_INSTANC
Open the template that your pages extend, usually `templates/base.html` (or `templates/layout.html`), and add the tag inside `<head>`:
-```jinja filename="templates/base.html"
+```jinja title="templates/base.html"
<head>
<meta charset="utf-8">
<title>{% block title %}My App{% endblock %}</title>
@@ -76,10 +78,10 @@ Templates that do not extend the base layout need the same tag in their own `<he
## Troubleshooting
-- **Tag missing**: `from_prefixed_env()` reads the environment when the app is created, so restart the server after changing `FLASK_RYBBIT_SITE_ID`. Check `app.config["RYBBIT_SITE_ID"]` in `flask shell`.
+- **Tag missing**: the app reads the environment when it is created, so restart the server after changing `RYBBIT_SITE_ID`. Check `app.config["RYBBIT_SITE_ID"]` in `flask shell`.
- **Macros imported into other templates**: `config` is added to the render context, not to imported templates. A macro that outputs the tag must be imported `with context`.
- **Content Security Policy**: if you set one with Flask-Talisman or similar, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.
-- **Self-hosted instance**: set `FLASK_RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.
+- **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/flutter-web.mdx b/docs/content/docs/(docs)/guides/flutter-web.mdx
index 354186c28..1090f30a5 100644
--- a/docs/content/docs/(docs)/guides/flutter-web.mdx
+++ b/docs/content/docs/(docs)/guides/flutter-web.mdx
@@ -6,7 +6,6 @@ icon: SiFlutter
---
import { Steps, Step } from "fumadocs-ui/components/steps";
-import { Callout } from "fumadocs-ui/components/callout";
A Flutter web app is served from the `web/index.html` template in your project, which `flutter build web` copies to `build/web/index.html`. The snippet goes in that file's `<head>`. Flutter draws the UI into a canvas rather than DOM elements, so pageviews and manual events work as usual while anything that inspects the DOM does not.
diff --git a/docs/content/docs/(docs)/guides/gitbook.mdx b/docs/content/docs/(docs)/guides/gitbook.mdx
index af3170432..7004f8af9 100644
--- a/docs/content/docs/(docs)/guides/gitbook.mdx
+++ b/docs/content/docs/(docs)/guides/gitbook.mdx
@@ -8,12 +8,14 @@ icon: SiGitbook
import { Steps, Step } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";
-GitBook does not let you add custom scripts to a published site, and its integration platform does not let third parties inject them either. This page explains what that means and what your options are.
+GitBook does not let you add custom scripts to a published site, and its integration platform does not let third parties inject them either. Rybbit can't track GitBook-hosted pages today. The steps below cover your options for the docs and the snippet for the rest of your site.
<Steps>
<Step>
### Get your tracking snippet
+You need the snippet for the parts of your site outside GitBook, or for a docs host that accepts it (see the next step).
+
<include>../../../partials/guides/get-snippet.mdx</include>
</Step>
@@ -36,6 +38,8 @@ The rest of your site (marketing pages, app, blog) is unaffected: add the snippe
<Step>
### Verify installation
+Run this check on the pages where you added the snippet. GitBook-hosted pages won't appear in Rybbit.
+
<include>../../../partials/guides/verify.mdx</include>
</Step>
</Steps>
diff --git a/docs/content/docs/(docs)/guides/hubspot.mdx b/docs/content/docs/(docs)/guides/hubspot.mdx
index 814beb3bf..473363b46 100644
--- a/docs/content/docs/(docs)/guides/hubspot.mdx
+++ b/docs/content/docs/(docs)/guides/hubspot.mdx
@@ -61,7 +61,7 @@ HubSpot forms submit inside the page without a full reload, so track them with a
<script>
window.addEventListener("message", function (event) {
if (event.data.type === "hsFormCallback" && event.data.eventName === "onFormSubmitted") {
- window.rybbit.event("form_submitted", { formId: event.data.id });
+ window.rybbit?.event("form_submitted", { formId: event.data.id });
}
});
</script>
diff --git a/docs/content/docs/(docs)/guides/laravel.mdx b/docs/content/docs/(docs)/guides/laravel.mdx
index 458abcff1..3a1fa5a09 100644
--- a/docs/content/docs/(docs)/guides/laravel.mdx
+++ b/docs/content/docs/(docs)/guides/laravel.mdx
@@ -23,14 +23,14 @@ Laravel renders pages through Blade layouts, so the snippet goes into the layout
Add the Rybbit values to `.env`:
-```bash filename=".env"
+```bash title=".env"
RYBBIT_INSTANCE_URL=https://app.rybbit.io
RYBBIT_SITE_ID=YOUR_SITE_ID
```
Then register them in `config/services.php`:
-```php filename="config/services.php"
+```php title="config/services.php"
<?php
return [
@@ -49,7 +49,7 @@ Run `php artisan config:clear` if your configuration is cached, otherwise the ne
Open the Blade layout that wraps your pages. In a default install this is `resources/views/layouts/app.blade.php`; Breeze and Jetstream also ship `resources/views/layouts/guest.blade.php`, and Inertia apps use `resources/views/app.blade.php`. Add the tag inside `<head>`:
-```php filename="resources/views/layouts/app.blade.php"
+```php title="resources/views/layouts/app.blade.php"
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
diff --git a/docs/content/docs/(docs)/guides/magento.mdx b/docs/content/docs/(docs)/guides/magento.mdx
index 66860f053..916d46a7e 100644
--- a/docs/content/docs/(docs)/guides/magento.mdx
+++ b/docs/content/docs/(docs)/guides/magento.mdx
@@ -5,7 +5,6 @@ category: ecommerce
---
import { Steps, Step } from "fumadocs-ui/components/steps";
-import { Callout } from "fumadocs-ui/components/callout";
Magento Open Source and Adobe Commerce have a **Scripts and Style Sheets** field in the design configuration that prints HTML into the `<head>` of every storefront page, so no theme edits are needed. On 2.4.7 and later the checkout page runs under a strict Content Security Policy, so the tracker's host also needs a CSP whitelist entry before it loads there.
@@ -111,7 +110,7 @@ $purchase = [
?>
<script>
document.addEventListener('DOMContentLoaded', function () {
- window.rybbit.event('purchase', <?= /* @noEscape */ json_encode($purchase) ?>);
+ window.rybbit?.event('purchase', <?= /* @noEscape */ json_encode($purchase) ?>);
});
</script>
```
diff --git a/docs/content/docs/(docs)/guides/mintlify.mdx b/docs/content/docs/(docs)/guides/mintlify.mdx
index 7ac765ce1..38785dec0 100644
--- a/docs/content/docs/(docs)/guides/mintlify.mdx
+++ b/docs/content/docs/(docs)/guides/mintlify.mdx
@@ -22,7 +22,7 @@ Mintlify includes every `.js` file in your docs content directory on every page,
Create a JavaScript file in your content directory, next to `docs.json` and your `.mdx` pages:
-```javascript filename="rybbit.js"
+```javascript title="rybbit.js"
(function () {
var el = document.createElement("script");
el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
@@ -35,8 +35,14 @@ Commit and deploy. Mintlify picks the file up automatically; there is nothing to
To pass [script attributes](/docs/script#script-attributes) such as skip patterns, set them on the element before appending it:
-```javascript filename="rybbit.js"
-el.setAttribute("data-skip-patterns", JSON.stringify(["/internal/**"]));
+```javascript title="rybbit.js"
+(function () {
+ var el = document.createElement("script");
+ el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";
+ el.defer = true;
+ el.setAttribute("data-skip-patterns", JSON.stringify(["/internal/**"]));
+ document.head.appendChild(el);
+})();
```
<Callout type="info">
diff --git a/docs/content/docs/(docs)/guides/odoo.mdx b/docs/content/docs/(docs)/guides/odoo.mdx
index cfd13098e..feed4e1b2 100644
--- a/docs/content/docs/(docs)/guides/odoo.mdx
+++ b/docs/content/docs/(docs)/guides/odoo.mdx
@@ -43,7 +43,7 @@ Odoo eCommerce pages render standard HTML, so use `data-rybbit-event` attributes
<script>
document.addEventListener("click", function (e) {
if (e.target.closest("#add_to_cart")) {
- window.rybbit.event("add_to_cart");
+ window.rybbit?.event("add_to_cart");
}
});
</script>
diff --git a/docs/content/docs/(docs)/guides/phoenix.mdx b/docs/content/docs/(docs)/guides/phoenix.mdx
index 78c620de6..d7c24cb6a 100644
--- a/docs/content/docs/(docs)/guides/phoenix.mdx
+++ b/docs/content/docs/(docs)/guides/phoenix.mdx
@@ -23,7 +23,7 @@ Phoenix renders every page inside the root layout, `lib/my_app_web/components/la
`config/runtime.exs` runs when the app boots, including inside a release, so it is the right place to read environment variables. Add a `:rybbit` key for your app (replace `:my_app` with your OTP app name):
-```elixir filename="config/runtime.exs"
+```elixir title="config/runtime.exs"
config :my_app, :rybbit,
instance_url: System.get_env("RYBBIT_INSTANCE_URL", "https://app.rybbit.io"),
site_id: System.get_env("RYBBIT_SITE_ID")
@@ -40,7 +40,7 @@ export RYBBIT_SITE_ID=YOUR_SITE_ID
Templates in `lib/my_app_web/components/layouts/` are embedded into the `MyAppWeb.Layouts` module, so a function defined there is callable from `root.html.heex`. Add one that returns the config:
-```elixir filename="lib/my_app_web/components/layouts.ex"
+```elixir title="lib/my_app_web/components/layouts.ex"
defmodule MyAppWeb.Layouts do
use MyAppWeb, :html
@@ -54,7 +54,7 @@ end
Open `lib/my_app_web/components/layouts/root.html.heex` and add the tag inside `<head>`, after the existing `app.css` and `app.js` tags:
-```html filename="lib/my_app_web/components/layouts/root.html.heex"
+```html title="lib/my_app_web/components/layouts/root.html.heex"
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
diff --git a/docs/content/docs/(docs)/guides/rails.mdx b/docs/content/docs/(docs)/guides/rails.mdx
index 67866f050..1e5f6d2ec 100644
--- a/docs/content/docs/(docs)/guides/rails.mdx
+++ b/docs/content/docs/(docs)/guides/rails.mdx
@@ -23,14 +23,14 @@ Rails wraps every page in `app/views/layouts/application.html.erb`, so the snipp
Add the Rybbit values to your environment (`.env` if you use dotenv-rails, otherwise your host's environment settings):
-```bash filename=".env"
+```bash title=".env"
RYBBIT_INSTANCE_URL=https://app.rybbit.io
RYBBIT_SITE_ID=YOUR_SITE_ID
```
Then expose them through the `config.x` namespace in `config/application.rb`:
-```ruby filename="config/application.rb"
+```ruby title="config/application.rb"
module MyApp
class Application < Rails::Application
# ... existing configuration
@@ -45,7 +45,7 @@ end
Open `app/views/layouts/application.html.erb` and add the tag inside `<head>`, after the stylesheet and JavaScript tags:
-```erb filename="app/views/layouts/application.html.erb"
+```erb title="app/views/layouts/application.html.erb"
<head>
<title><%= content_for(:title) || "MyApp" %></title>
<meta name="viewport" content="width=device-width,initial-scale=1">
diff --git a/docs/content/docs/(docs)/guides/react/gatsby.mdx b/docs/content/docs/(docs)/guides/react/gatsby.mdx
index 5273b08c1..b0a5cc544 100644
--- a/docs/content/docs/(docs)/guides/react/gatsby.mdx
+++ b/docs/content/docs/(docs)/guides/react/gatsby.mdx
@@ -92,7 +92,7 @@ export default function TrackedButton({ label, eventName, eventData }) {
## Troubleshooting
-- **Pageviews missing after client-side navigation**: this is rare. If it happens, export `onRouteUpdate` from `gatsby-browser.js` and call `window.rybbit.pageview()` there when `location.pathname` changes. Test the default behaviour first.
+- **Pageviews missing after client-side navigation**: this is rare. If it happens, export `onRouteUpdate` from `gatsby-browser.js` and call `window.rybbit.pageview()` there when `location.pathname` changes. Skip the first call (`prevLocation` is `null`), because the script already tracks the landing page. Test the default behaviour first.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/react/remix.mdx b/docs/content/docs/(docs)/guides/react/remix.mdx
index 7014d350c..bbc993253 100644
--- a/docs/content/docs/(docs)/guides/react/remix.mdx
+++ b/docs/content/docs/(docs)/guides/react/remix.mdx
@@ -7,7 +7,7 @@ icon: SiRemix
import { Steps, Step } from "fumadocs-ui/components/steps";
-Remix renders the whole HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file and reaches every route.
+Remix renders the whole HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file and reaches every route. Remix v2 apps that have moved to React Router v7, its successor, should follow the [React Router guide](/docs/guides/react/react-router) instead.
<Steps>
<Step>
@@ -72,7 +72,7 @@ export default function OfferRoute() {
## Troubleshooting
-- **Pageviews missing after client-side navigation**: this is rare. If it happens, call `window.rybbit.pageview()` from a root-level effect that runs on `useLocation()` changes; test the default behaviour first.
+- **Pageviews missing after client-side navigation**: this is rare. If it happens, call `window.rybbit.pageview()` from a root-level effect that runs on `useLocation()` changes, skipping its first run because the script already tracks the landing page; test the default behaviour first.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/react/vite-cra.mdx b/docs/content/docs/(docs)/guides/react/vite-cra.mdx
index 49c0c2769..1206abe52 100644
--- a/docs/content/docs/(docs)/guides/react/vite-cra.mdx
+++ b/docs/content/docs/(docs)/guides/react/vite-cra.mdx
@@ -7,7 +7,7 @@ icon: SiReact
import { Steps, Step } from "fumadocs-ui/components/steps";
-A client-side React app built with Vite or Create React App has a single HTML entry file. Paste the snippet into its `<head>` and it loads on every route.
+A client-side React app built with Vite or Create React App has a single HTML entry file. Paste the snippet into its `<head>` and it loads on every route. Create React App is deprecated, so new projects should use Vite; the steps below still work for existing CRA apps.
<Steps>
<Step>
diff --git a/docs/content/docs/(docs)/guides/shopify.mdx b/docs/content/docs/(docs)/guides/shopify.mdx
index a30a37b81..f0ed5640d 100644
--- a/docs/content/docs/(docs)/guides/shopify.mdx
+++ b/docs/content/docs/(docs)/guides/shopify.mdx
@@ -51,7 +51,7 @@ Add to your main product template (`sections/main-product.liquid` or `templates/
<script>
document.addEventListener('DOMContentLoaded', function () {
var variant = {{ product.selected_or_first_available_variant | json }};
- window.rybbit.event('view_item', {
+ window.rybbit?.event('view_item', {
item_id: variant.sku || variant.id,
item_name: {{ product.title | json }},
item_variant: variant.title === 'Default Title' ? null : variant.title,
@@ -74,7 +74,7 @@ document.addEventListener('DOMContentLoaded', function () {
form.addEventListener('submit', function () {
var variant = {{ product.selected_or_first_available_variant | json }};
var qty = form.querySelector('[name="quantity"]');
- window.rybbit.event('add_to_cart', {
+ window.rybbit?.event('add_to_cart', {
item_id: variant.sku || variant.id,
item_name: {{ product.title | json }},
price: variant.price / 100,
@@ -97,7 +97,7 @@ document.addEventListener('DOMContentLoaded', function () {
if (!button) return;
button.addEventListener('click', function () {
var cart = {{ cart | json }};
- window.rybbit.event('begin_checkout', {
+ window.rybbit?.event('begin_checkout', {
currency: cart.currency,
value: cart.total_price / 100,
items: cart.items.map(function (item) {
@@ -113,7 +113,7 @@ Event properties are limited to 2048 characters of serialised JSON and larger pa
#### Purchase
-Checkout and the order status page do not load your theme, and the old **Order status page > Additional scripts** field is deprecated: view-only since August 28, 2025, with non-Plus stores required to migrate by August 26, 2026. Track purchases with a custom web pixel from [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations) instead.
+Checkout and the order status page do not load your theme, and the old **Order status page > Additional scripts** field is deprecated: it became view-only on August 28, 2025, and the migration deadline for non-Plus stores passed on August 26, 2026, so don't rely on scripts there. Track purchases with a custom web pixel from [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations) instead.
Pixels run in a sandbox with no access to `window.rybbit`, so the pixel posts the event straight to Rybbit's track endpoint.
@@ -150,7 +150,7 @@ analytics.subscribe("checkout_completed", (event) => {
});
```
-`checkout_completed` fires once per placed order. The same [Customer Events](https://shopify.dev/docs/api/customer-events) API also exposes `product_added_to_cart` and `checkout_started`, so you can move add-to-cart and begin-checkout into the pixel too if theme code is unreliable on your store.
+`checkout_completed` fires once per placed order. The same [Customer Events](https://shopify.dev/docs/api/web-pixels-api) API also exposes `product_added_to_cart` and `checkout_started`, so you can move add-to-cart and begin-checkout into the pixel too if theme code is unreliable on your store.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/squarespace.mdx b/docs/content/docs/(docs)/guides/squarespace.mdx
index 3e9880c19..b86cce7d2 100644
--- a/docs/content/docs/(docs)/guides/squarespace.mdx
+++ b/docs/content/docs/(docs)/guides/squarespace.mdx
@@ -11,7 +11,7 @@ import { Callout } from "fumadocs-ui/components/callout";
Squarespace injects custom HTML into every page through its **Code Injection** panel, so no template edits are needed.
<Callout type="warn">
-Code Injection is available on the **Business** and **Commerce** plans. It is not available on the Personal plan.
+Code Injection is available on the **Core**, **Plus** and **Advanced** plans, and on some legacy plans. It is not available on the Basic plan.
</Callout>
<Steps>
@@ -41,7 +41,7 @@ The **Footer** field also works and loads the script on every page. Leave the **
## Troubleshooting
-- **Code Injection is missing from Settings**: the site is on the Personal plan. Upgrade to Business or Commerce.
+- **Code Injection is missing from Settings**: the site's plan doesn't include it, such as Basic. Upgrade to Core, Plus or Advanced.
- **Only the checkout is tracked**: the snippet was pasted into **Order Confirmation Page** instead of **Header** or **Footer**.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/storyblok.mdx b/docs/content/docs/(docs)/guides/storyblok.mdx
index 2184c3dbd..84f49b820 100644
--- a/docs/content/docs/(docs)/guides/storyblok.mdx
+++ b/docs/content/docs/(docs)/guides/storyblok.mdx
@@ -56,7 +56,7 @@ The script tracks client-side route changes automatically, so navigation between
## Troubleshooting
- **Visual Editor previews count as visits**: the Visual Editor loads your frontend in an iframe at the **Preview URL** set under **Settings > Visual Editor**, appending `_storyblok` and `_storyblok_tk[...]` query parameters. Editors' preview sessions are tracked like real visitors. Point the Preview URL at a separate preview deployment registered as its own site in Rybbit, or leave the tag out of builds that use the preview token.
-- **Preview parameters in tracked URLs**: if the same deployment serves both the live site and the Visual Editor, the `_storyblok` parameters show up in tracked page URLs. Add `data-track-query="false"` to the script tag to drop query strings.
+- **Preview parameters in tracked URLs**: if the same deployment serves both the live site and the Visual Editor, the `_storyblok` parameters show up in tracked page URLs. Turn off [URL Parameters](/docs/site-settings#track-url-parameters) under **Site Settings β†’ Tracking** to drop query strings from tracked URLs. This drops UTM parameters too, so a separate preview deployment is the better fix if you track campaigns.
- **The Storyblok app is not tracked**: the snippet only runs in your frontend, so time spent in `app.storyblok.com` never appears in Rybbit.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/svelte/sveltekit.mdx b/docs/content/docs/(docs)/guides/svelte/sveltekit.mdx
index 011609c75..d285c6f9c 100644
--- a/docs/content/docs/(docs)/guides/svelte/sveltekit.mdx
+++ b/docs/content/docs/(docs)/guides/svelte/sveltekit.mdx
@@ -60,19 +60,21 @@ Call `window.rybbit.event()` from any Svelte component. Guard the call with `typ
}
</script>
-<button on:click={handleAction}>Perform action</button>
+<button onclick={handleAction}>Perform action</button>
```
+This uses Svelte 5 event attributes. On Svelte 4, write `on:click={handleAction}` instead.
+
## Troubleshooting
-- **Pageviews missing after navigation**: automatic route tracking covers SvelteKit's router, so test the default first. If a navigation is still not recorded, trigger it from `afterNavigate` in your root layout:
+- **Pageviews missing after navigation**: automatic route tracking covers SvelteKit's router, so test the default first. If a navigation is still not recorded, trigger it from `afterNavigate` in your root layout. Skip the initial load (`type` is `"enter"`): the script already tracks the landing page, and counting it again doubles it.
```svelte title="src/routes/+layout.svelte"
<script>
import { afterNavigate } from "$app/navigation";
- afterNavigate(() => {
- if (typeof window !== "undefined" && window.rybbit) {
+ afterNavigate(({ type }) => {
+ if (type !== "enter" && window.rybbit) {
window.rybbit.pageview();
}
});
diff --git a/docs/content/docs/(docs)/guides/svelte/vite.mdx b/docs/content/docs/(docs)/guides/svelte/vite.mdx
index 035078253..ef5d45117 100644
--- a/docs/content/docs/(docs)/guides/svelte/vite.mdx
+++ b/docs/content/docs/(docs)/guides/svelte/vite.mdx
@@ -61,9 +61,11 @@ Call `window.rybbit.event()` from any Svelte component:
}
</script>
-<button on:click={handleAction}>Perform action</button>
+<button onclick={handleAction}>Perform action</button>
```
+This uses Svelte 5 event attributes. On Svelte 4, write `on:click={handleAction}` instead.
+
## Troubleshooting
- **Pageviews missing after navigation**: Rybbit tracks History API and hash navigations, which covers routers such as `svelte-routing` and `svelte-spa-router`. If a route change is still not recorded, call `window.rybbit.pageview()` from that router's navigation callback.
diff --git a/docs/content/docs/(docs)/guides/vitepress.mdx b/docs/content/docs/(docs)/guides/vitepress.mdx
index 2e5b7527a..f7d072228 100644
--- a/docs/content/docs/(docs)/guides/vitepress.mdx
+++ b/docs/content/docs/(docs)/guides/vitepress.mdx
@@ -25,7 +25,7 @@ VitePress has a `head` option in `.vitepress/config.ts` that adds tags to every
<Tab>
Edit `.vitepress/config.ts` (or `.js` / `.mts`) and add the tag to `head`:
-```typescript filename=".vitepress/config.ts"
+```typescript title=".vitepress/config.ts"
import { defineConfig } from "vitepress";
export default defineConfig({
@@ -48,7 +48,7 @@ The empty string for `defer` is intentional. VitePress renders it as a boolean a
To track production only, make `head` conditional:
-```typescript filename=".vitepress/config.ts"
+```typescript title=".vitepress/config.ts"
const isProd = process.env.NODE_ENV === "production";
export default defineConfig({
@@ -62,7 +62,7 @@ export default defineConfig({
<Tab>
If you need runtime control, inject the tag from a custom theme. Create or edit `.vitepress/theme/index.ts`:
-```typescript filename=".vitepress/theme/index.ts"
+```typescript title=".vitepress/theme/index.ts"
import { type Theme } from "vitepress";
import DefaultTheme from "vitepress/theme";
diff --git a/docs/content/docs/(docs)/guides/vue/nuxt.mdx b/docs/content/docs/(docs)/guides/vue/nuxt.mdx
index 7e5344014..6fbe4c0a8 100644
--- a/docs/content/docs/(docs)/guides/vue/nuxt.mdx
+++ b/docs/content/docs/(docs)/guides/vue/nuxt.mdx
@@ -48,10 +48,10 @@ export default defineNuxtConfig({
Options:
- `siteId` (required): your Rybbit site ID.
-- `autoTrackPageview`: track pageviews automatically (on by default).
-- `trackSpa`: track client-side route changes (on by default).
- `analyticsHost`: script and API host for a self-hosted instance, for example `https://your-instance.com/api`.
-- `sessionReplay`, `webVitals`, `trackOutbound`: optional features.
+- `skipPatterns`, `maskPatterns`, `debounce`: passed to the script as the matching [script attributes](/docs/script#script-attributes). The module drops `debounce: 0`, so the script keeps its 500 ms default; use the `nuxt.config head` method if you need to turn debouncing off.
+
+The module also accepts `autoTrackPageview`, `trackSpa`, `trackQuery`, `trackOutbound`, `trackErrors`, `sessionReplay` and `webVitals`, but the current script ignores them. Turn those features on or off under **Site Settings β†’ Tracking** in your Rybbit dashboard instead.
<Callout type="info">
To keep the site ID out of source control, leave `siteId` unset and provide `NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID` in the environment; Nuxt Scripts reads it at runtime.
@@ -123,7 +123,7 @@ function handleAction() {
## Troubleshooting
-- **Pageviews missing after navigation**: both methods track Nuxt's client-side route changes automatically, so test the default first. If a route change is still not recorded, call `window.rybbit.pageview()` from a `router.afterEach` hook in a client plugin.
+- **Pageviews missing after navigation**: both methods track Nuxt's client-side route changes automatically, so test the default first. If a route change is still not recorded, call `window.rybbit.pageview()` from a `router.afterEach` hook in a client plugin. Skip the first navigation (`from` is `START_LOCATION` from `vue-router`), because the script already tracks the landing page.
## Next steps
diff --git a/docs/content/docs/(docs)/guides/vue/vite.mdx b/docs/content/docs/(docs)/guides/vue/vite.mdx
index c2853bf46..306122c4c 100644
--- a/docs/content/docs/(docs)/guides/vue/vite.mdx
+++ b/docs/content/docs/(docs)/guides/vue/vite.mdx
@@ -68,17 +68,18 @@ function trackAction() {
## Troubleshooting
-- **Pageviews missing after navigation**: Rybbit tracks Vue Router navigations automatically, so test the default first. If a route change is still not recorded, trigger it from an `afterEach` guard in your router setup:
+- **Pageviews missing after navigation**: Rybbit tracks Vue Router navigations automatically, so test the default first. If a route change is still not recorded, trigger it from an `afterEach` guard in your router setup. Skip the first navigation: the script already tracks the landing page, and counting it again doubles it.
```javascript title="src/router/index.js"
- import { createRouter, createWebHistory } from "vue-router";
+ import { createRouter, createWebHistory, START_LOCATION } from "vue-router";
const router = createRouter({
history: createWebHistory(import.meta.env.BASE_URL),
routes: [/* your routes */],
});
- router.afterEach(() => {
+ router.afterEach((to, from, failure) => {
+ if (from === START_LOCATION || failure) return;
if (window.rybbit) {
window.rybbit.pageview();
}
diff --git a/docs/content/docs/(docs)/guides/wix.mdx b/docs/content/docs/(docs)/guides/wix.mdx
index fc7b1b3d8..eb306591c 100644
--- a/docs/content/docs/(docs)/guides/wix.mdx
+++ b/docs/content/docs/(docs)/guides/wix.mdx
@@ -25,7 +25,7 @@ Custom code requires a **Wix Premium plan** and a **connected domain**. It is no
### Add the snippet to Wix
1. Open your site's dashboard and go to **Settings**.
-2. Open **Custom Code** (under **Advanced**). Older dashboards list it as **Tracking Tools & Analytics** under **Marketing & SEO**.
+2. Open **Custom Code** in the **Development & integrations** section. Older dashboards list it as **Tracking Tools & Analytics** under **Marketing & SEO**.
3. Click **+ Add Custom Code** and paste the snippet into the code box.
4. Name the code, for example `Rybbit`.
5. Under **Add Code to Pages**, choose **All pages** and **Load code once**. The script tracks Wix's client-side navigation itself, so loading it on every page change would inject it repeatedly.
diff --git a/docs/content/docs/(docs)/guides/woocommerce.mdx b/docs/content/docs/(docs)/guides/woocommerce.mdx
index 27b9771e5..4f4c151b0 100644
--- a/docs/content/docs/(docs)/guides/woocommerce.mdx
+++ b/docs/content/docs/(docs)/guides/woocommerce.mdx
@@ -81,7 +81,7 @@ function rybbit_track_purchase( $order_id ) {
?>
<script>
document.addEventListener('DOMContentLoaded', function () {
- window.rybbit.event('purchase', <?php echo wp_json_encode( $purchase ); ?>);
+ window.rybbit?.event('purchase', <?php echo wp_json_encode( $purchase ); ?>);
});
</script>
<?php
@@ -117,7 +117,7 @@ function rybbit_track_add_to_cart() {
var data = <?php echo wp_json_encode( $data ); ?>;
var qty = form.querySelector('input.qty');
data.quantity = qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1;
- window.rybbit.event('add_to_cart', data);
+ window.rybbit?.event('add_to_cart', data);
});
});
</script>
@@ -134,7 +134,7 @@ function rybbit_track_ajax_add_to_cart() {
<script>
jQuery(document.body).on('added_to_cart', function (event, fragments, cartHash, $button) {
if (!$button || !$button.length) return;
- window.rybbit.event('add_to_cart', {
+ window.rybbit?.event('add_to_cart', {
item_id: $button.data('product_id'),
quantity: $button.data('quantity') || 1,
source: 'ajax_add_to_cart'
diff --git a/docs/content/docs/(docs)/guides/wordpress.mdx b/docs/content/docs/(docs)/guides/wordpress.mdx
index 7137aa196..39afb81bb 100644
--- a/docs/content/docs/(docs)/guides/wordpress.mdx
+++ b/docs/content/docs/(docs)/guides/wordpress.mdx
@@ -9,7 +9,7 @@ import { Steps, Step } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
-WordPress has no built-in header-code setting, so the snippet goes in through a plugin such as **WPCode** or through your theme's `functions.php` or `header.php`. Every method below works on self-hosted WordPress.org sites; on WordPress.com you need the Business plan or higher before you can install plugins or add custom JavaScript.
+WordPress has no built-in header-code setting, so the snippet goes in through a plugin such as **WPCode** or through your theme's `functions.php` or `header.php`. Every method below works on self-hosted WordPress.org sites; on WordPress.com you need a paid plan (Personal, Premium, Business or Commerce) before you can install plugins.
<Steps>
<Step>
@@ -27,7 +27,7 @@ If you edit theme files, edit a **child theme**. Changes to a parent theme's `fu
<Tabs items={["WPCode", "functions.php", "header.php", "Mini plugin"]}>
<Tab>
-WPCode (formerly Insert Headers and Footers) is the recommended method: it survives theme updates, works with page builders, and is available on WordPress.com Business plans.
+WPCode (formerly Insert Headers and Footers) is the recommended method: it survives theme updates, works with page builders, and is available on every paid WordPress.com plan.
1. Go to **Plugins > Add New**, search for "WPCode", then install and activate it.
2. Go to **Code Snippets > Header & Footer** (**Settings > Insert Headers and Footers** in older versions).
@@ -35,7 +35,7 @@ WPCode (formerly Insert Headers and Footers) is the recommended method: it survi
</Tab>
<Tab>
-1. Go to **Appearance > Theme File Editor** and open your child theme's `functions.php`.
+1. Go to **Appearance > Theme File Editor** (**Tools > Theme File Editor** with a block theme) and open your child theme's `functions.php`.
2. Add this to the end of the file, replacing `YOUR_SITE_ID`:
```php
@@ -51,6 +51,8 @@ add_action( 'wp_head', 'rybbit_add_tracking_script' );
</Tab>
<Tab>
+Only classic themes have a `header.php`. Block themes, the default since Twenty Twenty-Two, build the header from block templates, so use WPCode, `functions.php` or the mini plugin instead.
+
1. Go to **Appearance > Theme File Editor** and open your child theme's `header.php`.
2. Paste the snippet just before the closing `</head>` tag:
@@ -104,7 +106,7 @@ Running WooCommerce? Once the snippet is in place, see the [WooCommerce guide](/
- **Script optimisers**: "Delay JavaScript execution" features in WP Rocket, Perfmatters and FlyingPress rebuild script tags and drop `data-*` attributes, which is why the snippet passes the site ID in the URL (`?siteId=`). If tracking still fails, exclude `app.rybbit.io` from optimisation: Autoptimize's exclusion list, WP Rocket's JavaScript optimisation and delay-JS exclusions, Perfmatters / FlyingPress delay-JS exclusions, LiteSpeed Cache JS excludes, SG Optimizer combine/minify.
- **Page builders** (Elementor, Divi, WPBakery, Beaver Builder): add the snippet with WPCode rather than a builder's custom HTML block. Builders sanitise HTML and can strip attributes from script tags.
- **Security plugins**: Wordfence, Sucuri and similar plugins can block external scripts. Add `app.rybbit.io` to the allowlist.
-- **WordPress.com plans**: Free, Personal and Premium plans cannot add custom JavaScript. Upgrade to Business or eCommerce and use the WPCode method.
+- **WordPress.com plans**: the Free plan cannot install plugins. Upgrade to any paid plan (Personal, Premium, Business or Commerce) and use the WPCode method.
## Next steps
diff --git a/docs/content/docs/(docs)/meta.json b/docs/content/docs/(docs)/meta.json
index 3ca2f8a7b..7d1558193 100644
--- a/docs/content/docs/(docs)/meta.json
+++ b/docs/content/docs/(docs)/meta.json
@@ -10,6 +10,7 @@
"---Usage---",
"script",
"script-troubleshooting",
+ "localhost-tracking",
"track-events",
"autocapture",
"identify-users",
@@ -42,7 +43,6 @@
"data-import",
"---Other---",
"definitions",
- "privacy",
- "contact"
+ "roadmap"
]
}
diff --git a/docs/content/partials/guides/get-snippet.mdx b/docs/content/partials/guides/get-snippet.mdx
index 039435f72..cdb7f2ff5 100644
--- a/docs/content/partials/guides/get-snippet.mdx
+++ b/docs/content/partials/guides/get-snippet.mdx
@@ -4,4 +4,4 @@ In your Rybbit dashboard, open **Site Settings β†’ Tracking Script** and copy yo
<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>
```
-`YOUR_SITE_ID` is the numeric ID of your site. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.
+`YOUR_SITE_ID` is your site's ID, a 12-character string such as `a1b2c3d4e5f6`. Older sites may use a numeric ID, which still works. If you self-host Rybbit, `app.rybbit.io` is the domain of your own instance.