πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
docs: standardize integration guides and add 56 platform guides (#1185)
Goldflag2c8d7fcd310c
diff --git a/.github/workflows/test.yml b/.github/workflows/test.ymlindex b78a5e350..874c46146 100644--- a/.github/workflows/test.yml+++ b/.github/workflows/test.yml@@ -38,6 +38,10 @@ jobs:working-directory: docsrun: npm ci+ - name: Lint integration guides+ working-directory: docs+ run: npm run lint:guides+- name: Run agent-readiness testsworking-directory: docsrun: npm run test:agent-readinessdiff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 1cfcc8a0a..c22e024e2 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -8,6 +8,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co- Build: `npm run build`- Production: `npm start`- Type Check: `tsc --noEmit`+- Lint integration guides: `npm run lint:guides` (rules in `content/partials/guides/README.md`; copy `TEMPLATE.mdx` for a new guide)## Project OverviewThis is the documentation and marketing website for Rybbit, built with Next.js 16 and Fumadocs. The site includes:diff --git a/docs/content/docs/(docs)/guides/angular.mdx b/docs/content/docs/(docs)/guides/angular.mdxindex d5d87fd95..f1191394d 100644--- a/docs/content/docs/(docs)/guides/angular.mdx+++ b/docs/content/docs/(docs)/guides/angular.mdx@@ -1,48 +1,27 @@---title: Angular-description: Integrate Rybbit Analytics with your Angular application+description: Add Rybbit analytics to your Angular app+category: frameworks+icon: SiAngular----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your Angular application.--## How to Add Rybbit to Your Angular App--The recommended and most common method is to add the Rybbit tracking script directly to your `src/index.html` file. This ensures the script is loaded early and reliably for your Angular application.--### Adding to `src/index.html`+An Angular CLI project serves one HTML shell, `src/index.html`, for every route. Paste the snippet into its `<head>` and the script loads once for the whole app.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet. It will look like this:--```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Remember to replace `YOUR_SITE_ID` with your actual Site ID.-</Step>--<Step>-### Locate Your `index.html` File+### Get your tracking snippet-In a standard Angular CLI project, this file is typically located at `src/index.html`.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Add the Snippet to `index.html`+### Add the snippet to Angular-Open `src/index.html` and paste the Rybbit tracking snippet just before the closing `</head>` tag or `</body>` tag. Placing it in the `<head>` is generally preferred for earlier loading.+Open `src/index.html` and paste the snippet just before `</head>`:-```html filename="src/index.html"+```html title="src/index.html"<!doctype html><html lang="en"><head>@@ -50,83 +29,57 @@ Open `src/index.html` and paste the Rybbit tracking snippet just before the clos<title>MyAngularApp</title><base href="/"><meta name="viewport" content="width=device-width, initial-scale=1">- <link rel="icon" type="image/x-icon" href="favicon.ico">- <!-- Rybbit Tracking Snippet -->- <script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer- ></script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script></head><body>- <app-root></app-root> <!-- Your root Angular component -->- <!-- If you prefer, you can also place the script here, before </body> -->+ <app-root></app-root></body></html>```-Make sure to replace `YOUR_SITE_ID` with your actual Site ID.++Placing it before `</body>` also works; `<head>` lets it start loading sooner. Navigation through the Angular Router is tracked automatically as pageviews.</Step><Step>-### Verify Installation+### Verify installation-After building and deploying your application, open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **SPA Page View Tracking**: Rybbit's tracking script is designed to automatically detect route changes in most Angular applications (using Angular Router) and track them as page views. If you find that page views are not being tracked correctly after navigation, you might need to manually trigger page views. You can subscribe to router events:- ```typescript- // In a relevant component or service- import { Router, NavigationEnd } from '@angular/router';- import { filter } from 'rxjs/operators';-- // ...- // constructor(private router: Router) {}- // ...-- // this.router.events.pipe(- // filter(event => event instanceof NavigationEnd)- // ).subscribe(() => {- // if (window.rybbit) {- // window.rybbit.pageview();- // }- // });- ```- However, test the default behavior first, as manual tracking might not be necessary.-</Callout>--## Custom Event Tracking--Once the Rybbit script is installed and loaded, you can track custom events from any of your Angular components or services:--```typescript-// Example in an Angular component-import { Component } from '@angular/core';--// Declare rybbit on window for TypeScript+## Track custom events++Declare `rybbit` on `window` once so TypeScript accepts the call, then call `window.rybbit.event()` from any component or service. Guard the call so a blocked script does not throw.++```typescript title="src/app/feature/feature.component.ts"+import { Component } from "@angular/core";+declare global {interface Window {rybbit?: {event: (eventName: string, eventData?: Record<string, any>) => void;pageview: () => void;- // Add other methods if you use them};}}@Component({- selector: 'app-my-feature',+ selector: "app-feature",template: `<button (click)="onFeatureClick()">Use Feature</button>`,})-export class MyFeatureComponent {+export class FeatureComponent {onFeatureClick(): void {- if (window.rybbit && typeof window.rybbit.event === 'function') {- window.rybbit.event('feature_used', { featureName: 'Amazing Feature' });- } else {- console.warn('Rybbit tracking not available.');+ if (window.rybbit) {+ window.rybbit.event("feature_used", { featureName: "Amazing Feature" });}}}```-Declaring `window.rybbit` helps with TypeScript type checking. Always ensure `window.rybbit` and its methods are available before calling them.\ No newline at end of file++## 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.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/aspnet.mdx b/docs/content/docs/(docs)/guides/aspnet.mdxnew file mode 100644index 000000000..a93f0b0a9--- /dev/null+++ b/docs/content/docs/(docs)/guides/aspnet.mdx@@ -0,0 +1,88 @@+---+title: ASP.NET Core+description: Add Rybbit analytics to your ASP.NET Core app+category: backend+icon: SiDotnet+---++import { Steps, Step } from "fumadocs-ui/components/steps";++ASP.NET Core MVC and Razor Pages apps share one layout file, `_Layout.cshtml`, that wraps every view, so the snippet goes into its `<head>`. Keep the site ID in `appsettings.json` and inject `IConfiguration` into the layout so nothing is hard-coded.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to ASP.NET Core++#### Configure the site ID++Add a `Rybbit` section to `appsettings.json`:++```json filename="appsettings.json"+{+ "Rybbit": {+ "InstanceUrl": "https://app.rybbit.io",+ "SiteId": "YOUR_SITE_ID"+ }+}+```++To keep the ID out of source control or vary it per environment, leave `SiteId` empty in `appsettings.json` and set it in `appsettings.Production.json`, or as the environment variable `Rybbit__SiteId` (double underscore separates configuration sections).++#### Add the tag to your layout++Open the layout file:++- Controllers with views: `Views/Shared/_Layout.cshtml`+- Razor Pages: `Pages/Shared/_Layout.cshtml`++Inject `IConfiguration` at the top and add the tag inside `<head>`:++```razor filename="Views/Shared/_Layout.cshtml"+@inject IConfiguration Configuration+@{+ var rybbitSiteId = Configuration["Rybbit:SiteId"];+ var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";+}+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <title>@ViewData["Title"] - MyApp</title>+ <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />++ @if (!string.IsNullOrEmpty(rybbitSiteId))+ {+ <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>+ }+</head>+```++If `Microsoft.Extensions.Configuration` is not already imported in `_ViewImports.cshtml`, add `@using Microsoft.Extensions.Configuration` above the `@inject` line.++The `@if` guard skips the tag when `SiteId` is empty, so development is not tracked unless you set the value there. If your app has more than one layout, add the tag to each, or move it into a partial view and render it with `<partial name="_Rybbit" />` from every layout.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Tag missing**: environment-specific files such as `appsettings.Development.json` override `appsettings.json`, so check which environment you are running (`ASPNETCORE_ENVIRONMENT`) and that the `Rybbit` section exists there or in the base file. Environment variables override both.+- **Content Security Policy**: if middleware adds a `Content-Security-Policy` header, add your Rybbit host to `script-src` and `connect-src`, or [proxy the script](/docs/proxy-guide) through your own domain.+- **Response caching or output caching**: the tag is rendered server-side, so a cached response keeps whatever configuration was active when it was cached. Clear the cache after changing the site ID.+- **Self-hosted instance**: set `Rybbit:InstanceUrl` to your own domain without a trailing slash; the layout appends the script path to it.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/astro.mdx b/docs/content/docs/(docs)/guides/astro.mdxindex e499bf8a3..df06c8b22 100644--- a/docs/content/docs/(docs)/guides/astro.mdx+++ b/docs/content/docs/(docs)/guides/astro.mdx@@ -1,140 +1,77 @@---title: Astro-description: Integrate Rybbit Analytics with your Astro application for content-rich websites+description: Add Rybbit analytics to your Astro site+category: frameworks+icon: SiAstro----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your Astro application for analytics tracking. Astro is a web framework for building content-rich websites, delivering minimal JavaScript by default.--## How to Add Rybbit to Your Astro Site--The most common way to add a global script like Rybbit's to an Astro site is by including it in a common layout component that is used across your pages, or directly within the `<head>` of your pages if you don't use a shared layout.+Astro pages share a layout component that renders the `<html>` document. Add the snippet to the `<head>` of that layout and every page that uses it is tracked.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet. It will look like this:+### Get your tracking snippet-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Remember to replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Add the Snippet to a Common Layout or Page Head--**Using a Common Layout (Recommended):**+### Add the snippet to Astro-If you have a common layout component (e.g., `src/layouts/Layout.astro` or similar) that wraps your pages, this is the best place to add the script.+Open your shared layout, usually `src/layouts/Layout.astro`, and paste the snippet inside `<head>`. Add `is:inline` so Astro leaves the tag as-is instead of bundling it:-Open your layout file and add the Rybbit script tag within the `<head>` section.--```astro filename="src/layouts/Layout.astro"+```astro title="src/layouts/Layout.astro"----// src/layouts/Layout.astro-export interface Props {- title: string;-}-const { title } = Astro.props;-const rybbitSiteId = "YOUR_SITE_ID"; // Replace with your actual Site ID---<!doctype html><html lang="en">- <head>- <meta charset="UTF-8" />- <meta name="description" content="Astro description" />- <meta name="viewport" content="width=device-width" />- <link rel="icon" type="image/svg+xml" href="/favicon.svg" />- <meta name="generator" content={Astro.generator} />- <title>{title}</title>-- <!-- Rybbit Tracking Snippet -->- <script- src="https://app.rybbit.io/api/script.js"- data-site-id={rybbitSiteId}- defer- ></script>- </head>- <body>- <slot /> <!-- Page content will be injected here -->- </body>+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width" />+ <title>{title}</title>+ <script is:inline src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ </head>+ <body>+ <slot />+ </body></html>```-Make sure to replace `YOUR_SITE_ID` with your actual Site ID.-**Adding Directly to Individual Pages (If not using a common layout):**+If you do not use a shared layout, add the same tag to the `<head>` of each page in `src/pages/`. A layout is easier to maintain.-If you don't have a common layout, you can add the script to the `<head>` of each `.astro` page file in your `src/pages/` directory. However, using a layout is more maintainable.+Astro builds a multi-page site by default, so each navigation is a full page load and a new pageview. With [view transitions](https://docs.astro.build/en/guides/view-transitions/) enabled, client-side navigation is tracked automatically when the URL changes.</Step><Step>-### Verify Installation+### Verify installation-After building and deploying your Astro site, open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded on your pages.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **Page View Tracking in Astro**:- - **MPA (Multi-Page Application) Mode**: By default, Astro builds multi-page applications. When a user navigates between different pages, a full page load occurs, and Rybbit's script will naturally track this as a new page view.- - **View Transitions**: If you are using Astro's [View Transitions API](https://docs.astro.build/en/guides/view-transitions/) for client-side navigation effects, Rybbit's script should generally still detect these as page views if the URL changes. However, if you notice issues, you might need to manually trigger page views. You can listen to Astro's `astro:after-swap` event:- ```javascript- // In a client-side script, perhaps in your common layout or a global script file- document.addEventListener('astro:after-swap', () => {- if (window.rybbit) {- window.rybbit.pageview();- }- });- ```- Test the default behavior first.-</Callout>--## Custom Event Tracking--You can track custom events from client-side JavaScript within your Astro site. This can be done in `<script>` tags within your `.astro` files or from JavaScript modules imported into Astro components (especially within UI framework components used as Astro islands).--**Example in an Astro component's client-side script:**-```astro-----// src/components/MyButton.astro-----<button id="my-astro-button">Click Me in Astro</button>+## Track custom events++Call `window.rybbit.event()` from a client-side `<script>` in any `.astro` component, or from inside a framework island the same way you would in that framework.++```astro title="src/components/TrackedButton.astro"+<button id="tracked-button">Click me</button><script>- document.getElementById('my-astro-button')?.addEventListener('click', () => {+ document.getElementById("tracked-button")?.addEventListener("click", () => {if (window.rybbit) {- window.rybbit.event('astro_button_click', { source: 'MyButton.astro' });+ window.rybbit.event("astro_button_click", { source: "TrackedButton.astro" });}});</script>```-**Example within a React/Vue/Svelte island component used in Astro:**+## Troubleshooting-If you're using a UI framework component (e.g., React) as an island in Astro, you'd track events from within that component's logic, similar to how you would in a standalone app of that framework:+- **Pageviews missing with view transitions**: this is rare. If it happens, listen for Astro's `astro:after-swap` event in a client-side script and call `window.rybbit.pageview()`; test the default behaviour first.+- **Proxying through your own domain**: Astro can serve the script from your domain with SSR middleware. See the [Astro proxy guide](/docs/proxy-guide/astro).-```jsx-// src/components/MyReactIsland.jsx (used in an .astro file)-import React from 'react';--export default function MyReactIsland() {- const handleClick = () => {- if (window.rybbit) {- window.rybbit.event('react_island_click', { island: 'MyReactIsland' });- }- };- return <button onClick={handleClick}>Click Me (React Island)</button>;-}-```+## Next steps-Always ensure `window.rybbit` is available before calling its methods in client-side scripts.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/bigcommerce.mdx b/docs/content/docs/(docs)/guides/bigcommerce.mdxindex 27e388479..1468fd32d 100644--- a/docs/content/docs/(docs)/guides/bigcommerce.mdx+++ b/docs/content/docs/(docs)/guides/bigcommerce.mdx@@ -1,130 +1,66 @@---title: BigCommerce-description: Integrate Rybbit Analytics with your BigCommerce store+description: Add Rybbit analytics to your BigCommerce store+category: ecommerce+icon: SiBigcommerce----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Tabs, Tab } from 'fumadocs-ui/components/tabs';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-BigCommerce is a leading e-commerce platform for online stores. You can integrate Rybbit Analytics to track visitor behavior and conversions.--## How to Add Rybbit to BigCommerce--<Tabs items={['Script Manager (Recommended)', 'Theme Files']}>-<Tab>-### Using Script Manager--The easiest way to add Rybbit to BigCommerce is through the Script Manager.+BigCommerce's **Script Manager** adds scripts to every storefront page without theme edits, and it is also where the order-confirmation purchase event goes. Editing the theme's `head.html` works too.<Steps><Step>-### Access Script Manager--1. Log in to your BigCommerce admin panel-2. Go to **Storefront** > **Script Manager**-3. Click **Create a Script**-</Step>--<Step>-### Configure the Script--Fill in the following settings:--- **Name**: Rybbit Analytics-- **Description**: Rybbit Analytics tracking script-- **Placement**: Head-- **Location**: All pages-- **Script category**: Analytics-- **Script type**: Script--In the **Script contents** box, paste:+### Get your tracking snippet-```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.defer = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();-</script>-```--Replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Save the Script+### Add the snippet to BigCommerce-Click **Save** to activate the script on your store.-</Step>-</Steps>+<Tabs items={["Script Manager", "Theme files"]}>+<Tab>+1. In the control panel, go to **Storefront > Script Manager** and click **Create a Script**.+2. Fill in the settings:+ - **Name**: Rybbit Analytics+ - **Placement**: Head+ - **Location**: All pages+ - **Script category**: Analytics+ - **Script type**: Script+3. Paste the snippet into **Script contents** and click **Save**.</Tab><Tab>-### Editing Theme Files--You can also add the script directly to your theme files for more control.-<Callout type="warn">-Editing theme files requires some technical knowledge. Make a backup of your theme before making changes.+Back up your theme before editing files.</Callout>-<Steps>-<Step>-### Access Theme Files--1. Go to **Storefront** > **Themes**-2. Click **Advanced** on your current theme-3. Select **Edit Theme Files**-</Step>--<Step>-### Edit the Header Template--1. Navigate to **templates** > **components** > **common**-2. Open `head.html`-3. Add the following code before the closing `</head>` or at the end of the file:--```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.defer = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();-</script>-```+1. Go to **Storefront > Themes**, click **Advanced** on your current theme, then **Edit Theme Files**.+2. Open **templates > components > common** and then `head.html`.+3. Paste the snippet at the end of the file, before the closing `</head>` tag, and click **Save**.+</Tab>+</Tabs></Step><Step>-### Save and Apply+### Verify installation-Click **Save** to apply the changes to your live store.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-</Tab>-</Tabs>--## Tracking E-commerce Events--To get the most out of Rybbit with BigCommerce, you can track key e-commerce events like product views and purchases.-### Track Purchases+## Track custom events-To track completed purchases, create another script in Script Manager with these settings:+#### Purchase-- **Placement**: Footer-- **Location**: Order Confirmation-- **Script type**: Script+Create a second script in Script Manager with **Placement: Footer**, **Location: Order Confirmation** and **Script type: Script**. BigCommerce runs Script Manager contents through Handlebars, so expressions such as `checkout.order.id` are filled in with the order data before the page is served:```html<script>-(function() {+(function () {function waitForRybbit(callback, timeout) {var start = Date.now();(function check() {@@ -136,8 +72,7 @@ To track completed purchases, create another script in Script Manager with these})();}- waitForRybbit(function() {- // BigCommerce provides order data via Handlebars+ waitForRybbit(function () {{{#if checkout.order}}window.rybbit.event('purchase', {transaction_id: '{{checkout.order.id}}',@@ -150,20 +85,13 @@ To track completed purchases, create another script in Script Manager with these</script>```-<Callout type="info">-BigCommerce uses Handlebars templating. The `{{}}` syntax is processed by BigCommerce to inject order data.-</Callout>+`waitForRybbit` polls until the tracking script from the head has defined `window.rybbit`, so the event is not lost if the confirmation page runs the footer script first.## Troubleshooting-### Script not loading--1. Check Script Manager to ensure the script is enabled-2. Clear your store's cache: **Server Settings** > **Store-level caching** > **Purge cache**-3. Check the browser console for any errors+- **Script not on the page**: confirm the script is enabled in Script Manager, then purge the store cache under **Server Settings > Store-level caching > Purge cache**.+- **Purchase event missing**: the purchase script must use the **Order Confirmation** location, and the `checkout.order`, `checkout.subtotal` and `checkout.currency` Handlebars objects depend on your BigCommerce checkout version. Place a test order to confirm the event arrives.-### E-commerce events not tracking+## Next steps-1. Make sure the purchase tracking script is set to **Order Confirmation** location-2. Verify the Handlebars variables match your BigCommerce version-3. Test by completing a test order+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/blazor.mdx b/docs/content/docs/(docs)/guides/blazor.mdxnew file mode 100644index 000000000..14524368a--- /dev/null+++ b/docs/content/docs/(docs)/guides/blazor.mdx@@ -0,0 +1,126 @@+---+title: Blazor+description: Add Rybbit analytics to your Blazor app+category: backend+icon: SiBlazor+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Where the snippet goes depends on the Blazor hosting model: a Blazor Web App keeps its `<head>` in `Components/App.razor`, a standalone Blazor WebAssembly app in `wwwroot/index.html`, and a Blazor Server app (.NET 7 and earlier) in `Pages/_Host.cshtml`. In each case the tag is added once and stays on the page while Blazor handles navigation client-side.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Blazor++<Tabs items={["Blazor Web App", "Blazor WebAssembly (standalone)", "Blazor Server (.NET 7 and earlier)"]}>+<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"+{+ "Rybbit": {+ "InstanceUrl": "https://app.rybbit.io",+ "SiteId": "YOUR_SITE_ID"+ }+}+```++Then inject `IConfiguration` in `Components/App.razor` and add the tag inside `<head>`:++```razor filename="Components/App.razor"+@inject IConfiguration Configuration+@{+ var rybbitSiteId = Configuration["Rybbit:SiteId"];+ var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";+}+<!DOCTYPE html>+<html lang="en">++<head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <base href="/" />+ <link rel="stylesheet" href="@Assets["app.css"]" />+ <HeadOutlet />++ @if (!string.IsNullOrEmpty(rybbitSiteId))+ {+ <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>+ }+</head>+```++Override the value per environment with `appsettings.Production.json` or the environment variable `Rybbit__SiteId`.+</Tab>++<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"+<head>+ <base href="/" />+ <link rel="stylesheet" href="css/app.css" />++ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+```++The site ID is public on every platform (it is in the page source), so a static value here is fine; `wwwroot/appsettings.json` is equally visible to the browser and offers no advantage for this value.+</Tab>++<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"+@page "/"+@using Microsoft.Extensions.Configuration+@inject IConfiguration Configuration+@{+ var rybbitSiteId = Configuration["Rybbit:SiteId"];+ var rybbitInstanceUrl = Configuration["Rybbit:InstanceUrl"] ?? "https://app.rybbit.io";+}+<!DOCTYPE html>+<html lang="en">+<head>+ <base href="~/" />+ <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />++ @if (!string.IsNullOrEmpty(rybbitSiteId))+ {+ <script src="@rybbitInstanceUrl/api/script.js?siteId=@rybbitSiteId" defer></script>+ }+</head>+```+</Tab>+</Tabs>++#### Navigation++Blazor's router, `NavigationManager.NavigateTo` and enhanced navigation in Blazor Web Apps all update the URL through `history.pushState` (or `replaceState` when `replace: true`) rather than reloading the page. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). Enhanced navigation patches the DOM without re-running scripts already in `<head>`, which is what you want: the tracker loads once and keeps running. `NavigateTo(url, forceLoad: true)` and links with `data-enhance-nav="false"` do a full page load, which the script tracks as a new pageview.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Tag missing in a Blazor Web App**: `App.razor` reads server-side configuration, so check the `appsettings` file for the active `ASPNETCORE_ENVIRONMENT`; environment variables override the files.+- **Blazor WebAssembly PWA**: `index.html` is cached by the service worker. Users receive the new tag only after the app is republished and the service worker updates.+- **Content Security Policy**: if you set one, 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 `Rybbit:InstanceUrl` (or the static URL in `index.html`) to your own domain without a trailing slash.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/bolt.mdx b/docs/content/docs/(docs)/guides/bolt.mdxnew file mode 100644index 000000000..f76faf9d9--- /dev/null+++ b/docs/content/docs/(docs)/guides/bolt.mdx@@ -0,0 +1,74 @@+---+title: Bolt+description: Add Rybbit analytics to your Bolt app+category: ai-builders+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Bolt has no settings field for custom head code (its **Analytics** project setting only shows traffic for published sites), so the snippet goes into the app's HTML head as a code change: prompt Bolt to add it, or switch to Code view and paste it into the root HTML or layout file. Publish the project again afterwards.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Bolt++<Tabs items={["Ask Bolt", "Edit the code"]}>+<Tab>+Paste this into the chat, with your snippet in place of the placeholder:++```text+Add this script tag to the <head> of every page and keep all existing head tags:+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+```++Review the change Bolt makes before you move on: the tag should be in the document head, not inside a component.+</Tab>++<Tab>+Click the **Code Preview** icon (`<>`) at the top center to switch to Code view, then open the file that owns the `<head>` for the framework Bolt chose:++- **Vite** projects (React, Vue, Svelte): `index.html` at the project root.+- **Next.js** projects: `app/layout.tsx`, using the `next/script` component as in the [Next.js guide](/docs/guides/react/next-js).+- Any other framework: ask Bolt "which file renders the HTML head?" and edit that one.++For a Vite project, paste the snippet before `</head>`:++```html title="index.html"+<head>+ <meta charset="UTF-8" />+ <title>My app</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+```++Click **Save** or press **Ctrl+S**.+</Tab>+</Tabs>++Publish the change: open the **Publish** menu and click **Publish** the first time, or **Update** for a site that is already live. In-app navigation is tracked as pageviews automatically.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Published site unchanged**: edits are not applied to the live site until you click **Update** in the **Publish** menu.+- **Bolt removed the tag**: later prompts can regenerate `index.html` or the layout. Right-click the file in the **Files** list and choose **Lock file** so Bolt leaves it alone, or add a line to the project's **Knowledge** telling it to keep the Rybbit script.+- **Expo (mobile) projects**: a script tag only runs in the web build. For the native app, use the [JavaScript SDK](/docs/sdks/web) instead.+- **Numbers differ from Bolt's Analytics**: Bolt's built-in counts include crawlers and bots; Rybbit filters them.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/bubble.mdx b/docs/content/docs/(docs)/guides/bubble.mdxindex 14c749815..dfe24fc1f 100644--- a/docs/content/docs/(docs)/guides/bubble.mdx+++ b/docs/content/docs/(docs)/guides/bubble.mdx@@ -1,129 +1,57 @@---title: Bubble.io-description: Integrate Rybbit Analytics with your Bubble.io application to track user behavior+description: Add Rybbit analytics to your Bubble.io app+category: builders----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your Bubble.io application to track user behavior, page views, and custom events.--## How to Add Rybbit to Your Bubble App--Bubble allows you to add custom code, including JavaScript snippets, to the header of your pages.+Bubble adds custom header code to every page of your app through the **SEO / metatags** settings tab, so the snippet goes there once and ships with your next deploy.<Steps><Step>-### Retrieve Your Tracking Script+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your code snippet. It will look like this:--```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Remember to replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Access Your Bubble App Settings+### Add the snippet to Bubble.io-- Open your Bubble application in the editor.-- Navigate to the **Settings** tab in the left-hand sidebar.-- Go to the **SEO / metatags** sub-tab.+1. Open your app in the Bubble editor and click the **Settings** tab in the left sidebar.+2. Open the **SEO / metatags** sub-tab.+3. Scroll to **Script/meta tags in header** and paste the snippet. It is added to the `<head>` of every page in the app.+4. Deploy the app to **Live**. The development version does not pick up the change until you deploy.</Step><Step>-### Add the Snippet to the Page Header+### Verify installation-- Scroll down to the section titled **"Script/meta tags in header"**.-- Paste your Rybbit tracking snippet into this box. This will add the script to the `<head>` section of every page in your Bubble app.--Alternatively, some Bubble plans or configurations might offer a dedicated section for "Advanced Settings" or "Custom Code" where header scripts can be placed globally or on specific pages. The "SEO / metatags" header script section is generally the most common place for global scripts.-</Step>--<Step>-### Deploy Your App--- After adding the script, ensure you deploy your Bubble application to the live version for the changes to take effect.-</Step>--<Step>-### Verify Installation--Open your live Bubble application and navigate through a few pages. Then, check your Rybbit dashboard to see if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **Page View Tracking in Bubble Apps**: Bubble applications often behave like Single Page Applications (SPAs) for navigation between "pages" (which are often groups shown/hidden on a single actual HTML page). Rybbit's script is designed to detect URL changes in SPAs.- - If your Bubble app uses actual URL route changes for different views, Rybbit should track these automatically.- - If navigation primarily involves showing/hiding groups without URL changes, Rybbit will only track the initial page load. For more granular tracking of "virtual" page views in such cases, you would need to use custom event tracking.- - If URL changes occur but are not automatically tracked, you might need to trigger `window.rybbit.pageview()` manually using a Bubble workflow action that runs JavaScript when a "page" (group) becomes visible.-</Callout>--## Custom Event Tracking in Bubble--You can track custom events in Bubble by using a workflow action that runs JavaScript.--<Steps>-<Step>-### Create a Workflow+## Track custom events-- In the Bubble editor, go to the **Workflow** tab.-- Create a new workflow triggered by the event you want to track (e.g., "When Button A is clicked", "When a user's data changes", "When a page is loaded" and a certain condition is met).-</Step>--<Step>-### Add "Run JavaScript" Action--- Within your workflow, add a new action.-- Search for and select the **"Run JavaScript"** action (this might be provided by a free official Bubble plugin or a community plugin if not available by default; ensure you have a way to execute arbitrary JS).-</Step>--<Step>-### Add Rybbit Tracking Code+Bubble workflows can run arbitrary JavaScript through a **Run JavaScript** action (provided by the free Toolbox plugin). Use it to send events from any workflow trigger.-- In the "Run JavaScript" action's code block, add your Rybbit event tracking code:+1. Open the **Workflow** tab and pick the trigger, for example *When Button Signup is clicked*.+2. Add a **Run JavaScript** action.+3. Paste the call, using Bubble's dynamic expressions for the values:```javascript-if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('bubble_event_name', {- // You can use Bubble's dynamic expressions here to pass data- // For example: 'User Email': Current User's Email,- // 'Clicked Element': This Button's Text (if applicable)- property1: 'value1',- property2: 'value2'+if (window.rybbit) {+ window.rybbit.event("signup_clicked", {+ plan: "Current User's Plan",});}```-Replace `'bubble_event_name'` with a descriptive name for your event. You can use Bubble's dynamic data expressions within the JavaScript if the "Run JavaScript" action supports it, or pass data into the JavaScript action from previous workflow steps.-**Example:** If tracking a button click for a specific item:-```javascript-// Assuming you can pass dynamic data to the JS action-// let itemName = "Dynamic Item Name from Bubble"; // This would be set by Bubble's dynamic data-// let itemCategory = "Dynamic Category from Bubble";--if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('item_interaction', {- name: itemName, // Replace with actual dynamic data- category: itemCategory // Replace with actual dynamic data- });-}-```-</Step>+## Troubleshooting-<Step>-### Test Your Event+- **Only the first pageview is tracked**: Bubble apps that switch between groups on a single page do not change the URL, so there is nothing for the script to detect. Add a **Run JavaScript** action that calls `window.rybbit.pageview()` when the group becomes visible, or track those views as custom events. Apps that navigate between real Bubble pages are tracked automatically.+- **Snippet missing on the live site**: the header script is versioned with your app, so check that you deployed to Live after saving the setting.-- Preview your Bubble app and trigger the workflow.-- Check your Rybbit dashboard to see if the custom event data is being received.-</Step>-</Steps>+## Next steps-By adding the global script and using "Run JavaScript" workflow actions, you can effectively integrate Rybbit analytics into your Bubble.io application.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/capacitor.mdx b/docs/content/docs/(docs)/guides/capacitor.mdxnew file mode 100644index 000000000..018fc48bc--- /dev/null+++ b/docs/content/docs/(docs)/guides/capacitor.mdx@@ -0,0 +1,78 @@+---+title: Capacitor+description: Add Rybbit analytics to your Capacitor app+category: apps+icon: SiCapacitor+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Capacitor wraps a normal web app in a native WebView, so the snippet goes in the `<head>` of that web app's `index.html` and ships to iOS and Android with `npx cap sync`. If the app is built with Ionic Angular, React or Vue, follow the [Angular](/docs/guides/angular), [React](/docs/guides/react/vite-cra) or [Vue](/docs/guides/vue/vite) guide for where the tag lives, then come back here for the WebView origin settings.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Capacitor++1. Paste the snippet into the `<head>` of your web app's `index.html` (the file in the `webDir` folder from `capacitor.config`, after your framework's build):++```html title="index.html"+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+```++2. Enable `CapacitorHttp`, which routes `window.fetch` through native HTTP. The iOS WebView runs on `capacitor://localhost`, and Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so without this the browser blocks the requests on iOS:++```ts title="capacitor.config.ts"+import type { CapacitorConfig } from "@capacitor/cli";++const config: CapacitorConfig = {+ appId: "com.example.app",+ appName: "My App",+ webDir: "dist",+ plugins: {+ CapacitorHttp: {+ enabled: true,+ },+ },+};++export default config;+```++3. Build the web app, then copy it into the native projects:++```bash+npm run build+npx cap sync+```++Android serves the app from `https://localhost` (`server.androidScheme` defaults to `https`), which is a regular origin, so tracking works there with or without `CapacitorHttp`. In-app route changes are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.++<Callout type="info">+Use the script tag rather than the `@rybbit/js` npm package on Capacitor. The package sends events with `navigator.sendBeacon`, which `CapacitorHttp` does not patch, so its requests from `capacitor://localhost` are still blocked on iOS.+</Callout>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Works on Android and in the browser, silent on iOS**: `CapacitorHttp` is not enabled, or the native projects were not re-synced after changing the config. Run `npx cap sync` and rebuild in Xcode.+- **Changes do not appear on device**: `npx cap sync` copies the built web bundle; edit the source, rebuild the web app, then sync again.+- **Live reload during development**: with `server.url` pointing at your dev server the WebView loads an `http://` origin, so requests succeed even without `CapacitorHttp`. Do not read a working dev build as proof that the production build is configured.+- **Every pageview shows `localhost` as hostname**: expected. `server.hostname` defaults to `localhost` on both platforms; filter by site, not hostname.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/carrd.mdx b/docs/content/docs/(docs)/guides/carrd.mdxindex 50eddd385..fb40e17e2 100644--- a/docs/content/docs/(docs)/guides/carrd.mdx+++ b/docs/content/docs/(docs)/guides/carrd.mdx@@ -1,72 +1,63 @@---title: Carrd-description: Integrate Rybbit Analytics with your Carrd site+description: Add Rybbit analytics to your Carrd site+category: builders+icon: SiCarrd----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";-Carrd is a popular platform for building simple, responsive one-page sites. You can add Rybbit Analytics to track visitors on your Carrd site.+Carrd builds one-page sites, and the snippet goes into the **Head** embed code field in the site settings.<Callout type="warn">-Adding custom code requires a **Carrd Pro** subscription (Pro Standard or Pro Plus). The custom-code Embeds feature is not included on Pro Lite.+Custom head code requires a **Carrd Pro** subscription (Pro Standard or Pro Plus). The Embed Code feature is not included on Pro Lite.</Callout>-## How to Add Rybbit to Carrd-<Steps><Step>-### Open Your Site Settings+### Get your tracking snippet-1. Log in to Carrd and open your site in the editor-2. Click on the **Settings** icon (gear) in the top right-3. Select the **Settings** tab+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Add Head Code+### Add the snippet to Carrd-1. Scroll down to the **Head** section under "Embed Code"-2. Paste the following code:+1. Open your site in the Carrd editor and click the **Settings** gear in the top right.+2. Open the **Settings** tab and scroll to **Embed Code**.+3. Paste the following into the **Head** field:```html<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.defer = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();+ (function () {+ var s = document.createElement("script");+ s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";+ s.defer = true;+ document.head.appendChild(s);+ })();</script>```-Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.+This wraps the snippet in a small loader so Carrd's embed processing cannot rewrite the tag.++4. Click **Save**, then **Publish**. Changes are not live until you publish.++If your site has multiple pages (a Pro Plus feature), the head code loads on all of them.</Step><Step>-### Publish Your Site+### Verify installation-Click **Save** then **Publish** to apply the changes to your live site.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">-We use the JavaScript approach instead of a plain script tag because some site builders may strip `data-*` attributes during processing.-</Callout>--## Using Multiple Pages--If your Carrd site has multiple pages (Pro Plus feature), the tracking script in the head code will automatically load on all pages.-## Troubleshooting-### Script not working--1. Make sure you have a Carrd Pro subscription-2. Ensure you published the site after adding the code-3. Check "View Page Source" on your live site and search for `rybbit`+- **The Head field is missing**: the site is on Pro Lite or the free plan. Upgrade to Pro Standard or Pro Plus.+- **Snippet not in the page source**: the site was saved but not published. Publish again from the editor.-### Form submissions+## Next steps-To track form submissions as events, you can add a custom event using Carrd's form settings or by adding additional JavaScript in the embed code section.+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/chrome-extension.mdx b/docs/content/docs/(docs)/guides/chrome-extension.mdxnew file mode 100644index 000000000..0026642d0--- /dev/null+++ b/docs/content/docs/(docs)/guides/chrome-extension.mdx@@ -0,0 +1,94 @@+---+title: Chrome extension+description: Add Rybbit analytics to your Chrome extension+category: apps+icon: SiGooglechrome+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Manifest V3 requires every piece of executable code to ship inside the extension package, and the `extension_pages` Content Security Policy is fixed at `script-src 'self' 'wasm-unsafe-eval'; object-src 'self'` with no way to relax it. A remote `<script>` tag can therefore never load in an extension page. Bundle the `@rybbit/js` SDK into your popup, options or side panel page instead, and grant `host_permissions` for the analytics host.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>++You only need the site ID from the snippet; the script tag itself is not used in an extension.+</Step>++<Step>+### Add the snippet to Chrome extension++1. Install the SDK in the extension project:++```bash+npm install @rybbit/js+```++2. Initialise it in the entry script of each extension page you want to track (the popup from `action.default_popup`, the options page from `options_ui.page`, the side panel from `side_panel.default_path`). The SDK needs `window` and `document`, so do not import it in the service worker.++```js title="src/popup.js"+import rybbit from "@rybbit/js";++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");+```++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"+{+ "manifest_version": 3,+ "host_permissions": ["https://app.rybbit.io/*"]+}+```++4. Build the extension with your bundler (Vite, webpack, Rollup) so `@rybbit/js` ends up inside the package, then reload the unpacked extension at `chrome://extensions`.++The default extension CSP does not restrict `connect-src`, so no `content_security_policy` entry is required. If you define your own policy, add `https://app.rybbit.io` to its `connect-src`.++<Callout type="warn">+Do not initialise the SDK in a content script. Content scripts run inside third-party websites; tracking there records other people's pages under your site ID, and content scripts are subject to the host page's same-origin policy in any case.+</Callout>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `rybbit.event()` from the page script, or use data attributes on buttons in your popup HTML:++```js title="src/popup.js"+document.getElementById("save")?.addEventListener("click", () => {+ rybbit.event("settings_saved", { theme: "dark" });+});+```++```html title="popup.html"+<button data-rybbit-event="upgrade_click" data-rybbit-prop-plan="pro">Upgrade</button>+```++## Troubleshooting++- **`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.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/circle.mdx b/docs/content/docs/(docs)/guides/circle.mdxnew file mode 100644index 000000000..708212ec5--- /dev/null+++ b/docs/content/docs/(docs)/guides/circle.mdx@@ -0,0 +1,52 @@+---+title: Circle+description: Add Rybbit analytics to your Circle community+category: creators+icon: SiCircle+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Circle has a **Code snippets** setting that injects custom code into the `<head>` of every page in your community, so the snippet goes there once and covers public pages and logged-in member pages alike.++<Callout type="info">+Custom CSS/JavaScript snippets are included on all current Circle plans (Professional, Business and Circle Plus).+</Callout>++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Circle++1. Open your community as an admin and go to **Settings**.+2. Open **Code snippets**.+3. Paste the snippet into the **Head code snippets** field.+4. Click **Save**. Changes apply to the whole community immediately; there is no publish step.++Circle's own help article for this setting is [Custom code snippets](https://help.circle.so/p/administration/site-management/custom-code-snippets).++Circle is a single-page app: after the first load, navigating between spaces, posts and courses changes the URL without a full reload. The script tracks these client-side route changes automatically, so each space and post shows up as its own pageview.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Custom domain**: the same head code is served on `yourcommunity.circle.so` and on your custom domain. If both hostnames are in use, keep them under one site in Rybbit so sessions are not split.+- **Post embeds**: custom HTML embedded inside a post is scoped to that post. Put the snippet in head code snippets, not in a post.+- **Nothing tracked while logged in as admin**: Circle applies head code to admins too, so check that your own IP or user is not excluded in Rybbit's site settings before assuming the snippet is missing.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/clickfunnels.mdx b/docs/content/docs/(docs)/guides/clickfunnels.mdxnew file mode 100644index 000000000..bafe424ca--- /dev/null+++ b/docs/content/docs/(docs)/guides/clickfunnels.mdx@@ -0,0 +1,66 @@+---+title: ClickFunnels+description: Add Rybbit analytics to your ClickFunnels funnels+category: landing+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++ClickFunnels 2.0 has a **Header Code** field at three levels: **Site Settings** for the whole workspace, **Funnel settings** for every page in one funnel, and the page editor for a single page. Add the snippet at the widest level you want tracked and leave the narrower ones empty so it is not loaded twice.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to ClickFunnels++<Tabs items={["Whole site", "One funnel", "One page"]}>+<Tab>+1. In your workspace, open the **Site & Blog** app in the left menu and click **Site Settings**.+2. Paste the snippet into **Header Code**.+3. Save.++This applies to every page in the workspace: funnel pages, store pages, courses, blog posts and site pages.+</Tab>++<Tab>+1. Open **Funnels** and click the **Settings** gear next to the funnel (or the **Settings** button in the top-right of the funnel workflow editor).+2. Paste the snippet into **Head Code**.+3. Click **Update Funnel**.++The code loads on every page of that funnel only.+</Tab>++<Tab>+1. Open the page in the page editor.+2. Go to **Settings > Tracking Code** and paste the snippet into **Header Code**.+3. Click **Save**.++The code loads on this page only.+</Tab>+</Tabs>++Save, then open the live page URL to test: header code does not run inside the page editor.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Duplicate pageviews**: the snippet is present at more than one level (site and funnel, or funnel and page). Keep a single copy.+- **Snippet not in the page source**: check which level you pasted it at. Site Settings covers the workspace, funnel settings cover that funnel's pages only, and the page editor covers one page.+- **jQuery**: ClickFunnels pages already include jQuery, so do not load it again in the same header code block; a second copy can break page scripts.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/contentful.mdx b/docs/content/docs/(docs)/guides/contentful.mdxindex 3ee246f05..44e4d9ad6 100644--- a/docs/content/docs/(docs)/guides/contentful.mdx+++ b/docs/content/docs/(docs)/guides/contentful.mdx@@ -1,80 +1,61 @@---title: Contentful-description: Integrate Rybbit Analytics with your Contentful-powered website+description: Add Rybbit analytics to your Contentful site+category: cms+icon: SiContentful----import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-Contentful is an enterprise headless CMS that delivers content via API. Since Contentful is headless, you'll add Rybbit Analytics to your frontend application rather than to Contentful itself.+Contentful is a headless CMS: it stores content and delivers it over its APIs, but never renders your pages. The tracking snippet therefore goes into the frontend that consumes Contentful, not into Contentful itself.-<Callout type="info">-Contentful only manages and delivers your content - it doesn't serve your website. The tracking script goes in your frontend framework (Next.js, Gatsby, Nuxt, etc.).-</Callout>--## How to Add Rybbit with Contentful--Choose the guide that matches your frontend framework:--### React-based Frontends-- **[Next.js](/docs/guides/react/next-js)** - Most common choice with Contentful-- **[Gatsby](/docs/guides/react/gatsby)** - Has official Contentful plugin-- **[Remix](/docs/guides/react/remix)**-- **[Vite + React](/docs/guides/react/vite-cra)**--### Vue-based Frontends-- **[Nuxt](/docs/guides/vue/nuxt)**-- **[Vite + Vue](/docs/guides/vue/vite)**--### Other Frontends-- **[Astro](/docs/guides/astro)**-- **[SvelteKit](/docs/guides/svelte/sveltekit)**-- **[Angular](/docs/guides/angular)**+<Steps>+<Step>+### Get your tracking snippet-## Quick Example: Next.js with Contentful+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-If you're using Next.js (the most common Contentful frontend), add the tracking script to your root layout:+<Step>+### Add the snippet to Contentful-```tsx-// app/layout.tsx-import Script from 'next/script'--export default function RootLayout({- children,-}: {- children: React.ReactNode-}) {- return (- <html lang="en">- <head>- <Script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- strategy="afterInteractive"- />- </head>- <body>{children}</body>- </html>- )-}-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.--## Quick Example: Gatsby with Contentful--If you're using Gatsby, add to your `gatsby-ssr.js`:--```javascript-import React from 'react'+<Callout type="info">+Contentful has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Contentful.+</Callout>-export const onRenderBody = ({ setHeadComponents }) => {- setHeadComponents([- <script- key="rybbit"- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer- />- ])-}-```+<Tabs items={["Next.js", "Nuxt", "Other frontends"]}>+<Tab>+Next.js is the most common Contentful frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).+</Tab>+<Tab>+Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).+</Tab>+<Tab>+- [Gatsby](/docs/guides/react/gatsby), which pairs with the official `gatsby-source-contentful` plugin+- [Remix](/docs/guides/react/remix)+- [Vite + React](/docs/guides/react/vite-cra)+- [Vite + Vue](/docs/guides/vue/vite)+- [Astro](/docs/guides/astro)+- [SvelteKit](/docs/guides/svelte/sveltekit)+- [Angular](/docs/guides/angular)+</Tab>+</Tabs>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Editor previews count as visits**: Contentful's content preview URLs open a preview or draft build of your frontend. Register that deployment as a separate site in Rybbit, or leave the snippet out of preview builds, so editors' previews are not mixed into your production data.+- **The Contentful web app is not tracked**: the snippet only runs on your frontend, so time spent editing in Contentful never appears in Rybbit.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/craft-cms.mdx b/docs/content/docs/(docs)/guides/craft-cms.mdxnew file mode 100644index 000000000..80ef66f05--- /dev/null+++ b/docs/content/docs/(docs)/guides/craft-cms.mdx@@ -0,0 +1,70 @@+---+title: Craft CMS+description: Add Rybbit analytics to your Craft CMS site+category: cms+icon: SiCraftcms+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Craft CMS renders pages from Twig templates in the `templates/` folder, so the snippet goes into the base template that your section templates extend. A fresh `craftcms/craft` project ships a single `templates/index.twig` containing the full HTML document; most projects move that boilerplate into a base template and `{% extends %}` it.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Craft CMS++1. Open the template that owns your `<head>`. In a fresh install that is `templates/index.twig`; in a project with a base template it is the underscore-prefixed file every page extends, such as `templates/_layout.twig`.+2. Add the tag before `</head>`:++```twig title="templates/_layout.twig"+<!DOCTYPE html>+<html lang="{{ currentSite.language }}">+<head>+ <meta charset="utf-8">+ <title>{{ siteName }}</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+<body>+ {% block content %}{% endblock %}+</body>+</html>+```++3. Every section template that extends the base template now loads the script:++```twig title="templates/blog/_entry.twig"+{% extends "_layout" %}++{% block content %}+ <h1>{{ entry.title }}</h1>+ {{ entry.body }}+{% endblock %}+{% endraw %}+```++To keep the site ID out of templates and vary it per environment, read it from `.env` with `{{ getenv('RYBBIT_SITE_ID') }}`, or store it in a Global Set and use `{{ settings.rybbitSiteId }}`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Template caching**: if you wrap the head in `{% cache %}` tags, the change appears only after the cache expires or you run `php craft clear-caches/all`.+- **Live Preview counts as visits**: the control panel's Live Preview renders your template in an iframe with `x-craft-live-preview` in the query string. Wrap the tag in `{% if not craft.app.request.isPreview %}` to leave editors' previews out of your data.+- **Control panel is not tracked**: `/admin` uses Craft's own templates, so the snippet never runs there.+- **Multiple base templates**: if some sections extend a different base (for example `_layout-landing.twig`), add the tag to each one, or move it into a partial and `{% include %}` it from every base.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/discourse.mdx b/docs/content/docs/(docs)/guides/discourse.mdxnew file mode 100644index 000000000..a9bd4a7da--- /dev/null+++ b/docs/content/docs/(docs)/guides/discourse.mdx@@ -0,0 +1,46 @@+---+title: Discourse+description: Add Rybbit analytics to your Discourse forum+category: other+icon: SiDiscourse+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Discourse adds site-wide code through **theme components**. A component has an editable `</head>` section that Discourse injects into every page and, because Discourse ships a strict Content Security Policy, it stamps the required nonce onto script tags placed there. No server access or plugin is needed.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Discourse++1. In the admin sidebar open **Appearance β Themes and components** (older versions: **Admin β Customize β Themes**).+2. On the **Components** tab click **Install**, choose **Create new**, name it "Rybbit Analytics", make sure the type is **Component** and click **Create**.+3. Click **Edit CSS/HTML**, stay on the **Common** tab and open the **`</head>`** section (not **Header**, which is the visible page header).+4. Paste the snippet and click **Save**.+5. Back on the component page, add your active theme under **Include component on these themes** so the component is enabled.++Discourse is a single-page app: after the first load, topics and categories open without a full page reload. The tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`, so those navigations are recorded as pageviews.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Component saved but the script is missing from the page source**: the component is not attached to the active theme. Add the theme under **Include component on these themes**, or add the component from the theme's **Included components** list.+- **Script tag present but blocked**: check the browser console for a CSP error. Scripts added through the `</head>` section receive Discourse's nonce automatically; scripts injected any other way (for example from a plugin's raw HTML) do not.+- **Only the first pageview is recorded**: the **SPA Navigation** setting is off for the site in your Rybbit dashboard. Turn it on under Site Settings.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/django.mdx b/docs/content/docs/(docs)/guides/django.mdxnew file mode 100644index 000000000..9c5de9dee--- /dev/null+++ b/docs/content/docs/(docs)/guides/django.mdx@@ -0,0 +1,106 @@+---+title: Django+description: Add Rybbit analytics to your Django app+category: backend+icon: SiDjango+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Django pages extend a base template, so the snippet goes into the `<head>` of that base template. Put the site ID in `settings.py`, read from an environment variable, and pass it to templates with a small context processor so no template hard-codes the ID.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Django++#### Configure the site ID++Add the Rybbit values to `settings.py`, reading from the environment:++```python filename="settings.py"+import os++RYBBIT_INSTANCE_URL = os.environ.get("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")+RYBBIT_SITE_ID = os.environ.get("RYBBIT_SITE_ID", "")+```++Set `RYBBIT_SITE_ID=YOUR_SITE_ID` in your production environment (or your `.env` file if you load one with django-environ or python-dotenv).++#### Expose the values to templates++Create a context processor that adds both settings to every template context:++```python filename="myproject/context_processors.py"+from django.conf import settings+++def rybbit(request):+ return {+ "RYBBIT_INSTANCE_URL": settings.RYBBIT_INSTANCE_URL,+ "RYBBIT_SITE_ID": settings.RYBBIT_SITE_ID,+ }+```++Register it under `TEMPLATES` in `settings.py`:++```python filename="settings.py"+TEMPLATES = [+ {+ "BACKEND": "django.template.backends.django.DjangoTemplates",+ "DIRS": [BASE_DIR / "templates"],+ "APP_DIRS": True,+ "OPTIONS": {+ "context_processors": [+ "django.template.context_processors.request",+ "django.contrib.auth.context_processors.auth",+ "django.contrib.messages.context_processors.messages",+ "myproject.context_processors.rybbit",+ ],+ },+ },+]+```++#### Add the tag to your base template++Open the template that every page extends, usually `templates/base.html`, and add the tag inside `<head>`:++```jinja filename="templates/base.html"+<head>+ <meta charset="utf-8">+ <title>{% block title %}My Site{% endblock %}</title>++ {% if RYBBIT_SITE_ID %}+ <script src="{{ RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ RYBBIT_SITE_ID }}" defer></script>+ {% endif %}+</head>+```++The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable.++Pages that do not `{% extends "base.html" %}` (for example a separate admin or landing template) need the same tag in their own `<head>`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Tag missing**: settings are read at startup, so restart the server (or your WSGI/ASGI workers) after changing `RYBBIT_SITE_ID`. Confirm the context processor path matches your project package name.+- **Template rendered without a request**: context processors only run for templates rendered with a `RequestContext`, which `render()` and class-based views provide. `Template.render()` without a request has no `RYBBIT_SITE_ID` and the guard hides the tag.+- **Content Security Policy**: if you use django-csp, 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 `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/docusaurus.mdx b/docs/content/docs/(docs)/guides/docusaurus.mdxindex 2df229647..91430e5f3 100644--- a/docs/content/docs/(docs)/guides/docusaurus.mdx+++ b/docs/content/docs/(docs)/guides/docusaurus.mdx@@ -1,147 +1,113 @@---title: Docusaurus-description: Integrate Rybbit Analytics with your Docusaurus v2+ website+description: Add Rybbit analytics to your Docusaurus docs+category: docs+icon: SiDocusaurus----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";--This guide explains how to integrate Rybbit with your Docusaurus v2+ website for analytics tracking. Docusaurus is a static site generator that builds a single-page application with React.--## How to Add Rybbit to Your Docusaurus Site--Docusaurus provides a configuration option to add scripts or tags to the `<head>` of every page, which is the recommended way to include Rybbit.+Docusaurus has a `scripts` option in `docusaurus.config.js` that adds a `<script>` tag to the `<head>` of every page, so no theme swizzling is needed.<Steps><Step>-### Retrieve Your Tracking Script Details+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your **Site ID**. The script source will be `https://app.rybbit.io/api/script.js`.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Modify `docusaurus.config.js`--Open your `docusaurus.config.js` (or `docusaurus.config.ts` if using TypeScript) file, which is typically located at the root of your Docusaurus project.+### Add the snippet to Docusaurus-You can add the Rybbit script using the `scripts` array or the `headTags` array within your site configuration. Using `scripts` is often cleaner for simple script additions.--**Using the `scripts` configuration:**+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"-// @ts-check-// Note: type annotations allow type checking and IDEs autocompletion-/** @type {import('@docusaurus/types').Config} */const config = {- // ... other configurations (title, tagline, favicon, url, baseUrl, organizationName, projectName, etc.)+ // ... title, url, baseUrl, presets, themeConfig- presets: [- // ... your presets- ],-- themeConfig:- /** @type {import('@docusaurus/preset-classic').ThemeConfig} */- ({- // ... your themeConfig- }),-- // Add Rybbit script herescripts: [{- src: 'https://app.rybbit.io/api/script.js',+ src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",defer: true,- 'data-site-id': 'YOUR_SITE_ID', // Replace with your actual Site ID},- // You can add other scripts here if needed],-- // Alternatively, using headTags (more verbose for simple scripts):- // headTags: [- // {- // tagName: 'script',- // attributes: {- // defer: true,- // src: 'https://app.rybbit.io/api/script.js',- // 'data-site-id': 'YOUR_SITE_ID', // Replace- // },- // },- // ],};module.exports = config;```-Make sure to replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.++If you already manage tags through `headTags`, this form is equivalent:++```javascript filename="docusaurus.config.js"+headTags: [+ {+ tagName: "script",+ attributes: {+ src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",+ defer: "true",+ },+ },+],+```++Rebuild with `npm run build` and deploy. The tag is not hot-reloaded into a running `npm run start` session until you restart it.++<Callout type="info">+Docusaurus builds a single-page app on React Router. Rybbit detects client-side route changes and records them as pageviews, so no extra code is needed for navigation.+</Callout></Step><Step>-### Verify Installation+### Verify installation-After rebuilding and deploying your Docusaurus site (e.g., `npm run build` and `npm run serve`, or your deployment process), open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded on your pages.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **Page View Tracking**: Docusaurus builds a Single Page Application (SPA). Rybbit's tracking script is designed to automatically detect route changes in SPAs and track them as page views. If you find that page views are not being tracked correctly after client-side navigation (which is uncommon), you might need to manually trigger page views. Docusaurus uses React Router internally. You could potentially use a client module or swizzle a component to tap into navigation events if manual tracking is absolutely necessary, but **test the default behavior first**.- If manual tracking is required, you would call `window.rybbit.pageview()` after a route change.-</Callout>--## Custom Event Tracking+## Track custom events-Since Docusaurus uses React, you can track custom events from any of your custom React components or by using client modules.+Docusaurus pages are React, so you can fire events from a component and use it in MDX:-**Example in a custom React component used in Docusaurus:**-```jsx-// src/components/MyCustomButton.jsx-import React from 'react';+```jsx filename="src/components/TrackedButton.jsx"+import React from "react";-export default function MyCustomButton({ children, eventName, eventData }) {+export default function TrackedButton({ children, eventName, eventData }) {const handleClick = () => {- if (typeof window !== 'undefined' && window.rybbit) {- window.rybbit.event(eventName || 'docusaurus_custom_click', eventData || {});- }+ window.rybbit?.event(eventName, eventData);};return (- <button onClick={handleClick} className="button button--primary margin--sm">+ <button onClick={handleClick} className="button button--primary">{children}</button>);}```-You can then use this component in your MDX files:+```mdx-import MyCustomButton from '@site/src/components/MyCustomButton';+import TrackedButton from "@site/src/components/TrackedButton";-<MyCustomButton eventName="learn_more_clicked" eventData={{ page: 'introduction' }}>- Learn More-</MyCustomButton>+<TrackedButton eventName="learn_more_clicked" eventData={{ page: "introduction" }}>+ Learn more+</TrackedButton>```-**Using Client Modules:**-Docusaurus allows you to run JavaScript on page load using [Client Modules](https://docusaurus.io/docs/advanced/client-modules). You could use this to set up global event listeners or track specific initial interactions.+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:```javascript filename="src/client-modules/rybbit-events.js"-// Example: Track when a user clicks on any external link-export function onRouteUpdate({location, previousLocation}) {- // This function runs after Docusaurus finishes navigating to a new route.- // You could also use onRouteDidUpdate if you need the DOM to be fully updated.-- if (typeof window !== 'undefined' && window.rybbit && location.pathname !== previousLocation?.pathname) {- // Rybbit should auto-track pageviews, but if needed:- // window.rybbit.pageview();- }-- // Example: Add event listeners for specific elements- document.querySelectorAll('a[target="_blank"]').forEach(link => {- link.addEventListener('click', () => {- if (window.rybbit) {- window.rybbit.event('external_link_click', { href: link.href });- }+export function onRouteDidUpdate() {+ document.querySelectorAll('a[target="_blank"]').forEach((link) => {+ link.addEventListener("click", () => {+ window.rybbit?.event("external_link_click", { href: link.href });});});}```-Always ensure `window.rybbit` is available before calling its methods in client-side scripts.\ No newline at end of file+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.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/drupal.mdx b/docs/content/docs/(docs)/guides/drupal.mdxindex 3e53c2f57..40f6611e5 100644--- a/docs/content/docs/(docs)/guides/drupal.mdx+++ b/docs/content/docs/(docs)/guides/drupal.mdx@@ -1,61 +1,70 @@---title: Drupal-description: Integrate Rybbit Analytics with your Drupal site using the rybbit module+description: Add Rybbit analytics to your Drupal site+category: cms+icon: SiDrupal----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-Drupal is a flexible and secure content management system that features robust content modeling and user management tools. You can add Rybbit to Drupal to track anonymous and logged-in users.+The [Rybbit module](https://www.drupal.org/project/rybbit) on Drupal.org adds the tracking script to every page and can pass logged-in user details to Rybbit, so you enter a Site ID instead of editing your theme. It requires Drupal 10.3 or later.-## How to Add Rybbit to Drupal+<Steps>+<Step>+### Get your tracking snippet-You can add Rybbit to your site by installing the [Rybbit](https://drupal.org/project/rybbit) module from Drupal.org+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-<Steps><Step>+### Add the snippet to Drupal-### Get Your Tracking Script+<Tabs items={["Rybbit module", "Theme template"]}>+<Tab>+1. Install and enable the module:-First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Code**. It will look something like this:+ ```bash+ composer require drupal/rybbit+ drush en rybbit+ ```-```html-<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-```+2. Go to **Configuration β Web services β Rybbit analytics** (`/admin/config/services/rybbit`). Your account needs the *administer rybbit* permission.+3. Enter your **Site ID** and save.-Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.-</Step>-<Step>+Optional settings on the same page:-### Download and install the Rybbit module+- **Script URL**: defaults to Rybbit cloud. Point it at your own instance if you self-host Rybbit.+- **Visibility**: restrict tracking by role or by page path, each in include or exclude mode.+- **Identify logged-in users**: calls `identify()` with the user's UUID by default, and sends traits you define as key/value pairs. `username`, `name` and `email` are recognised trait names.+- The module also exposes hooks for altering the sitewide and per-user tracking data from your own module.+</Tab>+<Tab>+If you cannot install contributed modules, copy `core/modules/system/templates/html.html.twig` into your theme's `templates` folder and add the snippet just before `</head>`:-Follow Drupal's [recommended procedure](https://www.drupal.org/docs/extending-drupal/installing-modules) for installing the Rybbit module from https://www.drupal.org/project/rybbit:+```twig+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>```- $ composer require drupal/rybbit- $ drush en rybbit-```-</Step>-<Step>-### Configure module settings+Clear caches afterwards so Drupal picks up the new template.+</Tab>+</Tabs>+</Step>-Visit `admin/services/rybbit` and add your Site ID to the site's configuration page.+<Step>+### Verify installation-You can also modify the script's source and loading optimizations, set rules for when the script gets loaded, and configure the site to use the `identify()` method to pass details about logged-in users from Drupal to Rybbit.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-## Verify Integration--<Steps>-<Step>+## Troubleshooting-### Test Your Integration+- **Script missing after saving settings**: pages are served from Drupal's page cache. Clear caches with `drush cr` or **Configuration β Development β Performance β Clear all caches**.+- **Visitors are tracked but you are not**: check the role and path visibility settings on the module page. Excluding the administrator role is a common setup.+- **Logged-in users appear anonymous**: enable **Identify logged-in users** in the module settings; without it Drupal accounts are tracked like any other visitor.-- Open your live Drupal website in a browser.-- Navigate through a few pages.-- Check your Rybbit dashboard for incoming data. It might take a few minutes for the first events to appear.-</Step>-</Steps>+## Next steps-That's it! Rybbit Analytics should now be integrated with your Drupal site.+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/duda.mdx b/docs/content/docs/(docs)/guides/duda.mdxnew file mode 100644index 000000000..fe62c20a1--- /dev/null+++ b/docs/content/docs/(docs)/guides/duda.mdx@@ -0,0 +1,46 @@+---+title: Duda+description: Add Rybbit analytics to your Duda site+category: builders+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Duda has a site-wide **Header HTML** panel in the site settings with two fields: **Head HTML**, printed inside `<head>` on every page, and **Body End HTML**, printed before `</body>`. The snippet goes into Head HTML, and the site must be republished for it to reach the live site.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Duda++1. In the editor's side panel, click **More**, then **Settings**.+2. Click **Header HTML**.+3. Paste the snippet into **Head HTML** and click **Save**.+4. **Republish** the site. Saved header code shows in the editor and preview, but the live site is only updated on republish.++Head HTML accepts `<script>`, `<link>` and `<meta>` tags; anything else is stripped on save. The tracking snippet is a single `<script>` tag, so it is kept.++To limit tracking to one page instead, open that page's **settings** (gear icon), click **SEO** and paste the snippet into that page's **Header HTML**.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Snippet saved but not in the live page source**: the site was not republished. Republish after every change to Header HTML.+- **Code disappears after saving**: Head HTML strips tags other than `<script>`, `<link>` and `<meta>`. Paste only the script tag, without wrapping HTML or comments.+- **Consent management app in use**: Duda loads Head HTML before consent banners can intercept it. If you need the tracker gated by consent, put the snippet in **Body End HTML** instead, where the consent app can control it.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/ecwid.mdx b/docs/content/docs/(docs)/guides/ecwid.mdxnew file mode 100644index 000000000..8e6f4e750--- /dev/null+++ b/docs/content/docs/(docs)/guides/ecwid.mdx@@ -0,0 +1,98 @@+---+title: Ecwid+description: Add Rybbit analytics to your Ecwid store+category: ecommerce+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++An Ecwid by Lightspeed store runs either on Ecwid's hosted **Instant Site** or embedded in a page on another platform. On Instant Site the snippet goes into the site's header code setting; for an embedded store it goes into the `<head>` of the host site, and the storefront Ecwid renders inside that page is tracked with it.++<Callout type="warn">+Custom code on Instant Site is available on the **Venture**, **Business** and **Unlimited** plans. The free Starter plan has no custom code fields.+</Callout>++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Ecwid++<Tabs items={["Instant Site", "Embedded store"]}>+<Tab>+1. From your Ecwid admin, go to **Website** (or **Overview β Manage Instant Site**).+2. Scroll down to **SEO settings** and click **Add Code** under **Header meta tags and site verification**.+3. Paste the snippet and save.+4. Reload your Instant Site in the browser; there is no separate publish step for this setting.++The **Custom JavaScript code** field under **Advanced website settings** on the same page also works, but it prints code at the end of `<body>`, so prefer the header field.+</Tab>++<Tab>+The store is rendered by Ecwid's embed script inside your own page, so add the snippet to the `<head>` of the host site with that platform's method. See the [integration guides](/docs/guides) for WordPress, Wix, Squarespace, Webflow and others.++One snippet covers the whole store: product pages, cart and checkout all render inside the same host page.+</Tab>+</Tabs>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Ecwid's storefront JavaScript API fires `Ecwid.OnOrderPlaced` with the order right after a customer places it. Add this where the `Ecwid` object already exists: on Instant Site, under **Advanced website settings β Custom JavaScript code**; on an embedded store, after the Ecwid embed script on the host page.++```html+<script>+Ecwid.OnAPILoaded.add(function () {+ Ecwid.OnOrderPlaced.add(function (order) {+ window.rybbit.event('purchase', {+ transaction_id: order.vendorNumber,+ value: order.total,+ tax: order.tax,+ shipping: order.shipping,+ items: order.items.map(function (item) {+ return { item_id: item.sku, item_name: item.name, price: item.price, quantity: item.quantity };+ })+ });+ });+});+</script>+```++`vendorNumber` is the order number customers see in emails; `orderNumber` is Ecwid's internal ID. Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.++Ecwid also has a **Custom tracking code on Order Confirmation page** field under **Settings β General β Tracking & Analytics** (same plans as above). Code there runs on the `/checkout/order-confirmation` page and can use Ecwid's template variables when wrapped in `<#noescape>`:++```html+<script>+<#noescape>+document.addEventListener('DOMContentLoaded', function () {+ window.rybbit.event('purchase', { transaction_id: "${order.number}", value: ${order.total} });+});+</#noescape>+</script>+```++Use one method or the other, not both, or every order is counted twice.++## Troubleshooting++- **No Add Code button under SEO settings**: the store is on the Starter plan. Custom code needs Venture or higher.+- **`Ecwid is not defined`**: the purchase snippet ran before Ecwid's script. Move it below the embed script, or keep it in the Instant Site **Custom JavaScript code** field, which runs at the end of the page.+- **Embedded store, no pageviews**: the snippet belongs to the host site, not to Ecwid. Check the host page's source for `script.js?siteId=`.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/electron.mdx b/docs/content/docs/(docs)/guides/electron.mdxnew file mode 100644index 000000000..2ec13af5b--- /dev/null+++ b/docs/content/docs/(docs)/guides/electron.mdx@@ -0,0 +1,88 @@+---+title: Electron+description: Add Rybbit analytics to your Electron app+category: apps+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.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Electron++<Tabs items={["@rybbit/js SDK", "Script tag"]}>+<Tab>+The SDK is bundled with your renderer code, so nothing is loaded from a CDN at runtime and `script-src 'self'` stays intact.++1. Install the package in your project:++```bash+npm install @rybbit/js+```++2. Initialise it once in the renderer entry file, before any other tracking call:++```js title="src/renderer.js"+import rybbit from "@rybbit/js";++await rybbit.init({+ analyticsHost: "https://app.rybbit.io/api",+ siteId: "YOUR_SITE_ID",+});+```++3. Allow the analytics host in `connect-src`. Electron recommends a CSP for every renderer; when the renderer is loaded from a file, HTTP headers are not available, so use the meta tag:++```html title="src/index.html"+<meta+ http-equiv="Content-Security-Policy"+ content="default-src 'self'; connect-src 'self' https://app.rybbit.io"+/>+```+</Tab>++<Tab>+Paste the snippet into the `<head>` of the renderer HTML and allow the host in both `script-src` (the script itself) and `connect-src` (its requests):++```html title="src/index.html"+<meta+ http-equiv="Content-Security-Policy"+ content="default-src 'self'; script-src 'self' https://app.rybbit.io; connect-src 'self' https://app.rybbit.io"+/>+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+```++If you set the CSP from the main process with `session.defaultSession.webRequest.onHeadersReceived` instead, add the same two sources there.+</Tab>+</Tabs>++Both methods track in-app navigation without extra code: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so history-mode and hash-mode routers are covered.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Requests are blocked on the `file://` origin**: Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only. A renderer opened with `win.loadFile()` runs on the `file://` origin and sends `Origin: null`, so Chromium blocks the `POST` to `/api/track` before it leaves the app. The same applies to custom schemes registered with `protocol.handle()`. Load the renderer over http(s) with `win.loadURL()` (your dev server in development, a hosted or locally served build in production) and tracking works.+- **Console shows a CSP violation**: the message names the directive that blocked the request. Add `https://app.rybbit.io` to that directive; `connect-src` covers the SDK, and the script tag also needs `script-src`.+- **Hostname is empty in the dashboard**: pageviews report the renderer's `window.location.hostname`, which is empty for `file://` pages. Filter by site rather than hostname.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/eleventy.mdx b/docs/content/docs/(docs)/guides/eleventy.mdxnew file mode 100644index 000000000..589bd9368--- /dev/null+++ b/docs/content/docs/(docs)/guides/eleventy.mdx@@ -0,0 +1,80 @@+---+title: Eleventy+description: Add Rybbit analytics to your Eleventy site+category: static+icon: SiEleventy+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Eleventy renders every page through a layout in `_includes/`, so the snippet goes in your base layout's `<head>`. Keep the site ID in a global data file under `_data/` so the layout stays free of hard-coded values.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Eleventy++1. Create `_data/rybbit.json` (create the `_data/` directory if it does not exist). Every template can then read it as `rybbit`. Change `instanceUrl` only if you self-host:++ ```json title="_data/rybbit.json"+ {+ "siteId": "YOUR_SITE_ID",+ "instanceUrl": "https://app.rybbit.io"+ }+ ```++2. Open your base layout and add the tag inside `<head>`. The `eleventy.env.runMode` check keeps the script out of `--serve` and `--watch` runs, so local development is not tracked; the `rybbit.siteId` check keeps it out of builds with no ID configured.++<Tabs items={["Nunjucks", "Liquid"]}>+<Tab value="Nunjucks">+```html title="_includes/base.njk"+<head>+ ...+ {% if eleventy.env.runMode == "build" and rybbit.siteId %}+ <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>+ {% endif %}+</head>+```+</Tab>+<Tab value="Liquid">+```html title="_includes/base.liquid"+<head>+ ...+ {% if eleventy.env.runMode == "build" and rybbit.siteId %}+ <script src="{{ rybbit.instanceUrl }}/api/script.js?siteId={{ rybbit.siteId }}" defer></script>+ {% endif %}+</head>+```+</Tab>+</Tabs>++3. Build and deploy the generated `_site/` directory:++ ```bash+ npx @11ty/eleventy+ ```+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Snippet missing from the page source**: `npx @11ty/eleventy --serve` sets `runMode` to `serve`, so the guard removes the tag. Check the output of a plain build instead.+- **Eleventy 1.x**: `eleventy.env.runMode` was added in Eleventy 2.0. On older versions drop the `runMode` condition and keep only the `rybbit.siteId` check.+- **Custom data directory**: if your config sets `dir.data`, put `rybbit.json` in that directory instead of `_data/`.+- **Several layouts**: a page only gets the tag if its layout chain ends in the layout you edited. Pages with `layout: none` or a different base layout need the tag added there too.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/ember.mdx b/docs/content/docs/(docs)/guides/ember.mdxnew file mode 100644index 000000000..6f4ce3a5a--- /dev/null+++ b/docs/content/docs/(docs)/guides/ember.mdx@@ -0,0 +1,87 @@+---+title: Ember+description: Add Rybbit analytics to your Ember app+category: frameworks+icon: SiEmberdotjs+---++import { Steps, Step } from "fumadocs-ui/components/steps";++An Ember app has one HTML shell that every route renders into. Apps created with the current Vite-based `ember new` blueprint keep it at `index.html` in the project root; classic ember-cli apps keep it at `app/index.html`. Paste the snippet into the `<head>` of that file.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Ember++Open `index.html` (or `app/index.html` in a classic ember-cli app) and paste the snippet inside `<head>`, after the `{{content-for "head"}}` placeholder:++```handlebars title="index.html"+<!DOCTYPE html>+<html lang="en">+ <head>+ <meta charset="utf-8">+ <title>MyApp</title>+ <meta name="description" content="">+ <meta name="viewport" content="width=device-width, initial-scale=1">++ {{content-for "head"}}++ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>++ <link integrity="" rel="stylesheet" href="/@embroider/virtual/vendor.css">+ <link integrity="" rel="stylesheet" href="/@embroider/virtual/app.css">++ {{content-for "head-footer"}}+ </head>+ <body>+ {{content-for "body"}}+ ...+ {{content-for "body-footer"}}+ </body>+</html>+```++Keep the `{{content-for}}` placeholders in place; the build fills them in. Route transitions made by Ember's router (the default `history` location type) are tracked automatically as pageviews.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `window.rybbit.event()` from a component action. Guard the call so a blocked or still-loading script does not throw.++```js title="app/components/signup-button.gjs"+import Component from "@glimmer/component";+import { on } from "@ember/modifier";++export default class SignupButton extends Component {+ trackSignup = () => {+ if (window.rybbit) {+ window.rybbit.event("signup_click", { location: "hero" });+ }+ };++ <template>+ <button type="button" {{on "click" this.trackSignup}}>Sign up</button>+ </template>+}+```++## Troubleshooting++- **`index.html` is also used by the test runner**: `tests/index.html` is a separate file. Do not add the snippet there, or test runs send pageviews to your dashboard.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/fastapi.mdx b/docs/content/docs/(docs)/guides/fastapi.mdxnew file mode 100644index 000000000..f33f8f660--- /dev/null+++ b/docs/content/docs/(docs)/guides/fastapi.mdx@@ -0,0 +1,112 @@+---+title: FastAPI+description: Add Rybbit analytics to your FastAPI app+category: backend+icon: SiFastapi+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++FastAPI serves HTML through `Jinja2Templates`, so the snippet goes into the `<head>` of the base template your pages extend. Keep the site ID in a `pydantic-settings` class and register it as a Jinja global so every template can render the tag without passing it through each route.++<Callout type="info">+The tracking script runs in a browser, so it only applies to routes that return template-rendered HTML. JSON endpoints have nothing for it to track.+</Callout>++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to FastAPI++#### Configure the site ID++Install `pydantic-settings` and `jinja2` if you have not already:++```bash+pip install pydantic-settings jinja2+```++Define the settings, reading from the environment and an optional `.env` file:++```python filename="config.py"+from pydantic_settings import BaseSettings, SettingsConfigDict+++class Settings(BaseSettings):+ model_config = SettingsConfigDict(env_file=".env")++ rybbit_instance_url: str = "https://app.rybbit.io"+ rybbit_site_id: str = ""+++settings = Settings()+```++```bash filename=".env"+RYBBIT_INSTANCE_URL=https://app.rybbit.io+RYBBIT_SITE_ID=YOUR_SITE_ID+```++#### Register the values with Jinja++`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"+from fastapi import FastAPI, Request+from fastapi.responses import HTMLResponse+from fastapi.templating import Jinja2Templates++from config import settings++app = FastAPI()+templates = Jinja2Templates(directory="templates")+templates.env.globals["rybbit_instance_url"] = settings.rybbit_instance_url+templates.env.globals["rybbit_site_id"] = settings.rybbit_site_id++[email protected]("/", response_class=HTMLResponse)+async def index(request: Request):+ return templates.TemplateResponse(request=request, name="index.html")+```++#### Add the tag to your base template++Open the template your pages extend, usually `templates/base.html`, and add the tag inside `<head>`:++```jinja filename="templates/base.html"+<head>+ <meta charset="utf-8">+ <title>{% block title %}My App{% endblock %}</title>++ {% if rybbit_site_id %}+ <script src="{{ rybbit_instance_url }}/api/script.js?siteId={{ rybbit_site_id }}" defer></script>+ {% endif %}+</head>+```++The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is empty, so local development is not tracked unless you set the variable. Templates that do not extend the base need the same tag in their own `<head>`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Tag missing**: `Settings()` reads the environment when the module is imported, so restart Uvicorn (or your process manager) after changing `RYBBIT_SITE_ID`.+- **Several `Jinja2Templates` instances**: globals are per environment. If routers create their own `Jinja2Templates`, set the globals on each, or share one instance from a module.+- **Content Security Policy**: if middleware sets one, 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 `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the template appends the script path to it.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/flask.mdx b/docs/content/docs/(docs)/guides/flask.mdxnew file mode 100644index 000000000..0d71dc33c--- /dev/null+++ b/docs/content/docs/(docs)/guides/flask.mdx@@ -0,0 +1,86 @@+---+title: Flask+description: Add Rybbit analytics to your Flask app+category: backend+icon: SiFlask+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Flask renders Jinja templates, and most apps extend a shared base layout, so the snippet goes into that layout's `<head>`. Flask exposes `app.config` to every template as `config`, so store the site ID there and reference it from the template.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Flask++#### 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):++```bash filename=".env"+FLASK_RYBBIT_INSTANCE_URL=https://app.rybbit.io+FLASK_RYBBIT_SITE_ID=YOUR_SITE_ID+```++Then load them where you create the app:++```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()++[email protected]("/")+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.++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()`.++#### Add the tag to your base layout++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"+<head>+ <meta charset="utf-8">+ <title>{% block title %}My App{% endblock %}</title>++ {% if config.RYBBIT_SITE_ID %}+ <script src="{{ config.RYBBIT_INSTANCE_URL }}/api/script.js?siteId={{ config.RYBBIT_SITE_ID }}" defer></script>+ {% endif %}+</head>+```++`config` is part of Flask's standard template context, so no context processor is needed. The `{% if %}` guard skips the tag when `RYBBIT_SITE_ID` is unset, so local development is not tracked unless you set the variable.++Templates that do not extend the base layout need the same tag in their own `<head>`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## 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`.+- **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.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/flutter-web.mdx b/docs/content/docs/(docs)/guides/flutter-web.mdxnew file mode 100644index 000000000..354186c28--- /dev/null+++ b/docs/content/docs/(docs)/guides/flutter-web.mdx@@ -0,0 +1,80 @@+---+title: Flutter web+description: Add Rybbit analytics to your Flutter web app+category: apps+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.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Flutter web++1. Open `web/index.html` in your Flutter project.+2. Paste the snippet inside `<head>`, above the `flutter_bootstrap.js` script that Flutter generates:++```html title="web/index.html"+<head>+ <meta charset="UTF-8" />+ <title>My App</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+```++3. Rebuild with `flutter build web` and deploy the `build/web` folder.++Navigation is tracked automatically with either URL strategy. Flutter's default hash strategy writes routes as `/#/settings`, and the tracker listens for `hashchange` and records `#/settings` as the path `/settings`. With `usePathUrlStrategy()` the Navigator uses the History API, and the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Flutter widgets are not HTML elements, so `data-rybbit-event` attributes have nothing to attach to. Call `window.rybbit.event()` from Dart through `dart:js_interop` instead:++```dart title="lib/analytics.dart"+import 'dart:js_interop';++@JS('rybbit.event')+external void _rybbitEvent(String name, [JSAny? properties]);++void trackEvent(String name, [Map<String, Object?>? properties]) {+ _rybbitEvent(name, properties?.jsify());+}+```++```dart+ElevatedButton(+ onPressed: () {+ trackEvent('signup_click', {'plan': 'pro'});+ },+ child: const Text('Sign up'),+)+```++Guard the call with `kIsWeb` if the same code also compiles for mobile or desktop targets.++## Troubleshooting++- **Clicks, outbound links and session replay show nothing**: the CanvasKit and Skwasm renderers paint into a single `<canvas>`, so DOM-based features (`data-rybbit-event` attributes, outbound-link tracking, button-click autocapture, session replay) have no elements to observe. Use the Dart interop above for events.+- **Deep links 404 after switching to `usePathUrlStrategy()`**: path URLs need the web server to rewrite every route to `index.html`; the Flutter dev server does this for you, production hosting must be configured.+- **`rybbit` is undefined in Dart**: the snippet is `defer`red, so it is not ready during `main()`. Send events from user interactions, not from app start-up.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/framer.mdx b/docs/content/docs/(docs)/guides/framer.mdxindex 4ab0404a7..bf4ff8eb4 100644--- a/docs/content/docs/(docs)/guides/framer.mdx+++ b/docs/content/docs/(docs)/guides/framer.mdx@@ -1,103 +1,67 @@---title: Framer-description: Integrate Rybbit Analytics with your Framer site for behavior tracking and custom events+description: Add Rybbit analytics to your Framer site+category: builders+icon: SiFramer----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";--Rybbit enables you to gather analytics on user behavior, capture custom events, record sessions, and more within your Framer site.--## How to Add Rybbit to Framer+Framer has a **Custom Code** section in the site settings that injects HTML into the `<head>` of every published page.<Steps><Step>-### Retrieve Your Tracking Script+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your code snippet.--```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Add the Snippet to Your Framer Project+### Add the snippet to Framer-- Open your Framer project.-- Go to **Site Settings > General** and scroll down to **Custom Code**.-- Paste your snippet into the `<head>` tag section (start or end).-- Publish your changes.+1. Open your Framer project and go to **Site Settings β General**.+2. Scroll to **Custom Code**.+3. Paste the snippet into the **Start of `<head>` tag** field (End of `<head>` works too).+4. Click **Save**, then **Publish**. Custom code only reaches the live site on publish.</Step>-</Steps>-<Callout type="info">- **Page View Tracking in Framer**: Framer sites often behave like Single Page Applications (SPAs). Rybbit's tracking script is designed to automatically detect URL changes and track them as page views. If you use Framer's navigation features (like links between pages or components that change the URL), Rybbit should capture these. If you notice page views are not tracked correctly after navigation, you might need to manually trigger `window.rybbit.pageview()` using a Framer code override or code component when a "virtual" page change occurs. Test the default behavior first.-</Callout>+<Step>+### Verify installation-## Custom Event Tracking in Framer+<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>-You can track custom events in Framer using **Code Overrides** or by creating **Code Components**. This allows you to trigger Rybbit tracking calls in response to user interactions.+## Track custom events-**Example using a Code Override on a button:**+Use a **Code Override** to send events from any element in the canvas.-1. Select the button or interactive element in Framer.-2. In the properties panel on the right, find "Overrides" and click "+ File" to create a new override file (e.g., `MyButtonOverrides.tsx`) or select an existing one.-3. Add the following code to the override file:+1. Select the element, open **Overrides** in the properties panel, and click **+ File** to create an override file such as `RybbitOverrides.tsx`.+2. Add an override that wraps the element's click handler:```tsx-// MyButtonOverrides.tsx-import type { ComponentType } from "react"--export function withRybbitTracking(Component: ComponentType): ComponentType {- return (props) => {- const handleClick = () => {- if (typeof window !== "undefined" && window.rybbit) {- window.rybbit.event('framer_button_click', {- buttonName: props.text || 'Unnamed Button',- page: props.currentPage?.name || 'Unknown Page'- });- }- // Call original onClick if it exists- props.onClick?.();- };-- return <Component {...props} onClick={handleClick} />- }+// RybbitOverrides.tsx+import type { ComponentType } from "react";++export function withRybbitClick(Component: ComponentType): ComponentType {+ return (props) => {+ const handleClick = () => {+ window.rybbit?.event("cta_click", { label: props.text ?? "cta" });+ props.onClick?.();+ };+ return <Component {...props} onClick={handleClick} />;+ };}```-4. Apply this override to your button component in Framer:- * Select the button.- * In the Overrides section, choose the file (`MyButtonOverrides`).- * Choose the `withRybbitTracking` override for the `onClick` (or relevant interaction) property.+3. Back in the properties panel, pick the file and apply `withRybbitClick` to the element.-**Example within a Code Component:**+The same `window.rybbit.event()` call works inside a **Code Component**.-```tsx-// MyInteractiveComponent.tsx-import React from "react"--export function MyInteractiveComponent(props) {- const handleInteraction = () => {- if (typeof window !== "undefined" && window.rybbit) {- window.rybbit.event('framer_component_interaction', {- componentName: 'MyInteractiveComponent',- detail: 'User interacted'- });- }- }-- return (- <div onClick={handleInteraction} style={{ padding: 20, background: "lightblue", cursor: "pointer" }}>- Click me to track event- </div>- )-}-```-Remember to always check for `window.rybbit` before calling its methods. Publish your Framer site to see the tracking in action.\ No newline at end of file+## Troubleshooting++- **Navigation between pages is not tracked**: Framer sites navigate client-side and the script detects those URL changes. If a view changes without the URL changing, call `window.rybbit.pageview()` from an override when it appears.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/fumadocs.mdx b/docs/content/docs/(docs)/guides/fumadocs.mdxnew file mode 100644index 000000000..4f5f31431--- /dev/null+++ b/docs/content/docs/(docs)/guides/fumadocs.mdx@@ -0,0 +1,57 @@+---+title: Fumadocs+description: Add Rybbit analytics to your Fumadocs docs+category: docs+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Fumadocs is a documentation framework for Next.js, so the snippet goes in the root layout, `app/layout.tsx`, rendered with `next/script` so it is on every page including the docs routes.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Fumadocs++Open `app/layout.tsx` and render the `Script` component inside `<body>`, next to the `RootProvider` that Fumadocs already puts there:++```tsx title="app/layout.tsx"+import { RootProvider } from "fumadocs-ui/provider/next";+import Script from "next/script";+import type { ReactNode } from "react";++export default function Layout({ children }: { children: ReactNode }) {+ return (+ <html lang="en" suppressHydrationWarning>+ <body className="flex flex-col min-h-screen">+ <RootProvider>{children}</RootProvider>+ <Script+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"+ strategy="afterInteractive"+ />+ </body>+ </html>+ );+}+```++Use the root layout, not `app/docs/layout.tsx`: the docs layout only wraps pages under `/docs`, so a landing page outside it would be missed.++Client-side navigation between docs pages is recorded as pageviews automatically. The [Next.js guide](/docs/guides/react/next-js) covers the `Script` component, custom events from client components and proxying through your own domain.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/ghost.mdx b/docs/content/docs/(docs)/guides/ghost.mdxindex cd5c115cf..173d591ae 100644--- a/docs/content/docs/(docs)/guides/ghost.mdx+++ b/docs/content/docs/(docs)/guides/ghost.mdx@@ -1,59 +1,44 @@---title: Ghost-description: Integrate Rybbit Analytics with your Ghost blog or publication+description: Add Rybbit analytics to your Ghost publication+category: cms+icon: SiGhost----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";-Ghost is a powerful publishing platform for blogs and publications. You can easily add Rybbit Analytics using Ghost's built-in code injection feature.--## How to Add Rybbit to Ghost+Ghost has a built-in **Code injection** setting that adds HTML to the `<head>` of every page, so no theme edits are needed.<Steps><Step>-### Access Code Injection Settings+### Get your tracking snippet-1. Log in to your Ghost Admin panel-2. Go to **Settings** (gear icon in the bottom left)-3. Scroll down and click on **Code injection**+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Add the Tracking Script--In the **Site Header** section, paste the following code:+### Add the snippet to Ghost-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```+1. Open **Ghost Admin** and click the **Settings** gear in the bottom left.+2. Under **Advanced**, open **Code injection**.+3. Paste the snippet into **Site header** and click **Save**.-Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.+If you maintain your own theme instead, add the snippet to `default.hbs` just before `</head>`.</Step><Step>-### Save Changes+### Verify installation-Click **Save** in the top right corner. The script will now be loaded on all pages of your Ghost site.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>## Troubleshooting-### Script not appearing--1. Make sure you clicked **Save** after adding the code-2. Clear your browser cache and refresh the page-3. Check "View Page Source" and search for `rybbit` to verify the script is present--### Using a Ghost theme with custom code--If your theme has its own code injection or you're modifying theme files directly, you can add the script to your theme's `default.hbs` file, just before the closing `</head>` tag.+- **Ghost(Pro) with a custom theme**: code injection still applies on top of the theme, so prefer it over editing `default.hbs`.+- **Member-only content**: pages behind the paywall are tracked like any other page for visitors who can view them.+- **Portal and newsletter previews** render in an iframe and are not tracked.-### Membership/Subscriber tracking+## Next steps-Ghost's membership features work normally with Rybbit. All page views, including member-only content, will be tracked (for visitors who have access to view the content).+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/gitbook.mdx b/docs/content/docs/(docs)/guides/gitbook.mdxindex f2d6457b2..af3170432 100644--- a/docs/content/docs/(docs)/guides/gitbook.mdx+++ b/docs/content/docs/(docs)/guides/gitbook.mdx@@ -1,40 +1,45 @@---title: GitBook-description: Options for using Rybbit Analytics with GitBook documentation+description: Add Rybbit analytics to your GitBook docs+category: docs+icon: SiGitbook----import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";-GitBook is a popular platform for creating documentation and knowledge bases.+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.-<Callout type="warn">-GitBook no longer supports adding arbitrary custom scripts (JS/HTML) to published sites. The old **Custom scripts β Head** setting this guide previously described has been removed, so the standard Rybbit `<script>` snippet cannot be pasted into a GitBook-hosted site. Analytics on GitBook now works through its built-in integrations, and Rybbit does not currently have a prebuilt GitBook integration.-</Callout>+<Steps>+<Step>+### Get your tracking snippet-## Current options+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-### Build a custom GitBook integration+<Step>+### Add the snippet to GitBook-GitBook's [developer platform](https://gitbook.com/docs/integrations) lets you build and install your own integration, and integrations can inject scripts into published content β this is how GitBook's own analytics integrations (Google Analytics, Fathom, etc.) work. A minimal custom integration that injects the Rybbit snippet:+<Callout type="warn">+There is currently no supported way to load the Rybbit snippet on a GitBook-hosted site. The old **Custom scripts β Head** setting was removed, and GitBook's [integration scopes](https://gitbook.com/docs/developers/integrations/configurations) reserve `site:script:inject` for GitBook's own integrations: "Building integrations that inject JavaScript into a site or space is not possible at this time."+</Callout>-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```+Your options:-Refer to GitBook's integration documentation for the current manifest format and publishing flow, and note that script injection only applies to published spaces (typically on a custom domain).+- **Use GitBook's built-in analytics.** The **Insights** section in the GitBook app reports page views and search terms for published sites without any script.+- **Wait for a native integration.** A Rybbit integration would need GitBook to build or approve it. Ask GitBook support for it, and watch the [Rybbit roadmap](/docs/roadmap).+- **Host the docs elsewhere.** [Docusaurus](/docs/guides/docusaurus), [Mintlify](/docs/guides/mintlify), [VitePress](/docs/guides/vitepress), [Starlight](/docs/guides/starlight) and [Fumadocs](/docs/guides/fumadocs) all take the snippet directly, and GitBook can export a space as Markdown to migrate.-### Host your docs on a platform with custom-code support+The rest of your site (marketing pages, app, blog) is unaffected: add the snippet there as usual so traffic from the docs is still attributed by referrer.+</Step>-If building an integration isn't worth it for your use case, platforms like [Docusaurus](/docs/guides/docusaurus), [VitePress](/docs/guides/vitepress), [Mintlify](/docs/guides/mintlify), or [Hugo](/docs/guides/hugo) support adding the Rybbit script directly β see their guides.+<Step>+### Verify installation-## Verifying installation+<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>-If you do get the script injected via an integration:+## Next steps-1. Visit your published documentation through its public URL-2. Open the browser Network tab and confirm `script.js` loads and `POST` requests go to `/api/track`-3. Check your Rybbit dashboard for incoming pageviews+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/google-tag-manager.mdx b/docs/content/docs/(docs)/guides/google-tag-manager.mdxindex d871e7454..c6a12e5fa 100644--- a/docs/content/docs/(docs)/guides/google-tag-manager.mdx+++ b/docs/content/docs/(docs)/guides/google-tag-manager.mdx@@ -1,171 +1,97 @@---title: Google Tag Manager-description: Integrate Rybbit Analytics with your website using Google Tag Manager+description: Add Rybbit analytics to your Google Tag Manager container+category: tag-managers+icon: SiGoogletagmanager----import { Steps, Step } from 'fumadocs-ui/components/steps';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";--Google Tag Manager (GTM) allows you to add code snippets or tracking pixels to your website with minimal code changes. This makes it an efficient way to integrate Rybbit without modifying your codebase.--## How to Add Rybbit to Google Tag Manager+Google Tag Manager loads Rybbit through a **Custom HTML** tag fired on **All Pages**, so nothing in your site's code changes. Events you already push to the `dataLayer` can be forwarded to Rybbit with a second tag.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet.--Normally, the script would look like:--```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```--However, GTM sanitizes script tags by removing non-standard HTML attributes like `data-site-id`. So you need to use:--```javascript-<script>- (function() {- var el = document.createElement("script");- el.src = "https://app.rybbit.io/api/script.js";- el.defer = true;- el.setAttribute("data-site-id", "YOUR_SITE_ID");- document.head.appendChild(el);- })();-</script>-```-</Step>--<Step>-### Access Your GTM Dashboard+### Get your tracking snippet-Assuming GTM is already set up, go to your GTM dashboard and select the appropriate account and container linked to your website.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Create a New Tag+### Add the snippet to Google Tag Manager-Click on **Add a new tag** to initiate the creation process.-</Step>+1. Open your GTM container and go to **Tags β New**.+2. Under **Tag Configuration**, choose **Custom HTML** and paste the snippet:-<Step>-### Configure the Tag+```html+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+```-Under **Tag Configuration**, choose **Custom HTML** and paste your Rybbit snippet into the provided field.-</Step>+3. Under **Triggering**, choose **All Pages** (the built-in Page View trigger).+4. Name the tag, for example `Rybbit - Loader`, and click **Save**.+5. Click **Submit** and publish the container version.-<Step>-### Set Up Triggers+<Callout type="warn">+GTM rebuilds Custom HTML tags before injecting them and can drop non-standard attributes. Keep the site ID in the URL (`?siteId=`) as shown; the older `data-*` attribute form is not reliable here.+</Callout>-Assign a trigger to determine when the tag should fire. For instance, to load Rybbit on all pages, select the **All Pages** trigger.+Use **Preview** mode to confirm the tag fires on page load before publishing.</Step><Step>-### Save and Publish+### Verify installation-Save your changes and publish the container to make the tag active on your website.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-## Custom Event Tracking+## Track custom events-Once Rybbit is loaded through GTM, you can track custom events using JavaScript. Since GTM already handles the script loading, you can directly call the Rybbit tracking functions.+Once the loader tag is published, `window.rybbit` is available to your own JavaScript and to other GTM tags.-### Method 1: Direct JavaScript in GTM+#### Forward dataLayer events-You can create additional Custom HTML tags in GTM to track specific events:+If your site already pushes events like `dataLayer.push({ event: "signup" })`, one tag can forward them to Rybbit:++1. Create a **Custom Event** trigger. Set the event name to a regex such as `signup|purchase|add_to_cart` (tick **Use regex matching**).+2. Create a **Custom HTML** tag with that trigger:```html<script>- // Track a custom event when this tag fires- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('gtm_custom_event', {- event_category: 'engagement',- event_label: 'button_click',- value: 1+ if (window.rybbit) {+ window.rybbit.event("{{Event}}", {+ page: "{{Page Path}}",+ referrer: "{{Referrer}}"});}</script>```-### Method 2: Track Events from Your Website Code--Once Rybbit is loaded via GTM, you can track events directly from your website's JavaScript:--```javascript-// Example: Track button clicks-document.addEventListener('DOMContentLoaded', function() {- const ctaButton = document.getElementById('cta-button');- if (ctaButton) {- ctaButton.addEventListener('click', function() {- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('cta_clicked', {- button_text: ctaButton.textContent,- page_path: window.location.pathname,- timestamp: new Date().toISOString()- });- }- });- }-});-```+`{{Event}}`, `{{Page Path}}` and `{{Referrer}}` are GTM built-in variables. Add a **Data Layer Variable** for any custom field you push (for example `plan`) and reference it the same way.-### Method 3: Using GTM Variables and Triggers+#### Use GTM's click and form triggers-You can leverage GTM's built-in variables and triggers to send custom events to Rybbit:--1. Create a new **Custom HTML** tag-2. Use GTM variables in your tracking code:+The same pattern works with built-in **Click** and **Form Submission** triggers:```html<script>- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('{{Event}}', {- page: '{{Page URL}}',- referrer: '{{Referrer}}',- click_text: '{{Click Text}}',- click_url: '{{Click URL}}'+ if (window.rybbit) {+ window.rybbit.event("cta_clicked", {+ text: "{{Click Text}}",+ url: "{{Click URL}}"});}</script>```-3. Set up triggers for specific interactions (e.g., form submissions, scroll depth, video plays)--### Common Event Examples--```javascript-// Form submission-window.rybbit.event('form_submitted', {- form_id: 'contact-form',- form_name: 'Contact Us'-});--// E-commerce tracking-window.rybbit.event('add_to_cart', {- product_id: '12345',- product_name: 'Example Product',- price: 29.99,- quantity: 1-});--// Video engagement-window.rybbit.event('video_played', {- video_title: 'Product Demo',- duration: 120,- percent_watched: 75-});--// Download tracking-window.rybbit.event('file_downloaded', {- file_name: 'whitepaper.pdf',- file_type: 'pdf',- file_size: '2.5MB'-});-```+Enable the **Click Text** and **Click URL** built-in variables under **Variables β Configure**.++## Troubleshooting++- **Event tag fires before Rybbit loads**: the loader script is deferred, so an event tag on the same page load may run first and hit the `if (window.rybbit)` guard. Open the event tag's **Advanced Settings β Tag Sequencing** and set the loader tag to fire before it, or trigger the event tag on **Window Loaded** instead of **Page View**.+- **Consent mode**: if your container gates tags on consent, add the loader tag to the same consent group as your other analytics tags, otherwise it never fires.+- **Tag shows in Preview but not live**: the container version was not published. Click **Submit** and publish.++## Next steps+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/hexo.mdx b/docs/content/docs/(docs)/guides/hexo.mdxnew file mode 100644index 000000000..2c2161505--- /dev/null+++ b/docs/content/docs/(docs)/guides/hexo.mdx@@ -0,0 +1,85 @@+---+title: Hexo+description: Add Rybbit analytics to your Hexo site+category: static+icon: SiHexo+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Hexo 5 and later ship an injector API that adds HTML to the `<head>` of every generated page from a small file in your site's `scripts/` directory, so no theme edits are needed. Editing the theme's head partial is the fallback for older versions.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Hexo++<Tabs items={["Injector script", "Theme layout"]}>+<Tab value="Injector script">+1. Add your site ID to the site `_config.yml` at the root of your project (not the theme config). `instance_url` is only needed if you self-host:++ ```yaml title="_config.yml"+ rybbit:+ site_id: "YOUR_SITE_ID"+ instance_url: "https://app.rybbit.io"+ ```++2. Create `scripts/rybbit.js` (create the `scripts/` directory if it does not exist). Hexo loads every file in this directory at startup with the `hexo` object in scope:++ ```javascript title="scripts/rybbit.js"+ const { site_id: siteId, instance_url: instanceUrl = "https://app.rybbit.io" } =+ hexo.config.rybbit || {};++ if (siteId) {+ hexo.extend.injector.register(+ "head_end",+ `<script src="${instanceUrl}/api/script.js?siteId=${siteId}" defer></script>`+ );+ }+ ```++ `head_end` places the tag right before `</head>`. With no third argument the injector applies to every page type.+</Tab>+<Tab value="Theme layout">+Open your theme's head partial and paste the snippet before `</head>`. For the default Landscape theme that file is `themes/landscape/layout/_partial/head.ejs`; other themes keep an equivalent partial under `layout/`.++```html title="themes/landscape/layout/_partial/head.ejs"+ ...+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+```++Theme updates overwrite this file, so prefer the injector when your Hexo version supports it.+</Tab>+</Tabs>++Regenerate and deploy the `public/` directory:++```bash+hexo clean && hexo generate+```+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **`hexo.extend.injector` is undefined**: the injector API arrived in Hexo 5.0. Check `hexo version` and upgrade, or use the theme layout method.+- **Tag missing after adding the script**: run `hexo clean` before `hexo generate`; Hexo caches rendered output in `db.json` and can serve stale pages.+- **Local previews are tracked**: `hexo server` runs the same injector as `hexo generate`. Leave `site_id` empty in a local copy of `_config.yml`, or accept the local pageviews.+- **Theme config vs site config**: `hexo.config` reads the root `_config.yml`, not `themes/<name>/_config.yml`. Put the `rybbit` block in the root file.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/hostinger.mdx b/docs/content/docs/(docs)/guides/hostinger.mdxnew file mode 100644index 000000000..03566ddf9--- /dev/null+++ b/docs/content/docs/(docs)/guides/hostinger.mdx@@ -0,0 +1,50 @@+---+title: Hostinger Website Builder+description: Add Rybbit analytics to your Hostinger Website Builder site+category: builders+icon: SiHostinger+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Hostinger Website Builder has a **Custom code** integration in the website settings that adds code to every page. Script tags are placed at the end of `<body>` by default; a `data-render-head` attribute moves them into `<head>`.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Hostinger Website Builder++1. Open your site in the builder and click **β―** (More) at the top to open the website settings, then choose **Integrations**.+2. Select **Custom code**.+3. Paste the snippet with `data-render-head` added so it loads from `<head>`:++```html+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer data-render-head></script>+```++4. Save the changes, then click **Update website** to publish. Custom code runs on the live site and in preview, not inside the editor.++Without `data-render-head` the builder moves `<script>` tags to the end of `<body>`. The tracker still works there; the attribute only makes it load earlier.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **No requests to `script.js` in the editor**: expected. Integrations are injected into the published site only, so check the live URL or the preview.+- **Snippet saved but not in the page source**: the site was not updated after saving. Click **Update website**.+- **Site breaks after adding several snippets**: paste snippets one after another, never nested inside each other. If the page still fails, remove all custom code, update, and add the snippets back one at a time.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/htmx.mdx b/docs/content/docs/(docs)/guides/htmx.mdxnew file mode 100644index 000000000..7058ed857--- /dev/null+++ b/docs/content/docs/(docs)/guides/htmx.mdx@@ -0,0 +1,71 @@+---+title: htmx+description: Add Rybbit analytics to your htmx app+category: frameworks+icon: SiHtmx+---++import { Steps, Step } from "fumadocs-ui/components/steps";++htmx pages are plain server-rendered HTML, so the snippet goes in the `<head>` of your base layout next to the htmx script tag, in whichever template your server uses for the full-page response.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to htmx++Open the template that renders the full HTML document (the one that already loads htmx) and paste the snippet inside `<head>`:++```html title="layout.html"+<!DOCTYPE html>+<html lang="en">+ <head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <title>My htmx App</title>+ <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/htmx.min.js"></script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ </head>+ <body>+ <main id="content" hx-boost="true">...</main>+ </body>+</html>+```++Only full-page responses need the tag. Partial responses that htmx swaps into the page must not include it, or the script is re-evaluated on every swap.++Navigations that htmx records in browser history are tracked automatically as pageviews: `hx-push-url` and `hx-boost` call `history.pushState()`, `hx-replace-url` calls `history.replaceState()`, and the back and forward buttons fire `popstate`. All three are hooked by the tracker. A swap without `hx-push-url` leaves the URL unchanged and is not counted as a pageview; send a [custom event](/docs/track-events) for those interactions instead.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Use the `data-rybbit-event` attribute on the element that triggers the request. The tracker listens for clicks on `document`, so it also works on content that htmx swapped in after the page loaded:++```html+<button+ hx-post="/subscribe"+ hx-target="#form"+ data-rybbit-event="newsletter_subscribe"+ data-rybbit-prop-plan="free"+>+ Subscribe+</button>+```++To record an event when the server has actually processed the request, listen for htmx's `htmx:afterRequest` event and call `window.rybbit.event()` from there.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/hubspot.mdx b/docs/content/docs/(docs)/guides/hubspot.mdxnew file mode 100644index 000000000..814beb3bf--- /dev/null+++ b/docs/content/docs/(docs)/guides/hubspot.mdx@@ -0,0 +1,81 @@+---+title: HubSpot+description: Add Rybbit analytics to your HubSpot site+category: cms+icon: SiHubspot+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++HubSpot Content Hub (formerly CMS Hub) has a **Site header HTML** setting that injects code into the `<head>` of every website page, landing page, blog post and knowledge base article on a domain, so no template edits are needed. Individual pages can add or override code from the content editor.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to HubSpot++<Tabs items={["Site header HTML", "Single page"]}>+<Tab>+This adds the snippet to all HubSpot-hosted content on a domain.++1. In your HubSpot account, click the **settings** icon in the top navigation bar.+2. In the left sidebar, go to **Content > Pages**.+3. Use the **Choose a domain to edit its settings** dropdown to pick the domain, or stay on the default settings to apply the code to every domain.+4. Paste the snippet into the **Site header HTML** field.+5. Click **Save**.++If a domain has **Override default settings** turned on, the default header code no longer applies to it. Add the snippet to that domain's own settings as well.+</Tab>++<Tab>+Use this to track a single page, or when someone else controls the domain settings.++1. Open **Content > Website Pages** (or **Landing Pages**, **Blog**, **Knowledge Base**) and click the page name to open the editor.+2. Click the **Settings** menu, then select **Advanced**.+3. Under **Additional code snippets**, paste the snippet into the **Head HTML** field.+4. Click **Update** or **Publish**.++Per-page head HTML is added on top of the site header HTML, so a page tracked by both methods loads the script twice. Pick one.+</Tab>+</Tabs>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++HubSpot forms submit inside the page without a full reload, so track them with a custom event. Add `data-rybbit-event` to a call-to-action button, or listen for HubSpot's form-submitted message in a small script placed after the snippet:++```html+<script>+ window.addEventListener("message", function (event) {+ if (event.data.type === "hsFormCallback" && event.data.eventName === "onFormSubmitted") {+ window.rybbit.event("form_submitted", { formId: event.data.id });+ }+ });+</script>+```++See [Track custom events](/docs/track-events) for the event API.++## Troubleshooting++- **Snippet missing on one domain**: the site header HTML is per domain. Check whether that domain has **Override default settings** enabled and add the snippet there.+- **Duplicate pageviews**: the same page has the snippet in both site header HTML and its own **Head HTML**. Remove one.+- **Editor and preview**: the content editor renders pages in an iframe with unpublished changes. Previews are tracked like any other visit if they load the script, so avoid checking analytics from the editor.+- **Quotes**: header HTML set at the domain level also loads on HubSpot quotes hosted on that domain.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/hugo.mdx b/docs/content/docs/(docs)/guides/hugo.mdxindex ec1118a64..d9aa32db0 100644--- a/docs/content/docs/(docs)/guides/hugo.mdx+++ b/docs/content/docs/(docs)/guides/hugo.mdx@@ -1,125 +1,66 @@---title: Hugo-description: Integrate Rybbit Analytics with your Hugo static site using partial templates+description: Add Rybbit analytics to your Hugo site+category: static+icon: SiHugo----import { Steps, Step } from 'fumadocs-ui/components/steps';+import { Steps, Step } from "fumadocs-ui/components/steps";-Integrating Rybbit Analytics with your Hugo static site involves adding the tracking script to your site's templates. The best way to do this is by creating a partial template for the script and including it in your site's footer.+Hugo builds every page from templates under `layouts/`, so the cleanest place for the snippet is a partial template that your base template includes on every page.<Steps><Step>-### Get Your Tracking Script+### Get your tracking snippet-First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Code**. It will look something like this:--```html-<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.-</Step>--<Step>-### Create a Partial Template--In your Hugo project, navigate to the `layouts/partials/` directory. If it doesn't exist, create it.--Inside `layouts/partials/`, create a new file named `rybbit-analytics.html` (or a similar name).--Paste your Rybbit tracking script into this new file:--```html-{{/* layouts/partials/rybbit-analytics.html */}}-{{ if not hugo.IsServer }} {{/* Only include in production builds */}}- <script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-{{ end }}-```--**Explanation:**-- `{{ if not hugo.IsServer }}`: This Hugo condition ensures that the tracking script is only included when you build your site for production (`hugo`) and not during local development (`hugo server`). This prevents tracking your own local page views.-- Replace `https://app.rybbit.io` and `YOUR_SITE_ID` with your actual details.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Include the Partial in Your Footer--Now, you need to include this partial in your site's main footer template. This is typically located in `layouts/_default/baseof.html` or a theme-specific footer partial (e.g., `layouts/partials/footer.html` or `themes/your-theme/layouts/partials/footer.html`).--Open your main base template or footer partial file. Just before the closing `</body>` tag, add the following line to include your Rybbit Analytics partial:+### Add the snippet to Hugo-```html-{{/* ... other footer content ... */}}+1. Add your site ID under `params` in your Hugo config (`hugo.toml`, or `config.toml` in older Hugo versions). `rybbitInstanceURL` is only needed if you self-host:-{{ partial "rybbit-analytics.html" . }}+ ```toml title="hugo.toml"+ [params]+ rybbitSiteID = "YOUR_SITE_ID"+ rybbitInstanceURL = "https://app.rybbit.io"+ ```-</body>-</html>-```+2. Create `layouts/partials/rybbit-analytics.html` (create the `layouts/partials/` directory if it does not exist):-If you named your partial differently, make sure to use that name (e.g., `{{ partial "my-analytics-script.html" . }}`).-</Step>-</Steps>+ ```html title="layouts/partials/rybbit-analytics.html"+ {{ if and (not hugo.IsServer) .Site.Params.rybbitSiteID }}+ <script src="{{ .Site.Params.rybbitInstanceURL | default "https://app.rybbit.io" }}/api/script.js?siteId={{ .Site.Params.rybbitSiteID }}" defer></script>+ {{ end }}+ ```-## Configure `config.toml` (Optional but Recommended)+ `not hugo.IsServer` skips the script during `hugo server`, so local development is not tracked. The `rybbitSiteID` check keeps the tag out of builds that have no ID configured.-To make your Site ID configurable, you can use Hugo's site parameters.--<Steps>-<Step>-### Update `rybbit-analytics.html`+3. Include the partial from your base template, typically `layouts/_default/baseof.html`, inside `<head>`. If your theme owns `baseof.html`, copy it into your project's `layouts/_default/` first so the theme can be updated without losing the change; a theme footer partial such as `layouts/partials/footer.html` also works.-Modify `layouts/partials/rybbit-analytics.html` to use a site parameter:+ ```html title="layouts/_default/baseof.html"+ <head>+ ...+ {{ partial "rybbit-analytics.html" . }}+ </head>+ ```-```html-{{/* layouts/partials/rybbit-analytics.html */}}-{{ if and (not hugo.IsServer) .Site.Params.rybbitSiteID }}- <script defer src="{{ .Site.Params.rybbitInstanceURL | default "https://app.rybbit.io" }}/api/script.js" data-site-id="{{ .Site.Params.rybbitSiteID }}"></script>-{{ end }}-```+4. Build with `hugo` and deploy the generated `public/` directory.</Step><Step>-### Add parameters to `config.toml`--Open your Hugo configuration file (e.g., `config.toml`) and add:+### Verify installation-```toml-[params]- rybbitInstanceURL = "https://app.rybbit.io" # Your Rybbit instance URL- rybbitSiteID = "YOUR_SITE_ID" # Your Rybbit Site ID-```--This approach keeps your specific IDs out of the templates and makes it easier to manage for different environments if needed.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-## Build and Deploy--<Steps>-<Step>-### Build your Hugo site--Rebuild your Hugo site:--```bash-hugo-```-</Step>--<Step>-### Deploy--Deploy the generated `public/` directory to your web server.-</Step>+## Troubleshooting-<Step>-### Verify Integration+- **Snippet missing from the page source**: `hugo server` never emits it because of the `hugo.IsServer` guard. Check the output of a production `hugo` build instead.+- **Theme overrides**: a file at `layouts/_default/baseof.html` in your project takes precedence over the theme's copy, so make sure you edited the one Hugo actually renders.-- Open your live Hugo website in a browser.-- Navigate through a few pages.-- Check your Rybbit dashboard for incoming data. It might take a few minutes for the first events to appear.-</Step>-</Steps>+## Next steps-That's it! Rybbit Analytics is now integrated with your Hugo site and will only track visits on your production deployment.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/index.mdx b/docs/content/docs/(docs)/guides/index.mdxnew file mode 100644index 000000000..21aa85855--- /dev/null+++ b/docs/content/docs/(docs)/guides/index.mdx@@ -0,0 +1,10 @@+---+title: Integration guides+description: Step-by-step instructions for adding Rybbit to every major website platform, framework and CMS+---++Rybbit works on any site that can load a script tag. Each guide below shows exactly where the tracking snippet goes on that platform and how to confirm it is working.++Don't see your platform? Paste the snippet from **Site Settings β Tracking Script** into the `<head>` of every page, or follow the [tracking script](/docs/script) reference.++<GuideIndex />diff --git a/docs/content/docs/(docs)/guides/instapage.mdx b/docs/content/docs/(docs)/guides/instapage.mdxnew file mode 100644index 000000000..b112ca37e--- /dev/null+++ b/docs/content/docs/(docs)/guides/instapage.mdx@@ -0,0 +1,61 @@+---+title: Instapage+description: Add Rybbit analytics to your Instapage landing pages+category: landing+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Instapage takes custom scripts at two levels: **Workspace scripts** (under **Assets > Scripts**) apply to every page in a workspace, and each page also has its own **JavaScript** and **HTML/CSS** settings with a **Head** section. Custom HTML, CSS and JavaScript are included on all Instapage plans; Workspace scripts are limited to some subscriptions and show an upgrade prompt otherwise.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Instapage++<Tabs items={["Workspace scripts", "Single page"]}>+<Tab>+1. In the left menu, open **Assets**, then **Scripts**.+2. Paste the snippet into the **Head** section.+3. Above the editor, choose how it applies: option **A** adds it to every past and future page in the workspace; **B** leaves it off until you switch it on per page under **Scripts & Privacy**; **B + C** turns it on for all pages but lets you disable it per page.+4. Click **Apply**.++Workspace scripts load on the live URL before any page-level script, so the snippet is in place before other code on the page runs.+</Tab>++<Tab>+1. Open the page in the builder and click **Settings** in the right sidebar.+2. Open the **HTML/CSS** tab and paste the snippet into **Head**. (The **JavaScript** tab has the same three sections and wraps your code in `<script>` tags automatically; the snippet already has its own tag, so HTML/CSS is the simpler choice.)+3. **Publish** the page. Custom code runs only on the live, published page, not in the editor or preview.+</Tab>+</Tabs>++<Callout type="info">+If you use Instapage's privacy compliance banner, put the snippet in the page's **Scripts & Privacy** section instead so it fires only after the visitor accepts.+</Callout>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Snippet not in the page source**: the page was saved but not republished. Custom code only reaches the live URL on publish.+- **Assets > Scripts shows an upgrade prompt**: Workspace scripts are not on your subscription. Add the snippet per page instead.+- **Duplicate pageviews**: the snippet is both a workspace script and a page-level script. Keep one copy.+- **Old version still served**: clear your browser cache after publishing; Instapage notes cached copies can outlive an update.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/jekyll.mdx b/docs/content/docs/(docs)/guides/jekyll.mdxindex b87939cbd..327ceac38 100644--- a/docs/content/docs/(docs)/guides/jekyll.mdx+++ b/docs/content/docs/(docs)/guides/jekyll.mdx@@ -1,146 +1,88 @@---title: Jekyll-description: Integrate Rybbit Analytics with your Jekyll static site using layout files or includes+description: Add Rybbit analytics to your Jekyll site+category: static+icon: SiJekyll----import { Steps, Step } from 'fumadocs-ui/components/steps';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-Integrating Rybbit Analytics with your Jekyll static site involves adding the tracking script to your site's main layout file or by creating an include file.+Jekyll renders every page through a layout, usually `_layouts/default.html`. Put the snippet in an include file that the layout pulls in, or paste it into the layout directly.<Steps><Step>-### Get Your Tracking Script+### Get your tracking snippet-First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Code**. It will look something like this:--```html-<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.+<include>../../../partials/guides/get-snippet.mdx</include></Step>-</Steps>-## Option A: Add to Default Layout--The simplest way is to add the script directly to your default layout file.--<Steps><Step>-### Locate your main layout file--In your Jekyll project, find your main layout file. This is often `_layouts/default.html`.-</Step>--<Step>-### Add the tracking script--Open this file and paste the Rybbit tracking script just before the closing `</body>` tag.--```html-{{ site.title }}-{{ content }}-<!-- Other footer content -->--<!-- Rybbit Analytics Script -->-{% raw %}-{% if jekyll.environment == "production" %}- <script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-{% endif %}-{% endraw %}--</body>-</html>+### Add the snippet to Jekyll++<Tabs items={["Include file", "Layout file"]}>+<Tab value="Include file">+1. Add your site ID to `_config.yml`. `rybbit_instance_url` is only needed if you self-host:++ ```yaml title="_config.yml"+ rybbit_site_id: "YOUR_SITE_ID"+ rybbit_instance_url: "https://app.rybbit.io"+ ```++2. Create `_includes/rybbit-analytics.html` (create the `_includes/` directory if it does not exist):++ ```html title="_includes/rybbit-analytics.html"+ {% if jekyll.environment == "production" and site.rybbit_site_id %}+ <script src="{{ site.rybbit_instance_url | default: 'https://app.rybbit.io' }}/api/script.js?siteId={{ site.rybbit_site_id }}" defer></script>+ {% endif %}+ ```++ The `jekyll.environment` check keeps the script out of local `jekyll serve` builds; the `site.rybbit_site_id` check keeps it out of builds with no ID configured.++3. Include it from your layout's `<head>`:++ ```html title="_layouts/default.html"+ <head>+ ...+ {% include rybbit-analytics.html %}+ </head>+ ```+</Tab>+<Tab value="Layout file">+Open `_layouts/default.html` and paste the snippet inside `<head>`, wrapped in a production check so local `jekyll serve` builds are not tracked:++```html title="_layouts/default.html"+<head>+ ...+ {% if jekyll.environment == "production" %}+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ {% endif %}+</head>```+</Tab>+</Tabs>-**Explanation:**-- `{% raw %}{% if jekyll.environment == "production" %}{% endraw %}`: This Liquid tag condition ensures the script is only included when your site is built for production (e.g., when `JEKYLL_ENV=production jekyll build`). This prevents tracking your local development views.-- Replace `YOUR_SITE_ID` with your actual Site ID. The script source `https://app.rybbit.io/api/script.js` is for the standard cloud-hosted Rybbit instance.-</Step>-</Steps>--## Option B: Create an Include File (Recommended)--A cleaner approach is to create an include file for the script.--<Steps>-<Step>-### Create the Include File--- In your Jekyll project, navigate to the `_includes/` directory. If it doesn't exist, create it.-- Create a new file named `rybbit-analytics.html` (or similar) inside `_includes/`.-- Paste the following into `_includes/rybbit-analytics.html`:--```html-{% raw %}-{% comment %} _includes/rybbit-analytics.html {% endcomment %}-{% if jekyll.environment == "production" and site.rybbit_site_id %}- <script defer src="{{ site.rybbit_instance_url | default: 'https://app.rybbit.io' }}/api/script.js" data-site-id="{{ site.rybbit_site_id }}"></script>-{% endif %}-{% endraw %}-```-</Step>--<Step>-### Include in Layout--- Open your main layout file (e.g., `_layouts/default.html`).-- Just before the closing `</body>` tag, add:--```html-{{ site.title }}-{{ content }}-<!-- Other footer content -->--{% raw %}{% include rybbit-analytics.html %}{% endraw %}--</body>-</html>-```-</Step>--<Step>-### Configure `_config.yml`--- Open your `_config.yml` file and add your Rybbit details:--```yaml-# Rybbit Analytics Configuration-rybbit_instance_url: "https://app.rybbit.io" # Optional, defaults in include-rybbit_site_id: "YOUR_SITE_ID"-```-This method keeps your credentials in the configuration file and makes the script inclusion conditional on `rybbit_site_id` being set.-</Step>-</Steps>--## Build and Deploy--<Steps>-<Step>-### Build your Jekyll site--Build your Jekyll site. For production, set the `JEKYLL_ENV` environment variable:+Build for production and deploy the generated `_site/` directory:```bashJEKYLL_ENV=production jekyll build```-Or, if you use GitHub Pages, it typically sets `jekyll.environment` to `production` automatically during its build process.+GitHub Pages sets `jekyll.environment` to `production` during its own build, so no extra configuration is needed there.</Step><Step>-### Deploy+### Verify installation-Deploy the generated `_site/` directory to your web server.+<include>../../../partials/guides/verify.mdx</include></Step>+</Steps>-<Step>-### Verify Integration+## Troubleshooting-- Open your live Jekyll website in a browser.-- Navigate through a few pages.-- Check your Rybbit dashboard for incoming data. It might take a few minutes for the first events to appear.-</Step>-</Steps>+- **Snippet missing from the page source**: `jekyll serve` and a plain `jekyll build` run with `jekyll.environment` set to `development`, so the production guard removes the tag. Build with `JEKYLL_ENV=production` and check that output.+- **Config changes not applied**: Jekyll reads `_config.yml` once at startup, so restart `jekyll serve` after adding `rybbit_site_id`.++## Next steps-That's it! Rybbit Analytics is now integrated with your Jekyll site and will only track visits on your production deployment.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/joomla.mdx b/docs/content/docs/(docs)/guides/joomla.mdxindex 5a42e4bdb..3b5cff100 100644--- a/docs/content/docs/(docs)/guides/joomla.mdx+++ b/docs/content/docs/(docs)/guides/joomla.mdx@@ -1,139 +1,78 @@---title: Joomla-description: Integrate Rybbit Analytics with your Joomla website+description: Add Rybbit analytics to your Joomla site+category: cms+icon: SiJoomla----import { Tabs, Tab } from 'fumadocs-ui/components/tabs';-import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-Joomla is a popular open-source content management system. Here's how to add Rybbit Analytics to your Joomla site.--## How to Add Rybbit to Joomla--<Tabs items={['Custom HTML Module', 'Template Override']}>-<Tab>-### Using a Custom HTML Module--This is the easiest method and doesn't require editing any files.+Joomla has no built-in head-code setting, so the snippet goes in either a **Custom** module assigned to every page or in your template's `index.php`.<Steps><Step>-### Create a New Module+### Get your tracking snippet-1. Log in to your Joomla Administrator panel-2. Go to **Extensions** > **Modules**-3. Click **New** and select **Custom**+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Configure the Module--Set the following options:+### Add the snippet to Joomla-- **Title**: Rybbit Analytics (or any name you prefer)-- **Show Title**: No-- **Position**: Select a position that appears in the `<head>` section, often called `head`, `debug`, or similar depending on your template--In the **Editor** tab, switch to **Code** view (or disable the editor) and paste:--```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.defer = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();-</script>-```--Replace `YOUR_SITE_ID` with your actual Site ID.-</Step>--<Step>-### Publish the Module--1. Set **Status** to **Published**-2. Under **Menu Assignment**, select **On all pages**-3. Click **Save & Close**-</Step>-</Steps>--<Callout type="info">-If your template doesn't have a head position, you can use any position - the JavaScript will still add the script to the document head.-</Callout>+<Tabs items={["Custom module", "Template file"]}>+<Tab>+No file edits are needed, and the module survives template updates.++1. In the Administrator panel go to **Content β Site Modules** (**Extensions β Modules** on Joomla 3), click **New** and choose **Custom**.+2. Set **Title** to `Rybbit`, **Show Title** to **Hide**, and **Position** to any position your template renders on every page. Templates rarely expose a `<head>` position; the loader below moves the script into the head from wherever the module is rendered.+3. In the editor, use the **Toggle Editor** button (or **Code** view) so the script is not stripped, then paste:++ ```html+ <script>+ (function () {+ var s = document.createElement("script");+ s.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";+ s.defer = true;+ document.head.appendChild(s);+ })();+ </script>+ ```++4. Set **Status** to **Published**, choose **On all pages** under **Menu Assignment**, and click **Save & Close**.</Tab>-<Tab>-### Editing Template Files--For more control, you can add the script directly to your template.-<Callout type="warn">-Create a child template or template override to avoid losing changes when the template updates.+Edit a child template (Joomla 4.1+) or your own copy of the template, otherwise the change is lost on the next template update.</Callout>-<Steps>-<Step>-### Access Template Files+1. Go to **System β Site Templates** and open your active template.+2. Open `index.php` and add the snippet just before `</head>`:-1. Go to **System** > **Site Templates**-2. Click on your active template-3. Click on the **index.php** file (or create an override)-</Step>+ ```php+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ </head>+ ```-<Step>-### Add the Script--Find the closing `</head>` tag and add the script just before it:--```php-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.defer = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();-</script>-</head>-```--Replace `YOUR_SITE_ID` with your actual Site ID.+3. Click **Save & Close**.+</Tab>+</Tabs></Step><Step>-### Save the File+### Verify installation-Click **Save** or **Save & Close** to apply the changes.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-</Tab>-</Tabs>## Troubleshooting-### Script not appearing on the site--1. Check that the module is published and assigned to all pages-2. Clear Joomla's cache: **System** > **Clear Cache**-3. Verify the module position exists in your template--### Editor stripping the script--Joomla's default editor (TinyMCE) may strip script tags. To fix this:--1. Go to **Extensions** > **Plugins**-2. Find and open **Editor - TinyMCE**-3. Under **Extended Valid Elements**, add: `script[src|defer|data-site-id]`-4. Or simply use the **Code** view when editing the module--### Caching issues+- **Module not on the page**: confirm it is published, assigned to **On all pages**, and that the chosen position exists in your template. Then clear the cache under **System β Clear Cache**.+- **TinyMCE strips the script**: open the **Editor - TinyMCE** plugin under **System β Plugins** (**Extensions β Plugins** on Joomla 3) and add `script[src|defer]` to **Extended Valid Elements**, or keep using the toggled-off editor when saving the module.+- **Page caching**: the **System - Page Cache** plugin serves cached HTML, so clear the cache after adding the snippet. The script itself loads client-side and works with cached pages.-If you're using a caching plugin or extension:+## Next steps-1. Clear all caches after adding the script-2. The script should work with page caching since it loads client-side+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/kajabi.mdx b/docs/content/docs/(docs)/guides/kajabi.mdxnew file mode 100644index 000000000..0e8733716--- /dev/null+++ b/docs/content/docs/(docs)/guides/kajabi.mdx@@ -0,0 +1,56 @@+---+title: Kajabi+description: Add Rybbit analytics to your Kajabi site+category: creators+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Kajabi has a site-wide **Header Page Scripts** field under **Site details** that puts code in the `<head>` of every page, but it deliberately skips Offer checkout and upsell pages. Those have their own **Checkout Tracking Code** setting, so a full install is two pastes.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Kajabi++**Site-wide pages**++1. From the **Dashboard**, open **Settings**.+2. Under **Site settings**, click **Site details**.+3. Scroll to **Page scripts** and paste the snippet into **Header Page Scripts**.+4. Save.++**Checkout and upsell pages**++1. From the **Dashboard**, open **Settings**.+2. Under **Payment settings**, click **Checkout**.+3. In the **Checkout Tracking Code** section, click to edit the **Header tracking code** and paste the same snippet.+4. Save.++<Callout type="info">+Do not paste the snippet into a page's **Custom Code** section (under **Customize > Settings**). That field is for CSS and JavaScript without `<style>` or `<script>` tags, and it only applies to that one page.+</Callout>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Checkout pages missing from the dashboard**: Header Page Scripts do not run on Offer checkout or upsell pages. Add the snippet under **Settings > Checkout > Checkout Tracking Code** as well.+- **Both fields filled, one visitor, two sites?** Use the same site ID in both places so a visitor who browses your site and then buys is one session, and funnels can follow them through checkout.+- **Snippet added to a page's Custom Code block instead**: the **Add block > Custom Code** block does accept `<script>` tags, but it only covers that page. Keep the site-wide field as the source of truth.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/kirby.mdx b/docs/content/docs/(docs)/guides/kirby.mdxnew file mode 100644index 000000000..f9bdb6ac3--- /dev/null+++ b/docs/content/docs/(docs)/guides/kirby.mdx@@ -0,0 +1,83 @@+---+title: Kirby+description: Add Rybbit analytics to your Kirby site+category: cms+icon: SiKirby+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Kirby templates are plain PHP files in `site/templates/`, and shared markup lives in `site/snippets/`. The snippet goes into whichever file owns your `<head>`: the Starterkit's `site/snippets/header.php`, or the template itself in a Plainkit project.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Kirby++<Tabs items={["Starterkit", "Plainkit"]}>+<Tab>+The Starterkit renders the document head from a shared snippet that every template includes with `<?php snippet('header') ?>`.++1. Open `site/snippets/header.php`.+2. Add the tag before `</head>`:++```php title="site/snippets/header.php"+<head>+ <meta charset="utf-8">+ <meta name="viewport" content="width=device-width, initial-scale=1.0">+ <title><?= $site->title() ?> | <?= $page->title() ?></title>+ <?= css(['assets/css/index.css', '@auto']) ?>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+```++3. Save. Every template that calls `snippet('header')` now loads the script.+</Tab>++<Tab>+The Plainkit's `site/templates/default.php` contains only `<h1><?= $page->title() ?></h1>` and no document structure, so add the tag wherever you build your `<head>`. The usual pattern is a header snippet included by each template:++```php title="site/snippets/header.php"+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="utf-8">+ <title><?= $page->title() ?></title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+<body>+```++```php title="site/templates/default.php"+<?php snippet('header') ?>+<h1><?= $page->title() ?></h1>+<?php snippet('footer') ?>+```+</Tab>+</Tabs>++To keep the site ID out of the snippet, add it to `site/config/config.php` and read it with `<?= option('rybbit.siteId') ?>`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Page cache**: if `cache.pages.active` is enabled in `site/config/config.php`, flush `site/cache/` after editing the snippet or cached pages keep the old head.+- **Multiple header snippets**: templates that include a different header (for example `snippet('header-landing')`) need the tag added there too.+- **Panel is not tracked**: `/panel` is a separate app that does not render your templates, so editing time never appears in Rybbit.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/laravel.mdx b/docs/content/docs/(docs)/guides/laravel.mdxindex 876594f93..458abcff1 100644--- a/docs/content/docs/(docs)/guides/laravel.mdx+++ b/docs/content/docs/(docs)/guides/laravel.mdx@@ -1,121 +1,85 @@---title: Laravel-description: Integrate Rybbit Analytics with your Laravel application using Blade templates+description: Add Rybbit analytics to your Laravel app+category: backend+icon: SiLaravel----import { Steps, Step } from 'fumadocs-ui/components/steps';+import { Steps, Step } from "fumadocs-ui/components/steps";-Integrating Rybbit Analytics with your Laravel application is straightforward. You'll typically add the Rybbit tracking script to your main Blade layout file.+Laravel renders pages through Blade layouts, so the snippet goes into the layout file that wraps your site. Read the site ID from `config/services.php` and `.env` so it stays out of the template and differs per environment.<Steps><Step>-### Get Your Tracking Script+### Get your tracking snippet-First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Script**. It will look something like this:--```html-<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.-</Step>--<Step>-### Locate Your Main Blade Layout File--In a standard Laravel application, you'll have a main layout file that other Blade views extend. This file is often located at:--- `resources/views/layouts/app.blade.php` (common for applications using Laravel's authentication scaffolding)-- Or `resources/views/layouts/main.blade.php` or a similar custom name.-- If you're using Laravel Jetstream or Breeze, the main layout file might be in a slightly different location within `resources/views/`.--Identify the primary layout file that wraps most or all of your site's pages.-</Step>--<Step>-### Add the Tracking Script to the Layout--Open your main Blade layout file. Paste the Rybbit tracking script just before the closing `</body>` tag.--```php-<!DOCTYPE html>-<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">-<head>- <meta charset="utf-8">- <meta name="viewport" content="width=device-width, initial-scale=1">- <title>{{ config('app.name', 'Laravel') }}</title>- {{-- Stylesheets, etc. --}}- @vite(['resources/css/app.css', 'resources/js/app.js']) {{-- Example for Vite --}}-</head>-<body class="font-sans antialiased">- {{-- Your page content, often using @yield or <slot> --}}- @yield('content')-- {{-- Other scripts --}}-- {{-- Rybbit Analytics Script --}}- @if(app()->environment('production'))- <script defer src="{{ config('services.rybbit.instance_url', 'https://app.rybbit.io') }}/api/script.js" data-site-id="{{ config('services.rybbit.site_id') }}"></script>- @endif-</body>-</html>-```--**Explanation:**-- `@if(app()->environment('production'))`: This Blade directive ensures the script is only included when your Laravel application is running in the `production` environment. This prevents tracking during local development.-- `{{ config('services.rybbit.instance_url', 'https://app.rybbit.io') }}/api/script.js` and `{{ config('services.rybbit.site_id') }}`: This is a recommended way to manage your Rybbit credentials using Laravel's configuration system. The `config('services.rybbit.instance_url')` should resolve to your Rybbit instance's base URL (e.g., `https://app.rybbit.io` or your self-hosted URL), and `/api/script.js` is appended to it. The fallback shown ensures it defaults to the cloud-hosted Rybbit script. See step 4 for `.env` configuration.--If you prefer not to use the config helper immediately, you can hardcode the values:-```php- {{-- Rybbit Analytics Script --}}- @if(app()->environment('production'))- <script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>- @endif-```-Remember to replace placeholders with your actual script URL and Site ID.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Configure Environment Variables (Recommended)+### Add the snippet to Laravel-It's best practice to store your Rybbit Site ID and instance URL in your `.env` file and access them via Laravel's configuration.+#### Configure the site ID-**a. Add to `.env` file:**-Open your `.env` file and add:+Add the Rybbit values to `.env`:-```bash+```bash filename=".env"RYBBIT_INSTANCE_URL=https://app.rybbit.ioRYBBIT_SITE_ID=YOUR_SITE_ID```-**b. Add to `config/services.php`:**-Open (or create if it doesn't exist) `config/services.php` and add a configuration for Rybbit:+Then register them in `config/services.php`:-```php+```php filename="config/services.php"<?phpreturn [// ... other services'rybbit' => [- 'instance_url' => env('RYBBIT_INSTANCE_URL'),+ 'instance_url' => env('RYBBIT_INSTANCE_URL', 'https://app.rybbit.io'),'site_id' => env('RYBBIT_SITE_ID'),],];```-Now, the Blade template code from Step 3 using `config('services.rybbit.instance_url')` and `config('services.rybbit.site_id')` will work correctly.-Make sure to run `php artisan config:clear` if you've cached your configuration.+Run `php artisan config:clear` if your configuration is cached, otherwise the new keys are not picked up.++#### Add the tag to your layout++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"+<head>+ <meta charset="utf-8">+ <meta name="viewport" content="width=device-width, initial-scale=1">+ <title>{{ config('app.name', 'Laravel') }}</title>+ @vite(['resources/css/app.css', 'resources/js/app.js'])++ @production+ <script src="{{ config('services.rybbit.instance_url') }}/api/script.js?siteId={{ config('services.rybbit.site_id') }}" defer></script>+ @endproduction+</head>+```++`@production` only renders the tag when `APP_ENV=production`, so local development is not tracked. Drop the directive if you also want data from staging.++If you have several layouts (for example `app` and `guest`), add the tag to each one, or move it into a partial such as `resources/views/partials/rybbit.blade.php` and `@include` it from every layout.</Step><Step>-### Verify Integration+### Verify installation-- Deploy your Laravel application to your production environment (or set `APP_ENV=production` locally for testing, but be mindful of tracking local data).-- Open your live Laravel website in a browser.-- Navigate through a few pages.-- Check your Rybbit dashboard for incoming data. It might take a few minutes for the first events to appear.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-That's it! Rybbit Analytics is now integrated with your Laravel application and will only track visits in your production environment.\ No newline at end of file+## Troubleshooting++- **Tag missing in production**: run `php artisan config:clear` and `php artisan view:clear` after changing `.env` or `config/services.php`; cached config and compiled views keep the old values.+- **Tag missing locally**: `@production` hides it unless `APP_ENV=production`. Set that temporarily to test, or remove the directive.+- **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++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/leadpages.mdx b/docs/content/docs/(docs)/guides/leadpages.mdxnew file mode 100644index 000000000..5968a7f05--- /dev/null+++ b/docs/content/docs/(docs)/guides/leadpages.mdx@@ -0,0 +1,46 @@+---+title: Leadpages+description: Add Rybbit analytics to your Leadpages landing pages+category: landing+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Every Leadpages page, site and pop-up has an **Analytics** tab in its builder settings with a **Head Section Tracking Code** field, and that is where the snippet goes. In the site builder the setting is site-wide, so one paste covers every page of the site; landing pages built on their own are tracked one page at a time.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Leadpages++1. Open the site or landing page in the builder.+2. Click the **Settings** gear in the left-hand sidebar, then the **Analytics** tab.+3. Paste the snippet into **Head Section Tracking Code**.+4. Click **Save**, then **Update** to push the change to the published page.++Repeat for each standalone landing page you want tracked. For sites, the code applies to every page in the site.++Pop-ups have the same tracking code fields in their settings, but a pop-up shown on a page that already carries the snippet does not need its own copy.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Snippet not in the page source**: the page was saved but not updated. Click **Update** in the builder to republish.+- **Standalone pages missing**: tracking code on a site does not extend to landing pages published outside that site. Add the snippet to each one.+- **GA4 Measurement ID field**: the Analytics tab also has a field for a Google Analytics ID. That field is for GA4 only; the Rybbit snippet belongs in Head Section Tracking Code.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/lovable.mdx b/docs/content/docs/(docs)/guides/lovable.mdxnew file mode 100644index 000000000..460c7ef2f--- /dev/null+++ b/docs/content/docs/(docs)/guides/lovable.mdx@@ -0,0 +1,82 @@+---+title: Lovable+description: Add Rybbit analytics to your Lovable app+category: ai-builders+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Lovable has no project setting for custom head code, so the snippet goes into the app's HTML head like any other code change: ask Lovable to add it in chat, or open the **Code** tab and edit the file yourself. Either way, the live app only picks it up after you publish the change.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Lovable++<Tabs items={["Ask Lovable", "Edit the code"]}>+<Tab>+Paste this into the chat, with your snippet in place of the placeholder:++```text+Add this script tag to the <head> of the app on every page. Do not remove any existing head tags.+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+```++Check the diff Lovable shows: the tag belongs in the document head, not in a React component.+</Tab>++<Tab>+Open the **Code** tab in the project toolbar (editing needs a paid plan; on the Free plan the editor is read-only). Which file holds the head depends on when the project was created:++- **Projects created from May 13, 2026** use TanStack Start. Add the script to the `head()` of the root route in `src/routes/__root.tsx`; the `<HeadContent />` component already in that file renders it into the `<head>`:++```tsx title="src/routes/__root.tsx"+export const Route = createRootRoute({+ head: () => ({+ scripts: [+ { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: true },+ ],+ }),+ component: RootComponent,+});+```++- **Older React + Vite projects** have a single `index.html` at the project root. Paste the snippet before `</head>`:++```html title="index.html"+<head>+ <meta charset="UTF-8" />+ <title>My app</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+```++Save with **Cmd+S** / **Ctrl+S**.+</Tab>+</Tabs>++Then click **Publish** in the top right and choose **Publish changes**. Client-side route changes inside the app are tracked as pageviews automatically.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Live app still has no script**: Lovable does not push edits to the published app automatically. A dot on the **Publish** button means unpublished changes; open it and click **Publish changes**.+- **Free plan**: the Code tab is read-only, so use the chat prompt instead.+- **Script disappeared after a later prompt**: Lovable can rewrite the head when it regenerates the layout or upgrades the template. Add "keep the Rybbit script tag" to the project's Knowledge so future edits preserve it, and re-check the page source after big changes.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/magento.mdx b/docs/content/docs/(docs)/guides/magento.mdxnew file mode 100644index 000000000..66860f053--- /dev/null+++ b/docs/content/docs/(docs)/guides/magento.mdx@@ -0,0 +1,129 @@+---+title: Magento+description: Add Rybbit analytics to your Magento store+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.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Magento++1. In the Admin sidebar, go to **Content > Design > Configuration**.+2. Find the row for the scope you want to track (usually the store view) and click **Edit** in the **Action** column.+3. Expand **HTML Head**.+4. Paste the snippet at the end of **Scripts and Style Sheets** and click **Save Configuration**.+5. Go to **System > Cache Management** and refresh the invalidated cache types, then purge Varnish or your CDN if you use one.++#### Allow the tracker under CSP (2.4.7 and later)++Magento 2.4.7 switched the checkout page (`checkout_index_index`) to CSP restrict mode; other storefront pages stay in report-only mode. Scripts from hosts that are not whitelisted are blocked on checkout, so add the tracker's host to `script-src` and `connect-src` with a `csp_whitelist.xml` in a module of your own (plus the usual `registration.php` and `etc/module.xml`):++```xml title="app/code/Vendor/Rybbit/etc/csp_whitelist.xml"+<?xml version="1.0"?>+<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"+ xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">+ <policies>+ <policy id="script-src">+ <values>+ <value id="rybbit" type="host">https://app.rybbit.io</value>+ </values>+ </policy>+ <policy id="connect-src">+ <values>+ <value id="rybbit" type="host">https://app.rybbit.io</value>+ </values>+ </policy>+ </policies>+</csp_whitelist>+```++Run `bin/magento setup:upgrade` and flush the cache after adding the module. If you self-host Rybbit, whitelist your own instance's domain instead.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++The order success page renders `Magento_Checkout::success.phtml` through the `checkout.success` block, which reserves an `order.success.additional.info` container for extra content. Add a block to that container from the same module as the CSP whitelist; the block reads the order from the checkout session.++```php title="app/code/Vendor/Rybbit/Block/Purchase.php"+<?php+namespace Vendor\Rybbit\Block;++class Purchase extends \Magento\Checkout\Block\Onepage\Success+{+ public function getOrder(): \Magento\Sales\Model\Order+ {+ return $this->_checkoutSession->getLastRealOrder();+ }+}+```++```xml title="app/code/Vendor/Rybbit/view/frontend/layout/checkout_onepage_success.xml"+<?xml version="1.0"?>+<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">+ <body>+ <referenceContainer name="order.success.additional.info">+ <block class="Vendor\Rybbit\Block\Purchase" name="rybbit.purchase" template="Vendor_Rybbit::purchase.phtml" cacheable="false"/>+ </referenceContainer>+ </body>+</page>+```++```php title="app/code/Vendor/Rybbit/view/frontend/templates/purchase.phtml"+<?php+/** @var \Vendor\Rybbit\Block\Purchase $block */+$order = $block->getOrder();+if (!$order->getId()) {+ return;+}+$items = [];+foreach ($order->getAllVisibleItems() as $item) {+ $items[] = [+ 'item_id' => $item->getSku(),+ 'item_name' => $item->getName(),+ 'price' => (float) $item->getPrice(),+ 'quantity' => (int) $item->getQtyOrdered(),+ ];+}+$purchase = [+ 'transaction_id' => $order->getIncrementId(),+ 'value' => (float) $order->getGrandTotal(),+ 'currency' => $order->getOrderCurrencyCode(),+ 'items' => $items,+];+?>+<script>+document.addEventListener('DOMContentLoaded', function () {+ window.rybbit.event('purchase', <?= /* @noEscape */ json_encode($purchase) ?>);+});+</script>+```++The script waits for `DOMContentLoaded` because the tracker loads with `defer`. Event properties are limited to 2048 characters of JSON, so drop `items` for stores with large orders. `getTaxAmount()` and `getShippingAmount()` are available on the same order object if you want those too.++## Troubleshooting++- **Snippet not in the page source**: design configuration is scoped, and a store-view row overrides the website and global rows. Edit the row that applies to the storefront you are checking, then flush the page cache and Varnish.+- **Tracked everywhere except checkout**: CSP restrict mode on `checkout_index_index` is blocking the script. Confirm the whitelist module is enabled and look for `Content-Security-Policy` errors naming `app.rybbit.io` in the browser console.+- **Purchase event missing**: `getLastRealOrder()` is only set in the session that placed the order, so reopening the success page later renders nothing.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/meta.json b/docs/content/docs/(docs)/guides/meta.jsonindex ea1085349..c99ac0426 100644--- a/docs/content/docs/(docs)/guides/meta.json+++ b/docs/content/docs/(docs)/guides/meta.json@@ -1,36 +1,105 @@{"title": "Integration Guides","pages": [+ "index",+ "---JavaScript frameworks---","angular","astro",- "bigcommerce",- "bubble",- "carrd",- "contentful",- "docusaurus",- "drupal",- "framer",- "ghost",- "gitbook",- "google-tag-manager",+ "ember",+ "htmx",+ "preact",+ "qwik",+ "react",+ "solid",+ "svelte",+ "vue",+ "---Static site generators---",+ "eleventy",+ "hexo","hugo","jekyll",- "joomla",+ "zola",+ "---Backend frameworks---",+ "aspnet",+ "blazor",+ "django",+ "fastapi",+ "flask","laravel",+ "phoenix",+ "rails",+ "---Documentation tools---",+ "docusaurus",+ "fumadocs",+ "gitbook","mintlify",- "prestashop",- "react",+ "mkdocs",+ "nextra",+ "starlight",+ "vitepress",+ "---Content management systems---",+ "contentful",+ "craft-cms",+ "drupal",+ "ghost",+ "hubspot",+ "joomla",+ "kirby",+ "payload","sanity",- "shopify",- "squarespace",+ "statamic",+ "storyblok","strapi",- "svelte",- "thrivecart",- "vitepress",- "vue",+ "typo3",+ "umbraco",+ "wordpress",+ "---Website builders---",+ "bubble",+ "carrd",+ "duda",+ "framer",+ "hostinger",+ "squarespace","webflow",+ "weebly","wix",+ "---AI app builders---",+ "bolt",+ "lovable",+ "replit",+ "v0",+ "---E-commerce---",+ "bigcommerce",+ "ecwid",+ "magento",+ "prestashop",+ "shopify",+ "shopify-hydrogen",+ "thrivecart","woocommerce",- "wordpress"+ "---Courses & communities---",+ "circle",+ "kajabi",+ "podia",+ "teachable",+ "thinkific",+ "---Landing pages & funnels---",+ "clickfunnels",+ "instapage",+ "leadpages",+ "systeme-io",+ "unbounce",+ "---Tag managers---",+ "google-tag-manager",+ "---Desktop, mobile & extensions---",+ "capacitor",+ "chrome-extension",+ "electron",+ "flutter-web",+ "tauri",+ "---Other platforms---",+ "discourse",+ "moodle",+ "odoo"]}diff --git a/docs/content/docs/(docs)/guides/mintlify.mdx b/docs/content/docs/(docs)/guides/mintlify.mdxindex 34aca8297..7ac765ce1 100644--- a/docs/content/docs/(docs)/guides/mintlify.mdx+++ b/docs/content/docs/(docs)/guides/mintlify.mdx@@ -1,125 +1,68 @@---title: Mintlify-description: Integrate Rybbit Analytics with your Mintlify documentation site+description: Add Rybbit analytics to your Mintlify docs+category: docs+icon: SiMintlify----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";--This guide explains how to integrate Rybbit with your Mintlify documentation site for analytics tracking. Mintlify uses a file-based approach for custom scripts where any JavaScript file in your content directory is automatically included on every documentation page.--## How to Add Rybbit to Your Mintlify Docs--Mintlify allows you to add custom JavaScript files to your documentation by placing `.js` files inside your content directory. These files will be automatically included on every page.+Mintlify includes every `.js` file in your docs content directory on every page, so the snippet goes into a small JavaScript file that injects the tag.<Steps><Step>-### Retrieve Your Tracking Script Details+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your **Site ID**. The script source will be `https://app.rybbit.io/api/script.js` (or your self-hosted URL if applicable).+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Create a Custom JavaScript File--Create a new JavaScript file in your Mintlify content directory (typically where your `.mdx` files are located). You can name it something descriptive like `rybbit-analytics.js`.+### Add the snippet to Mintlify-```javascript filename="rybbit-analytics.js"-// Rybbit Analytics Integration-(function() {- // Create the script element- const script = document.createElement('script');- script.src = 'https://app.rybbit.io/api/script.js';- script.defer = true;- script.setAttribute('data-site-id', 'YOUR_SITE_ID'); // Replace with your actual Site ID+Create a JavaScript file in your content directory, next to `docs.json` and your `.mdx` pages:- // Append the script to the document head- document.head.appendChild(script);+```javascript filename="rybbit.js"+(function () {+ var el = document.createElement("script");+ el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";+ el.defer = true;+ document.head.appendChild(el);})();```-Make sure to replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.+Commit and deploy. Mintlify picks the file up automatically; there is nothing to register in `docs.json`. See Mintlify's [custom scripts](https://www.mintlify.com/docs/customize/custom-scripts) page for the current rules on file placement.-If you're self-hosting Rybbit, replace `https://app.rybbit.io/api/script.js` with your self-hosted URL (e.g., `https://your-domain.com/api/script.js`).-</Step>--<Step>-### Verify Installation+To pass [script attributes](/docs/script#script-attributes) such as skip patterns, set them on the element before appending it:-After deploying your Mintlify documentation site, open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded on your pages and the Rybbit tracking requests are being sent.--Look for:-- The `script.js` file being loaded in the Network tab-- POST requests to your Rybbit analytics endpoint (e.g., `/api/track`)-</Step>-</Steps>+```javascript filename="rybbit.js"+el.setAttribute("data-skip-patterns", JSON.stringify(["/internal/**"]));+```<Callout type="info">- **Page View Tracking**: Mintlify documentation sites are Single Page Applications (SPAs). Rybbit's tracking script is designed to automatically detect route changes in SPAs and track them as page views. The default configuration should work out of the box without any additional setup.+Mintlify sites are single-page apps. Rybbit records client-side navigation as pageviews, so no extra code is needed.</Callout>+</Step>-## Advanced Configuration--### Custom Script Attributes--You can customize the Rybbit script behavior by adding data attributes to the script tag:--```javascript filename="rybbit-analytics.js"-(function() {- const script = document.createElement('script');- script.src = 'https://app.rybbit.io/api/script.js';- script.defer = true;- script.setAttribute('data-site-id', 'YOUR_SITE_ID');-- // Optional: Customize debounce duration (default: 500ms)- script.setAttribute('data-debounce', '1000');-- // Optional: Add custom skip patterns for certain URLs- script.setAttribute('data-skip-patterns', JSON.stringify(['/admin/*', '/internal/*']));-- // Optional: Add custom mask patterns for sensitive data- script.setAttribute('data-mask-patterns', JSON.stringify(['password', 'token']));-- document.head.appendChild(script);-})();-```--Available script attributes:-- `data-site-id` (required): Your Rybbit site ID-- `data-debounce`: Debounce duration in milliseconds for tracking events (default: 500)-- `data-skip-patterns`: JSON array of URL patterns to skip tracking-- `data-mask-patterns`: JSON array of patterns to mask in tracked data-- `data-replay-batch-size`: Number of session replay events to batch before sending (default: 250)-- `data-replay-batch-interval`: Interval in milliseconds to send session replay batches (default: 5000)--## Custom Event Tracking+<Step>+### Verify installation-You can track custom events in your Mintlify documentation using the global `window.rybbit` API. This is useful for tracking specific user interactions like button clicks, downloads, or form submissions.+<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>-### Tracking Custom Events in MDX+## Track custom events-Since Mintlify supports MDX, you can add inline event handlers to track custom events:+Mintlify pages are MDX, so you can attach handlers inline:```mdx<button- onClick={() => {- if (typeof window !== 'undefined' && window.rybbit) {- window.rybbit.event('download_clicked', {- file: 'getting-started-guide.pdf',- section: 'introduction'- });- }- }}- className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"+ onClick={() => window.rybbit?.event("download_clicked", { file: "getting-started.pdf" })}>- Download Guide+ Download guide</button>```-## Related Resources+## Next steps-- [Rybbit Script Configuration](/docs/script)-- [Custom Event Tracking](/docs/track-events)-- [Mintlify Documentation](https://mintlify.com/docs)-- [Mintlify Custom Scripts](https://www.mintlify.com/docs/customize/custom-scripts)+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/mkdocs.mdx b/docs/content/docs/(docs)/guides/mkdocs.mdxnew file mode 100644index 000000000..97d64745b--- /dev/null+++ b/docs/content/docs/(docs)/guides/mkdocs.mdx@@ -0,0 +1,83 @@+---+title: MkDocs+description: Add Rybbit analytics to your MkDocs docs+category: docs+icon: SiMaterialformkdocs+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++MkDocs has an `extra_javascript` setting in `mkdocs.yml` that adds a script tag to every page, which works with any theme. If you run Material for MkDocs you can instead extend the theme and place the tag in `<head>` yourself.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to MkDocs++<Tabs items={["mkdocs.yml", "Material theme override"]}>+<Tab value="mkdocs.yml">+Add the script URL to `extra_javascript`. MkDocs 1.5 and later accept the mapping form with a `defer` key:++```yaml title="mkdocs.yml"+extra_javascript:+ - path: https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID+ defer: true+```++On MkDocs 1.4 or older, list the plain URL instead:++```yaml title="mkdocs.yml"+extra_javascript:+ - https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID+```++Themes render `extra_javascript` entries at the end of `<body>` rather than in `<head>`; the script still loads on every page.+</Tab>+<Tab value="Material theme override">+1. Point Material at an overrides directory in `mkdocs.yml`:++ ```yaml title="mkdocs.yml"+ theme:+ name: material+ custom_dir: overrides+ ```++2. Create `overrides/main.html` and fill the `extrahead` block, which Material reserves for custom tags inside `<head>`:++ ```html title="overrides/main.html"+ {% extends "base.html" %}++ {% block extrahead %}+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ {% endblock %}+ ```+</Tab>+</Tabs>++Rebuild with `mkdocs build` and deploy the `site/` directory (or `mkdocs gh-deploy`).++If Material's `navigation.instant` feature is on, page changes go through the History API and Rybbit records them as pageviews without extra code.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Config error on `defer`**: the `path` / `defer` mapping needs MkDocs 1.5+. Run `mkdocs --version` and either upgrade or use the plain URL form.+- **`main.html` has no effect**: the override only applies when `theme.custom_dir` is set and the file sits at `overrides/main.html`, relative to `mkdocs.yml`.+- **Local previews are tracked**: `mkdocs serve` renders the same config as `mkdocs build`. Use a second Rybbit site for local work if that matters.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/moodle.mdx b/docs/content/docs/(docs)/guides/moodle.mdxnew file mode 100644index 000000000..64122a6ab--- /dev/null+++ b/docs/content/docs/(docs)/guides/moodle.mdx@@ -0,0 +1,56 @@+---+title: Moodle+description: Add Rybbit analytics to your Moodle site+category: other+icon: SiMoodle+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Moodle has an **Additional HTML** admin setting that adds code to every page without touching the theme. Its **Within HEAD** field is where the snippet goes.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Moodle++1. Log in as an administrator and go to **Site administration β Appearance β Additional HTML**.+2. Paste the snippet into **Within HEAD**.+3. Click **Save changes**.++The snippet now loads on every page, including course pages, activities and the login page. Users must be able to reach `app.rybbit.io` from their browser; nothing is proxied through the Moodle server.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Moodle renders standard HTML, so `data-rybbit-event` attributes work anywhere you control markup, for example in a course page's HTML block or a label:++```html+<a href="/course/view.php?id=42" data-rybbit-event="course_open" data-rybbit-prop-course="42">+ Open course+</a>+```++For enrolment or completion events, call `window.rybbit.event()` from a small block of JavaScript placed in the **When BODY is closed** field of the same Additional HTML page.++## Troubleshooting++- **Snippet saved but not in the page source**: Moodle caches rendered output. Go to **Site administration β Development β Purge caches** and reload.+- **Pages inside the mobile app are not tracked**: the Moodle app renders course content in its own WebView with its own pages; the Additional HTML setting only affects the web site.+- **Snippet pasted into Custom CSS**: theme settings such as Boost's **Raw SCSS** only accept styles. Use Additional HTML for script tags.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/nextra.mdx b/docs/content/docs/(docs)/guides/nextra.mdxnew file mode 100644index 000000000..318aad7a4--- /dev/null+++ b/docs/content/docs/(docs)/guides/nextra.mdx@@ -0,0 +1,99 @@+---+title: Nextra+description: Add Rybbit analytics to your Nextra docs+category: docs+icon: SiNextra+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Nextra is a Next.js docs framework, so the snippet goes where it goes in any Next.js app: the root layout, rendered with `next/script`. Nextra 4 uses the App Router and `app/layout.jsx`; Nextra 3 uses the Pages Router and `pages/_app.jsx`.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Nextra++Use the `Script` component with `strategy="afterInteractive"` rather than a plain `<script>` tag; the `defer` attribute from the snippet is not needed.++<Tabs items={["Nextra 4 (App Router)", "Nextra 3 (Pages Router)"]}>+<Tab value="Nextra 4 (App Router)">+Add the `Script` next to the `Layout` in `app/layout.jsx` (or `.tsx`):++```jsx title="app/layout.jsx"+import { Footer, Layout, Navbar } from "nextra-theme-docs";+import { Head } from "nextra/components";+import { getPageMap } from "nextra/page-map";+import Script from "next/script";+import "nextra-theme-docs/style.css";++export default async function RootLayout({ children }) {+ return (+ <html lang="en" dir="ltr" suppressHydrationWarning>+ <Head />+ <body>+ <Layout+ navbar={<Navbar logo={<b>My Docs</b>} />}+ pageMap={await getPageMap()}+ footer={<Footer>MIT {new Date().getFullYear()} Β© My Docs.</Footer>}+ >+ {children}+ </Layout>+ <Script+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"+ strategy="afterInteractive"+ />+ </body>+ </html>+ );+}+```+</Tab>+<Tab value="Nextra 3 (Pages Router)">+Create `pages/_app.jsx` if your project does not have one, and render the `Script` beside the page:++```jsx title="pages/_app.jsx"+import Script from "next/script";++export default function App({ Component, pageProps }) {+ return (+ <>+ <Component {...pageProps} />+ <Script+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"+ strategy="afterInteractive"+ />+ </>+ );+}+```++Do not put the tag in the `head` option of `theme.config.jsx`: that option renders through `next/head`, and Next.js warns against loading scripts there.+</Tab>+</Tabs>++Nextra navigates between pages client-side. Rybbit records those route changes as pageviews, so no extra code is needed.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Only the docs pages are tracked**: in Nextra 4 the tag belongs in the root `app/layout.jsx`, not in a nested `app/docs/layout.jsx`, otherwise landing pages outside `docs/` are missed.+- **Upgrading from Nextra 3**: Nextra 4 dropped the Pages Router and `theme.config`. Move the `Script` from `pages/_app.jsx` to `app/layout.jsx` as part of the migration.+- **Proxying through your own domain**: see the [Next.js guide](/docs/guides/react/next-js) for rewrites; every endpoint must be rewritten, not just `script.js`.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/odoo.mdx b/docs/content/docs/(docs)/guides/odoo.mdxnew file mode 100644index 000000000..cfd13098e--- /dev/null+++ b/docs/content/docs/(docs)/guides/odoo.mdx@@ -0,0 +1,62 @@+---+title: Odoo+description: Add Rybbit analytics to your Odoo site+category: other+icon: SiOdoo+---++import { Steps, Step } from "fumadocs-ui/components/steps";++The Odoo Website app has a **Code Injection** setting in the website editor's theme panel with separate `<head>` and `</body>` fields that apply to every page of the website. The snippet goes in the `<head>` field. This works on Odoo Online, Odoo.sh and on-premise installs of Odoo 17 and 18.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Odoo++1. Open your website's frontend and click **Edit** in the top bar.+2. Switch to the **Theme** tab of the editor panel.+3. Scroll to the **Advanced** section and, next to **Code Injection**, click **`<head>`**.+4. Paste the snippet into the editor that opens and click **Save**.+5. Click **Save** in the website editor to publish the change.++The code is stored per website. If you run several websites from one Odoo database, switch website in the top bar and repeat the steps for each one.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Odoo eCommerce pages render standard HTML, so use `data-rybbit-event` attributes on any element you add in the editor, or call `window.rybbit.event()` from the `</body>` Code Injection field:++```html+<script>+ document.addEventListener("click", function (e) {+ if (e.target.closest("#add_to_cart")) {+ window.rybbit.event("add_to_cart");+ }+ });+</script>+```++The confirmation page is served at `/shop/confirmation`; a script that checks `window.location.pathname` there can send a `purchase` event once per order.++## Troubleshooting++- **The `<head>` button is missing**: Code Injection requires the **Website β Editor and Designer** access right. An administrator can grant it under **Settings β Users & Companies β Users**, on the user's **Access Rights** tab.+- **Change is visible while logged in but not for visitors**: click **Save** in the editor after closing the code window; the code is published with the page.+- **Multiple websites**: the field applies only to the website currently selected in the editor.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/payload.mdx b/docs/content/docs/(docs)/guides/payload.mdxnew file mode 100644index 000000000..efcc192ec--- /dev/null+++ b/docs/content/docs/(docs)/guides/payload.mdx@@ -0,0 +1,67 @@+---+title: Payload+description: Add Rybbit analytics to your Payload site+category: cms+icon: SiPayloadcms+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Payload is a headless CMS that installs into a Next.js app: the admin panel lives in the `(payload)` route group and your site in the `(frontend)` route group. The tracking snippet goes into the frontend root layout, not into Payload's config or admin panel.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Payload++<Callout type="info">+Payload has no template or head setting to paste into. Add the snippet to the root layout of the Next.js frontend that renders your site.+</Callout>++In both the `website` and `blank` templates created by `npx create-payload-app`, the frontend root layout is `src/app/(frontend)/layout.tsx`. Render `next/script` there, exactly as in the [Next.js guide](/docs/guides/react/next-js), so the script loads on every public route and stays out of the admin panel under `src/app/(payload)/`.++```tsx title="src/app/(frontend)/layout.tsx"+import Script from "next/script";++export default function RootLayout({ children }: { children: React.ReactNode }) {+ return (+ <html lang="en">+ <body>+ {children}+ <Script+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"+ strategy="afterInteractive"+ />+ </body>+ </html>+ );+}+```++The script tracks client-side route changes automatically, so Next.js `<Link>` navigation between Payload pages and posts is counted without extra code.++If your frontend is a separate app (Nuxt, Astro, SvelteKit) that fetches from Payload's REST or GraphQL API, follow that framework's guide instead: [Nuxt](/docs/guides/vue/nuxt), [Astro](/docs/guides/astro), [SvelteKit](/docs/guides/svelte/sveltekit), [Remix](/docs/guides/react/remix).+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Live Preview counts as visits**: the admin panel's Live Preview loads your frontend in an iframe at the URL set in `admin.livePreview.url`. Editors' preview sessions are tracked like any other visitor. Point `livePreview.url` at a separate preview deployment registered as its own site in Rybbit, or skip the tag in preview builds.+- **Draft preview routes**: if you use the `website` template's `/next/preview` route or Next.js draft mode, those pages are also tracked. Add `data-skip-patterns='["/next/**"]'` to the script tag to exclude them.+- **Admin panel is not tracked**: `/admin` is rendered by the `(payload)` route group, which has its own layout without the snippet. Put the tag in the `(frontend)` layout only.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/phoenix.mdx b/docs/content/docs/(docs)/guides/phoenix.mdxnew file mode 100644index 000000000..78c620de6--- /dev/null+++ b/docs/content/docs/(docs)/guides/phoenix.mdx@@ -0,0 +1,96 @@+---+title: Phoenix+description: Add Rybbit analytics to your Phoenix app+category: backend+icon: SiPhoenixframework+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Phoenix renders every page inside the root layout, `lib/my_app_web/components/layouts/root.html.heex`, which owns the `<html>` and `<head>` tags, so the snippet goes there. Read the site ID from application config set in `config/runtime.exs`, so it comes from an environment variable at boot and stays out of the template.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Phoenix++#### Configure the site ID++`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"+config :my_app, :rybbit,+ instance_url: System.get_env("RYBBIT_INSTANCE_URL", "https://app.rybbit.io"),+ site_id: System.get_env("RYBBIT_SITE_ID")+```++Then set the variables where the app runs:++```bash+export RYBBIT_INSTANCE_URL=https://app.rybbit.io+export RYBBIT_SITE_ID=YOUR_SITE_ID+```++#### Expose the config to the layout++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"+defmodule MyAppWeb.Layouts do+ use MyAppWeb, :html++ embed_templates "layouts/*"++ def rybbit_config, do: Application.get_env(:my_app, :rybbit, [])+end+```++#### Add the tag to the root layout++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"+<head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <meta name="csrf-token" content={get_csrf_token()} />+ <.live_title suffix=" Β· Phoenix Framework">{assigns[:page_title] || "MyApp"}</.live_title>+ <link phx-track-static rel="stylesheet" href={~p"/assets/app.css"} />+ <script defer phx-track-static type="text/javascript" src={~p"/assets/app.js"}></script>++ <script+ :if={rybbit_config()[:site_id]}+ src={"#{rybbit_config()[:instance_url]}/api/script.js?siteId=#{rybbit_config()[:site_id]}"}+ defer+ ></script>+</head>+```++The `:if` attribute skips the tag when `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.++#### LiveView navigation++`<.link navigate>`, `<.link patch>`, `push_navigate/2` and `push_patch/2` change the URL with `history.pushState` (or `replaceState` when `replace: true`) and keep the root layout, including its `<head>`, in place. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so each live navigation is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `phx:` event listener is needed. A regular `<.link href>` does a full page load, which the script also tracks.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Tag missing**: `config/runtime.exs` is evaluated at boot, so restart the app or release after changing `RYBBIT_SITE_ID`. Check with `Application.get_env(:my_app, :rybbit)` in `iex -S mix`.+- **Content Security Policy**: if you set a `content-security-policy` header in a plug, 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 `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/podia.mdx b/docs/content/docs/(docs)/guides/podia.mdxnew file mode 100644index 000000000..69cf3886d--- /dev/null+++ b/docs/content/docs/(docs)/guides/podia.mdx@@ -0,0 +1,83 @@+---+title: Podia+description: Add Rybbit analytics to your Podia site+category: creators+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Podia has a **Third-party code** setting under **Settings > Analytics** that adds the snippet to every public page of your site, including checkout. Podia inserts custom code just before the closing `</body>` tag rather than in `<head>`; the Rybbit script loads with `defer` and works the same from either position.++<Callout type="warn">+Third-party code is available on Podia's **Mover** and **Shaker** plans. On the free plan the Third-party code option is not shown.+</Callout>++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Podia++1. From your home feed, click your site name and choose **Admin**.+2. In the Admin sidebar, open **Settings > Analytics**.+3. Click **Edit** next to **Third-party code**.+4. Paste the snippet into the **Website tracking code** field.+5. Click **Save**. The code is live as soon as it is saved; there is no separate publish step.++The website tracking code runs on every public page of your site and on checkout pages. It does not run inside logged-in areas such as the customer dashboard, product viewer or community spaces.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++#### Purchase++Podia has a second field, **Conversion tracking code**, directly below the website tracking code. Code in that field runs only on the thank-you page after a purchase or membership signup, and Podia exposes the order as a `Podia.Conversion` object on that page (once per order; it is gone after a refresh).++Paste this into **Conversion tracking code** to send a `purchase` event with the order details:++```html+<script>+(function () {+ var c = window.Podia && window.Podia.Conversion;+ if (!c) return;+ var payload = {+ product: c.object.name,+ order_id: c.object.order_id,+ value: c.revenue,+ currency: c.currency+ };+ var start = Date.now();+ (function send() {+ if (window.rybbit && typeof window.rybbit.event === "function") {+ return window.rybbit.event("purchase", payload);+ }+ if (Date.now() - start < 8000) setTimeout(send, 150);+ })();+})();+</script>+```++The short polling loop is there because Podia runs the conversion code before the deferred tracking script has finished loading. `revenue` is `0` for free products and free membership plans, so filter on `value` in the dashboard if you only want paid orders.++## Troubleshooting++- **No Third-party code option**: the site is on the free plan. Third-party code requires Mover or Shaker.+- **No pageviews while you test**: Podia does not output tracking code when you are logged in to your own Podia account. Test in a private window, or log out first.+- **Logged-in member pages are missing**: expected. Custom code runs only on public pages and checkout, not in the customer dashboard, product viewer or community.+- **Duplicate purchase events**: `Podia.Conversion` is only present on the first load of the thank-you page, so a refresh does not resend. If you see duplicates, make sure the event script is in Conversion tracking code only and not also in Website tracking code.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/preact.mdx b/docs/content/docs/(docs)/guides/preact.mdxnew file mode 100644index 000000000..e97b679f3--- /dev/null+++ b/docs/content/docs/(docs)/guides/preact.mdx@@ -0,0 +1,69 @@+---+title: Preact+description: Add Rybbit analytics to your Preact app+category: frameworks+icon: SiPreact+---++import { Steps, Step } from "fumadocs-ui/components/steps";++A Preact app scaffolded with `npm init preact` (or Vite's `preact` template) has a single `index.html` at the project root. Paste the snippet into its `<head>` and it loads on every route.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Preact++Open `index.html` at the root of the project and paste the snippet inside `<head>`:++```html title="index.html"+<!DOCTYPE html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <link rel="icon" type="image/svg+xml" href="/vite.svg" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <title>Vite + Preact</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ </head>+ <body>+ <div id="app"></div>+ <script type="module" src="/src/index.jsx"></script>+ </body>+</html>+```++Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by `preact-iso`, `preact-router` or a similar router are tracked automatically as pageviews.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.++```jsx title="src/components/SignupButton.jsx"+export function SignupButton() {+ const handleClick = () => {+ if (window.rybbit) {+ window.rybbit.event("signup_click", { location: "hero" });+ }+ };++ return <button onClick={handleClick}>Sign up</button>;+}+```++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/prestashop.mdx b/docs/content/docs/(docs)/guides/prestashop.mdxindex 82c4f894d..62e765e14 100644--- a/docs/content/docs/(docs)/guides/prestashop.mdx+++ b/docs/content/docs/(docs)/guides/prestashop.mdx@@ -1,130 +1,62 @@---title: PrestaShop-description: Integrate Rybbit Analytics with your PrestaShop store+description: Add Rybbit analytics to your PrestaShop store+category: ecommerce+icon: SiPrestashop----import { Tabs, Tab } from 'fumadocs-ui/components/tabs';-import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-PrestaShop is a popular open-source e-commerce platform. Here's how to add Rybbit Analytics to track visitors and conversions on your PrestaShop store.--## How to Add Rybbit to PrestaShop--<Tabs items={['Custom Code Module', 'Theme Files']}>-<Tab>-### Using a Custom Code Module--PrestaShop's back office has no native option for injecting custom code into the-`<head>`. To add the tracking script without editing template files, install a-custom-code / header-injection module.+PrestaShop's back office has no built-in setting for custom `<head>` code, so the snippet goes in either through a header-injection module from the Addons marketplace or directly into your theme's `head.tpl`. Either way, clear the cache afterwards.<Steps><Step>-### Install a Custom Code Module--1. Log in to your PrestaShop Back Office-2. Go to **Modules** > **Module Catalog** (or **Module Manager**)-3. Install a module that injects custom code into the page header β for example- a "Custom HTML" or "Header/Head code" module from the- [PrestaShop Addons marketplace](https://addons.prestashop.com/)--<Callout type="info">-PrestaShop does not ship a built-in head-injection UI, so a third-party module is-required for this method. If you prefer not to install one, use the **Theme Files**-tab instead.-</Callout>-</Step>--<Step>-### Add the Tracking Script--Open the module's configuration and paste the following into its head / header-code field:--```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.defer = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();-</script>-```+### Get your tracking snippet-Replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Save Changes+### Add the snippet to PrestaShop-Save the module configuration and clear the cache under **Advanced Parameters** >-**Performance** to apply the tracking code to your store.-</Step>-</Steps>+<Tabs items={["Custom code module", "Theme files"]}>+<Tab>+1. In the back office, go to **Modules > Module Manager** (or **Module Catalog**) and install a module that injects custom HTML into the page header, for example a "Custom HTML" or "Header code" module from the [PrestaShop Addons marketplace](https://addons.prestashop.com/).+2. Open the module's configuration, paste the snippet into its head / header code field, and save.+3. Go to **Advanced Parameters > Performance** and click **Clear cache**.</Tab><Tab>-### Editing Theme Files--For direct control, you can edit your theme's template files.-<Callout type="warn">-Create a child theme before editing files to preserve changes during updates.+Edit a child theme. Changes to the parent theme are lost on theme updates.</Callout>-<Steps>-<Step>-### Access Theme Files--Navigate to your theme folder via FTP/SFTP or file manager:-```-/themes/your-theme-name/templates/_partials/-```-</Step>--<Step>-### Edit the Header Template--Open `head.tpl` and add the following before the closing `</head>` tag (or at the end of the file):--```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.defer = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();-</script>-```--Replace `YOUR_SITE_ID` with your actual Site ID.+1. Over FTP/SFTP or a file manager, open `/themes/your-theme-name/templates/_partials/head.tpl`.+2. Paste the snippet at the end of the file, before the closing `</head>` tag, and save.+3. Go to **Advanced Parameters > Performance** and click **Clear cache**.+</Tab>+</Tabs></Step><Step>-### Clear Cache+### Verify installation-1. Go to **Advanced Parameters** > **Performance**-2. Click **Clear cache**+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-</Tab>-</Tabs>-## Tracking E-commerce Events+## Track custom events-### Track Purchases+#### Purchase-To track completed purchases, add a script to the order confirmation page. Create a module or add to your theme's `order-confirmation.tpl`:+Add this to your theme's `order-confirmation.tpl`, or output it from a module hooked to the order confirmation page. PrestaShop renders templates with Smarty, so the `$order` variables are filled in with the order data:```html{if isset($order)}<script>-(function() {+(function () {function waitForRybbit(callback, timeout) {var start = Date.now();(function check() {@@ -136,7 +68,7 @@ To track completed purchases, add a script to the order confirmation page. Creat})();}- waitForRybbit(function() {+ waitForRybbit(function () {window.rybbit.event('purchase', {transaction_id: '{$order.details.reference}',value: {$order.totals.total.amount},@@ -148,24 +80,14 @@ To track completed purchases, add a script to the order confirmation page. Creat{/if}```-<Callout type="info">-PrestaShop uses Smarty templating. The `{$variable}` syntax is processed by PrestaShop to inject order data.-</Callout>+`waitForRybbit` polls until the tracking script from `head.tpl` has defined `window.rybbit`, so the event is not lost when the confirmation script runs first.## Troubleshooting-### Script not loading--1. Clear PrestaShop cache: **Advanced Parameters** > **Performance** > **Clear cache**-2. Disable any JavaScript optimization modules temporarily-3. Check the page source to verify the script is present--### Theme updates overwriting changes--Always use a child theme when editing template files. Changes to the parent theme will be lost on updates.+- **Script not on the page**: clear the cache under **Advanced Parameters > Performance**, and temporarily disable any JavaScript optimisation or combine/minify module.+- **Theme updates overwrite the snippet**: keep template edits in a child theme; parent-theme changes are lost on update.+- **Purchase event missing**: the `$order` Smarty variables differ between PrestaShop versions. Compare them with your version's `order-confirmation.tpl` and place a test order to confirm the event arrives.-### E-commerce events not tracking+## Next steps-1. Verify the Smarty variables match your PrestaShop version-2. Check the browser console for JavaScript errors-3. Test by completing a test order+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/qwik.mdx b/docs/content/docs/(docs)/guides/qwik.mdxnew file mode 100644index 000000000..bf39f6641--- /dev/null+++ b/docs/content/docs/(docs)/guides/qwik.mdx@@ -0,0 +1,83 @@+---+title: Qwik+description: Add Rybbit analytics to your Qwik app+category: frameworks+icon: SiQwik+---++import { Steps, Step } from "fumadocs-ui/components/steps";++A Qwik City app renders the whole document from `src/root.tsx`, which owns the `<head>` and `<body>` elements. Add the snippet to that `<head>` and it is on every route.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Qwik++Open `src/root.tsx` and add the tag inside `<head>`, after `<RouterHead />`:++```tsx title="src/root.tsx"+import { component$ } from "@builder.io/qwik";+import { QwikCityProvider, RouterOutlet } from "@builder.io/qwik-city";+import { RouterHead } from "./components/router-head/router-head";++import "./global.css";++export default component$(() => {+ return (+ <QwikCityProvider>+ <head>+ <meta charset="utf-8" />+ <RouterHead />+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ </head>+ <body lang="en">+ <RouterOutlet />+ </body>+ </QwikCityProvider>+ );+});+```++`src/components/router-head/router-head.tsx` renders per-route `head` exports (title, meta, links). Keep the Rybbit tag in `root.tsx` so it does not depend on any route's `head` export.++Navigations through Qwik City's `<Link>` component are tracked automatically as pageviews.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `window.rybbit.event()` from a `$` event handler. Handlers only run in the browser, so `window` is always defined; guard against a blocked or still-loading script.++```tsx title="src/components/signup-button.tsx"+import { component$ } from "@builder.io/qwik";++export const SignupButton = component$(() => {+ return (+ <button+ onClick$={() => {+ if (window.rybbit) {+ window.rybbit.event("signup_click", { location: "hero" });+ }+ }}+ >+ Sign up+ </button>+ );+});+```++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/rails.mdx b/docs/content/docs/(docs)/guides/rails.mdxnew file mode 100644index 000000000..67866f050--- /dev/null+++ b/docs/content/docs/(docs)/guides/rails.mdx@@ -0,0 +1,87 @@+---+title: Ruby on Rails+description: Add Rybbit analytics to your Ruby on Rails app+category: backend+icon: SiRubyonrails+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Rails wraps every page in `app/views/layouts/application.html.erb`, so the snippet goes into that layout's `<head>`. Read the site ID from a custom `config.x` setting fed by an environment variable, so the template stays free of hard-coded IDs and each environment can use its own site.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Ruby on Rails++#### Configure the site ID++Add the Rybbit values to your environment (`.env` if you use dotenv-rails, otherwise your host's environment settings):++```bash filename=".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"+module MyApp+ class Application < Rails::Application+ # ... existing configuration++ config.x.rybbit.instance_url = ENV.fetch("RYBBIT_INSTANCE_URL", "https://app.rybbit.io")+ config.x.rybbit.site_id = ENV["RYBBIT_SITE_ID"]+ end+end+```++#### Add the tag to your layout++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"+<head>+ <title><%= content_for(:title) || "MyApp" %></title>+ <meta name="viewport" content="width=device-width,initial-scale=1">+ <%= csrf_meta_tags %>+ <%= csp_meta_tag %>+ <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>+ <%= javascript_importmap_tags %>++ <% if Rails.configuration.x.rybbit.site_id.present? %>+ <script src="<%= Rails.configuration.x.rybbit.instance_url %>/api/script.js?siteId=<%= Rails.configuration.x.rybbit.site_id %>" defer></script>+ <% end %>+</head>+```++The `if` guard skips the tag wherever `RYBBIT_SITE_ID` is unset, so development and test environments are not tracked unless you set the variable there.++If you have more than one HTML layout (for example `application.html.erb` and `admin.html.erb`), add the tag to each, or move it into a partial such as `app/views/layouts/_rybbit.html.erb` and `<%= render "layouts/rybbit" %>` from every layout. Mailer layouts do not need it.++#### Turbo and Hotwire++Turbo Drive replaces the page `<body>` on each visit, merges the `<head>`, and pushes the new URL with `history.pushState`. The Rybbit script hooks `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`, so every Turbo visit is tracked as a pageview while **SPA Navigation** is enabled in your site settings (the default). No `turbo:load` listener is needed. Because the script tag is in `<head>` and identical on every page, Turbo Drive keeps the existing tag instead of loading it again.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Tag missing**: `config/application.rb` is read once at boot, so restart the server after changing `RYBBIT_SITE_ID`. Check `Rails.configuration.x.rybbit.site_id` in `rails console` if the tag does not render.+- **Content Security Policy**: if you set a policy in `config/initializers/content_security_policy.rb`, add your Rybbit host to `script_src` and `connect_src`, or the browser blocks both the script and the `/api/track` requests. Alternatively [proxy the script](/docs/proxy-guide) through your own domain so no extra origin is needed.+- **Self-hosted instance**: set `RYBBIT_INSTANCE_URL` to your own domain without a trailing slash; the layout appends the script path to it.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/react/gatsby.mdx b/docs/content/docs/(docs)/guides/react/gatsby.mdxindex 333263498..5273b08c1 100644--- a/docs/content/docs/(docs)/guides/react/gatsby.mdx+++ b/docs/content/docs/(docs)/guides/react/gatsby.mdx@@ -1,141 +1,99 @@---title: Gatsby-description: Integrate Rybbit with your Gatsby site for analytics tracking+description: Add Rybbit analytics to your Gatsby site+category: frameworks+icon: SiGatsby----import { Steps, Step } from 'fumadocs-ui/components/steps'-import { Callout } from 'fumadocs-ui/components/callout'+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";--This guide explains how to integrate Rybbit with your Gatsby site for analytics tracking. Gatsby is a React-based static site generator that builds fast, optimized websites.--## How to Add Rybbit to Your Gatsby Site--The recommended way to add a script that should appear on every page in a Gatsby site is by using the `onRenderBody` API in `gatsby-ssr.js`. This ensures the script is included in the HTML generated during the build process.+Gatsby generates the `<head>` of every page at build time. Add the snippet through the `onRenderBody` API in `gatsby-ssr.js`, or with Gatsby's own `<Script>` component if you want control over load timing.<Steps><Step>-### Retrieve Your Tracking Script Details+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your **Site ID**. The script source will be `https://app.rybbit.io/api/script.js`.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Modify `gatsby-ssr.js`+### Add the snippet to Gatsby-Create a `gatsby-ssr.js` file at the root of your Gatsby project if it doesn't already exist. Add the following code to it:+<Tabs items={["gatsby-ssr.js", "Gatsby Script component"]}>+<Tab value="gatsby-ssr.js">+Create `gatsby-ssr.js` at the root of your project if it does not exist and register the script with `setHeadComponents`:-```javascript filename="gatsby-ssr.js"-import React from 'react';+```javascript title="gatsby-ssr.js"+import React from "react";export const onRenderBody = ({ setHeadComponents }) => {- const rybbitSiteId = 'YOUR_SITE_ID'; // Replace with your actual Site ID-setHeadComponents([<script- key="rybbit-analytics-script" // A unique key for React- src="https://app.rybbit.io/api/script.js"- data-site-id={rybbitSiteId}+ key="rybbit-analytics"+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"defer/>,]);};```-Make sure to replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard. This will add the Rybbit script to the `<head>` of every page generated by Gatsby.-</Step>-<Step>-### Verify Installation+This puts the tag in the `<head>` of every generated page.+</Tab>+<Tab value="Gatsby Script component">+The [Gatsby Script API](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-script/) loads third-party scripts with a chosen `strategy` (`post-hydrate`, `idle` or `off-main-thread`). Render it in a layout component that wraps every page:-After rebuilding and deploying your Gatsby site (e.g., `gatsby build` and then serve the `public` folder, or your deployment process), open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded on your pages.-</Step>-</Steps>+```jsx title="src/components/layout.js"+import React from "react";+import { Script } from "gatsby";-### Alternative: Using `gatsby-plugin-script`--Gatsby also offers `gatsby-plugin-script` for more fine-grained control over script loading. If you prefer this method:--1. Install the plugin: `npm install gatsby-plugin-script` or `yarn add gatsby-plugin-script`.-2. Add it to your `gatsby-config.js`:--```javascript filename="gatsby-config.js"-module.exports = {- plugins: [- // ... other plugins- {- resolve: `gatsby-plugin-script`,- options: {- src: `https://app.rybbit.io/api/script.js`,- defer: true,- ['data-site-id']: `YOUR_SITE_ID`, // Replace with your Site ID- // strategy: 'post-hydrate', // Or 'idle', 'off-main-thread'- },- },- ],-};+export default function Layout({ children }) {+ return (+ <>+ {children}+ <Script+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"+ strategy="post-hydrate"+ />+ </>+ );+}```-The `onRenderBody` method is generally simpler for a basic async script like Rybbit's.+</Tab>+</Tabs>-<Callout type="info">- **Page View Tracking**: Gatsby sites behave like Single Page Applications (SPAs) after the initial load. Rybbit's tracking script is designed to automatically detect route changes (e.g., when using Gatsby's `<Link>` component) and track them as page views.+Rebuild the site (`gatsby build`) and deploy the `public` folder. Client-side navigation through Gatsby's `<Link>` is tracked automatically as pageviews.+</Step>- If you find that page views are not being tracked correctly after client-side navigation, you might need to manually trigger page views. You can do this using the `onRouteUpdate` API in `gatsby-browser.js`:+<Step>+### Verify installation- ```javascript filename="gatsby-browser.js"- export const onRouteUpdate = ({ location, prevLocation }) => {- if (typeof window !== 'undefined' && window.rybbit && location.pathname !== prevLocation?.pathname) {- // Rybbit should auto-track, but if needed:- // window.rybbit.pageview();- console.log("Rybbit: Route updated to", location.pathname); // For debugging- }- };- ```- Create `gatsby-browser.js` at the root of your project if it doesn't exist. **Test the default behavior first**, as manual tracking might not be necessary.-</Callout>+<include>../../../../partials/guides/verify.mdx</include>+</Step>+</Steps>-## Custom Event Tracking+## Track custom events-Since Gatsby uses React, you can track custom events from any of your React components.+Call `window.rybbit.event()` from any React component. Guard the call, because Gatsby renders components on the server during the build.-**Example in a Gatsby component:**-```jsx-// src/components/MyInteractiveButton.js-import React from 'react';+```jsx title="src/components/TrackedButton.js"+import React from "react";-const MyInteractiveButton = ({ buttonText, eventName, eventData }) => {+export default function TrackedButton({ label, eventName, eventData }) {const handleClick = () => {- if (typeof window !== 'undefined' && window.rybbit) {- window.rybbit.event(eventName || 'gatsby_button_click', eventData || {});+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.event(eventName, eventData);}};- return (- <button onClick={handleClick}>- {buttonText || "Click Me"}- </button>- );-};--export default MyInteractiveButton;-```-You can then use this component in your pages or other components:-```jsx-// src/pages/my-page.js-import React from "react"-import MyInteractiveButton from "../components/MyInteractiveButton"--const MyPage = () => (- <div>- <h1>Welcome to My Gatsby Page</h1>- <MyInteractiveButton- buttonText="Track Special Action"- eventName="special_action_taken"- eventData={{ pageContext: "my-page" }}- />- </div>-)--export default MyPage+ return <button onClick={handleClick}>{label}</button>;+}```-Always ensure `window.rybbit` is available before calling its methods in client-side scripts.+## 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.++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/react/meta.json b/docs/content/docs/(docs)/guides/react/meta.jsonindex 32845ac7a..510fa8c96 100644--- a/docs/content/docs/(docs)/guides/react/meta.json+++ b/docs/content/docs/(docs)/guides/react/meta.json@@ -1,4 +1,11 @@{"title": "React",- "pages": ["next-js", "vite-cra", "gatsby", "remix"]+ "pages": [+ "next-js",+ "vite-cra",+ "react-router",+ "tanstack-start",+ "remix",+ "gatsby"+ ]}diff --git a/docs/content/docs/(docs)/guides/react/next-js.mdx b/docs/content/docs/(docs)/guides/react/next-js.mdxindex 6a2ce0259..5048d1137 100644--- a/docs/content/docs/(docs)/guides/react/next-js.mdx+++ b/docs/content/docs/(docs)/guides/react/next-js.mdx@@ -1,184 +1,99 @@---title: Next.js-description: Integrate Rybbit with your Next.js application for analytics tracking+description: Add Rybbit analytics to your Next.js app+category: frameworks+icon: SiNextdotjs----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";--Next.js is a popular React framework that enables features like server-side rendering and static site generation. This guide explains how to integrate Rybbit with your Next.js application.--## How to Add Rybbit to Next.js+Next.js ships a [Script component](https://nextjs.org/docs/app/building-your-application/optimizing/scripts) that controls when a third-party script loads. Render it once in your root layout (App Router) or custom `App` (Pages Router) so the snippet is on every page.<Steps><Step>-### Retrieve Your Tracking Script+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your site ID. You'll need this for the `data-site-id` attribute.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Install the Script Using Next.js Script Component+### Add the snippet to Next.js-Next.js provides a built-in [Script component](https://nextjs.org/docs/app/building-your-application/optimizing/scripts) that handles script loading efficiently. This is the recommended approach.-</Step>--<Step>-### Add to Your Layout File+Use `next/script` with `strategy="afterInteractive"` instead of a plain `<script>` tag. The `defer` attribute from the snippet is not needed; the strategy handles load timing.-Create or modify your layout file depending on your Next.js version:--**For App Router (Next.js 13+):**--```jsx-// app/layout.js-import Script from "next/script"+<Tabs items={["App Router", "Pages Router"]}>+<Tab value="App Router">+```jsx title="app/layout.js"+import Script from "next/script";export default function RootLayout({ children }) {return (<html lang="en">- <head /><body>{children}<Script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"strategy="afterInteractive"/></body></html>- )+ );}```+</Tab>+<Tab value="Pages Router">+```jsx title="pages/_app.js"+import Script from "next/script";-**For Pages Router:**--```jsx-// pages/_app.js-import Script from "next/script"--function MyApp({ Component, pageProps }) {+export default function MyApp({ Component, pageProps }) {return (<><Component {...pageProps} /><Script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"strategy="afterInteractive"/></>- )+ );}--export default MyApp```-</Step>-</Steps>--### (optional) 4. Rewrite the script serving to bypass ad blockers--While Rybbit is not using any cookied based tracking and is fully compliant-with GDPR, CCPA, and other privacy regulations, some ad blockers may still agressively-block it no matter how the tracking is implemented or operated.--With Next.js's [rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) feature, you can rewrite the script serving to reduce the chance of being blocked by ad blockers.--```dotenv-# .env--# use this value if you are self-hosting Rybbit-NEXT_PUBLIC_RYBBIT_HOST=https://your-hosted-rybbit-instance.com--# use this value if you are using the Rybbit hosted tracking-NEXT_PUBLIC_RYBBIT_HOST=https://app.rybbit.io-```--```js-// next.config.js-module.exports = {- // ... other configurations- async rewrites() {- return [- {- source: "/api/script.js",- destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/script.js`,- },- {- source: "/api/track",- destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/track`,- },- {- source: "/api/identify",- destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/identify`,- },- {- source: "/api/replay.js",- destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/replay.js`,- },- {- source: "/api/site/:path*",- destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/site/:path*`,- },- {- source: "/api/session-replay/:path*",- destination: `${process.env.NEXT_PUBLIC_RYBBIT_HOST}/api/session-replay/:path*`,- },- ]- },-}-```--The script derives its API base from its own `src`, so once you serve it from `/api/script.js` it will call every other endpoint under `/api` on your own domain too. All six rewrites are required: `script.js` and `track` cover the script and pageview/event traffic, `identify` covers `identify()`, `replay.js` and `session-replay/:path*` cover session replay, and `site/:path*` covers the tracking-config and feature-flag requests. If you omit the `site/:path*` rewrite, the tracking-config fetch fails and the script silently falls back to its defaults, disabling web vitals, error tracking, session replay, and button/copy/form autocapture.--and where you are using the script:--```jsx-// app/layout.js or pages/_app.js-<Script- src="/api/script.js"- data-site-id="YOUR_SITE_ID"- strategy="afterInteractive"-/>-```--Note that this rewrite will consume the bandwidth of your server, as all tracking requests will be proxied through your Next.js application. Consider this when evaluating your hosting costs and server capacity requirements.+</Tab>+</Tabs>+Client-side navigation through `<Link>` and `router.push()` is tracked automatically as pageviews; no extra code is needed.+</Step>-<Callout type="info">- **Page View Tracking in Next.js**: Rybbit's tracking script is designed to automatically detect route changes when using Next.js's `<Link>` component or `router.push()` and track them as page views. If you encounter a rare scenario where page views are not being tracked correctly after client-side navigation, you might need to manually trigger page views using `window.rybbit.pageview()`. However, test the default behavior first, as manual tracking is typically not necessary.-</Callout>+<Step>+### Verify installation-## Custom Event Tracking+<include>../../../../partials/guides/verify.mdx</include>+</Step>+</Steps>-Once the Rybbit script is loaded via the Next.js `Script` component, you can track custom events from any of your React components within your Next.js application.+## Track custom events-```jsx-// Example in a Next.js component-// components/MyButton.js-'use client'; // If using App Router and this component has interactivity+Call `window.rybbit.event()` from any client component. Guard the call, because the script loads after hydration and components can also render on the server.-// Declare rybbit on window for TypeScript if you're using it-// declare global {-// interface Window {-// rybbit?: {-// event: (eventName: string, eventData?: Record<string, any>) => void;-// pageview: () => void;-// // Add other methods if you use them-// };-// }-// }+```jsx title="components/MyButton.js"+"use client";export default function MyButton({ title }) {const handleClick = () => {- if (typeof window !== 'undefined' && window.rybbit && typeof window.rybbit.event === 'function') {- window.rybbit.event('button_click', { buttonTitle: title });- } else {- console.warn('Rybbit tracking not available.');+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.event("button_click", { buttonTitle: title });}};- return <button onClick={handleClick}>{title || 'Click Me'}</button>;+ return <button onClick={handleClick}>{title}</button>;}```-Always ensure `window.rybbit` and its methods are available before calling them, especially since the script loading is managed by Next.js's `strategy`. Consider the script's loading strategy (`afterInteractive` in the examples) when deciding where and how early you can reliably call these tracking functions.++## Troubleshooting++- **Proxying through your own domain**: Next.js [rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) can serve the script and its API from your domain. Follow the [Next.js proxy guide](/docs/proxy-guide/next-js); every endpoint must be rewritten, including `site/tracking-config`, otherwise the script silently falls back to default settings and features such as web vitals and session replay stay off.+- **Pageviews missing after client-side navigation**: this is rare; call `window.rybbit.pageview()` yourself after the route change only if the default behaviour does not work for you.++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/react/react-router.mdx b/docs/content/docs/(docs)/guides/react/react-router.mdxnew file mode 100644index 000000000..0c3344d9e--- /dev/null+++ b/docs/content/docs/(docs)/guides/react/react-router.mdx@@ -0,0 +1,83 @@+---+title: React Router+description: Add Rybbit analytics to your React Router app+category: frameworks+icon: SiReactrouter+---++import { Steps, Step } from "fumadocs-ui/components/steps";++In React Router framework mode (v7 and later, the successor to Remix), `app/root.tsx` renders the `<html>` document for every route. Add the snippet to the `<head>` in its `Layout` export. This guide supersedes the [Remix guide](/docs/guides/react/remix); if you use React Router only as a library inside a Vite app, follow the [React (Vite / CRA) guide](/docs/guides/react/vite-cra) instead.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to React Router++Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component, after `<Meta />` and `<Links />`. `Layout` wraps the app, `HydrateFallback` and `ErrorBoundary`, so the snippet stays in place in every state:++```tsx title="app/root.tsx"+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";++export function Layout({ children }: { children: React.ReactNode }) {+ return (+ <html lang="en">+ <head>+ <meta charSet="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <Meta />+ <Links />+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ </head>+ <body>+ {children}+ <ScrollRestoration />+ <Scripts />+ </body>+ </html>+ );+}++export default function App() {+ return <Outlet />;+}+```++If your `root.tsx` has no `Layout` export, add the tag to the `<head>` of the default `App` component instead. Restart the dev server after the change. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.+</Step>++<Step>+### Verify installation++<include>../../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `window.rybbit.event()` from any route or component. Check for `window` first, because route modules also render on the server.++```tsx title="app/routes/pricing.tsx"+export default function Pricing() {+ const handleClick = () => {+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.event("plan_selected", { plan: "pro" });+ }+ };++ return <button onClick={handleClick}>Choose Pro</button>;+}+```++## Troubleshooting++- **Nonce-based Content Security Policy**: if you pass a `nonce` to `<Scripts />` and `<ScrollRestoration />`, add the same `nonce` attribute to the Rybbit tag, otherwise the browser blocks it.++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/react/remix.mdx b/docs/content/docs/(docs)/guides/react/remix.mdxindex 0246dda64..7014d350c 100644--- a/docs/content/docs/(docs)/guides/react/remix.mdx+++ b/docs/content/docs/(docs)/guides/react/remix.mdx@@ -1,51 +1,30 @@---title: Remix-description: Integrate Rybbit with your Remix application for analytics tracking+description: Add Rybbit analytics to your Remix app+category: frameworks+icon: SiRemix----import { Steps, Step } from 'fumadocs-ui/components/steps'-import { Callout } from 'fumadocs-ui/components/callout'+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your Remix application for analytics tracking. Remix is a full-stack web framework that leverages React for building user interfaces.--## How to Add Rybbit to Your Remix App--The recommended way to add a script that should appear on every page in a Remix application is by including it in your root layout file, typically `app/root.tsx` (or `app/root.jsx`).+Remix renders the whole HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file and reaches every route.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet. It will look like this:+### Get your tracking snippet-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Remember to replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Add the Snippet to `app/root.tsx`+### Add the snippet to Remix-Open your `app/root.tsx` (or `app/root.jsx`) file. This file defines the root HTML structure for your application. Add the Rybbit tracking snippet within the `<head>` section of the returned JSX.+Open `app/root.tsx` (or `app/root.jsx`) and add the tag inside `<head>`, after `<Meta />` and `<Links />`:-```tsx filename="app/root.tsx"-import {- Links,- Meta,- Outlet,- Scripts,- ScrollRestoration,-} from "@remix-run/react";+```tsx title="app/root.tsx"+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";export default function App() {- const rybbitSiteId = "YOUR_SITE_ID"; // Replace with your actual Site ID-return (<html lang="en"><head>@@ -53,12 +32,7 @@ export default function App() {<meta name="viewport" content="width=device-width, initial-scale=1" /><Meta /><Links />- {/* Rybbit Tracking Snippet */}- <script- src="https://app.rybbit.io/api/script.js"- data-site-id={rybbitSiteId}- defer- ></script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script></head><body><Outlet />@@ -69,42 +43,37 @@ export default function App() {);}```-Make sure to replace `YOUR_SITE_ID` with your actual Site ID. You can define it as a constant or directly in the script tag.++Restart the dev server after the change. Client-side navigation after the initial server render is tracked automatically as pageviews.</Step><Step>-### Verify Installation+### Verify installation-After restarting your Remix development server or deploying your application, open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded.+<include>../../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **SPA Page View Tracking**: Rybbit's tracking script is designed to automatically detect route changes in most modern SPAs. Remix handles client-side navigation after the initial server render. If you find that page views are not being tracked correctly after client-side navigations (which can sometimes happen depending on the specifics of the script's SPA detection), you might need to manually trigger page views.-- One way to do this in Remix is to leverage a component that re-renders on navigation, or potentially by creating a custom `useLocationChange` hook if more granular control is needed, though this is often more complex. A simpler approach if manual tracking is needed might involve a root-level effect that listens to location changes. However, **test the default behavior first**, as manual tracking might not be necessary.- If manual tracking is required, you would call `window.rybbit.pageview()` after a route change.-</Callout>+## Track custom events-## Custom Event Tracking+Call `window.rybbit.event()` from any route or component. Check for `window` first, because Remix renders components on the server.-Once the Rybbit script is installed and loaded, you can track custom events from any of your Remix route components or other React components within your Remix app:--```tsx-// Example in a Remix route component-export default function MyFeatureRoute() {- const handleButtonClick = () => {+```tsx title="app/routes/offer.tsx"+export default function OfferRoute() {+ const handleClick = () => {if (typeof window !== "undefined" && window.rybbit) {- window.rybbit.event('remix_feature_click', { feature: 'Special Offer' });+ window.rybbit.event("offer_claimed", { feature: "Special Offer" });}};- return (- <div>- <h1>My Awesome Feature</h1>- <button onClick={handleButtonClick}>Claim Offer</button>- </div>- );+ return <button onClick={handleClick}>Claim Offer</button>;}```-Always check `typeof window !== "undefined"` before accessing `window.rybbit` because Remix components can render on the server. Then, ensure `window.rybbit` itself is available.++## 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.++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/react/tanstack-start.mdx b/docs/content/docs/(docs)/guides/react/tanstack-start.mdxnew file mode 100644index 000000000..6bb6c80fa--- /dev/null+++ b/docs/content/docs/(docs)/guides/react/tanstack-start.mdx@@ -0,0 +1,102 @@+---+title: TanStack Start+description: Add Rybbit analytics to your TanStack Start app+category: frameworks+icon: SiTanstack+---++import { Steps, Step } from "fumadocs-ui/components/steps";++TanStack Start manages the document head through the root route's `head()` option, rendered by `<HeadContent />` in `src/routes/__root.tsx`. Add the snippet to the `scripts` array returned by `head()` and it is on every route.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to TanStack Start++Open `src/routes/__root.tsx` and add a `scripts` entry to the object returned by `head()`. `<HeadContent />` in the root document renders it as a `<script>` tag inside `<head>`:++```tsx title="src/routes/__root.tsx"+import type { ReactNode } from "react";+import { Outlet, createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";++export const Route = createRootRoute({+ head: () => ({+ meta: [+ { charSet: "utf-8" },+ { name: "viewport", content: "width=device-width, initial-scale=1" },+ { title: "My App" },+ ],+ scripts: [+ {+ src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",+ defer: true,+ },+ ],+ }),+ component: RootComponent,+});++function RootComponent() {+ return (+ <RootDocument>+ <Outlet />+ </RootDocument>+ );+}++function RootDocument({ children }: Readonly<{ children: ReactNode }>) {+ return (+ <html>+ <head>+ <HeadContent />+ </head>+ <body>+ {children}+ <Scripts />+ </body>+ </html>+ );+}+```++Use the `scripts` key inside `head()`, not the route-level `scripts` option: that one renders body scripts through `<Scripts />`, which also works but loads later. Client-side navigation through `<Link>` and `useNavigate()` is tracked automatically as pageviews.+</Step>++<Step>+### Verify installation++<include>../../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `window.rybbit.event()` from any route component. Check for `window` first, because TanStack Start renders routes on the server by default.++```tsx title="src/routes/pricing.tsx"+import { createFileRoute } from "@tanstack/react-router";++export const Route = createFileRoute("/pricing")({+ component: Pricing,+});++function Pricing() {+ const handleClick = () => {+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.event("plan_selected", { plan: "pro" });+ }+ };++ return <button onClick={handleClick}>Choose Pro</button>;+}+```++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/react/vite-cra.mdx b/docs/content/docs/(docs)/guides/react/vite-cra.mdxindex af5d94bff..49c0c2769 100644--- a/docs/content/docs/(docs)/guides/react/vite-cra.mdx+++ b/docs/content/docs/(docs)/guides/react/vite-cra.mdx@@ -1,100 +1,75 @@---title: React (Vite / CRA)-description: Integrate Rybbit with your client-side React application+description: Add Rybbit analytics to your React app+category: frameworks+icon: SiReact----import { Steps, Step } from 'fumadocs-ui/components/steps'-import { Callout } from 'fumadocs-ui/components/callout'+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your client-side React application, such as those created with Create React App (CRA) or Vite.--## How to Add Rybbit to Your React App--The recommended and simplest method to add the Rybbit tracking script is directly in your `index.html` file. This ensures the script is loaded early and reliably.--### Adding to `public/index.html` (or `index.html` for Vite)--This is the most straightforward method and ensures the script is loaded early.+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.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet. It will look like this:+### Get your tracking snippet-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Remember to replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Locate Your `index.html` File+### Add the snippet to React-- For **Create React App (CRA)**: This file is typically located at `public/index.html`.-- For **Vite (React template)**: This file is typically located at the root of your project as `index.html`.-</Step>+Find the HTML entry file for your tooling:-<Step>-### Add the Snippet to `index.html`+- **Vite**: `index.html` at the project root.+- **Create React App**: `public/index.html`.-Open your `index.html` file and paste the Rybbit tracking snippet just before the closing `</head>` tag or `</body>` tag. Placing it in the `<head>` allows it to load sooner.+Paste the snippet just before `</head>`:-```html filename="public/index.html (CRA) or index.html (Vite)"-<!DOCTYPE html>+```html title="index.html"+<!doctype html><html lang="en"><head><meta charset="utf-8" />- <link rel="icon" href="%PUBLIC_URL%/favicon.ico" /> <!-- Example for CRA -->- <!-- Other meta tags and links --><title>My React App</title>- <!-- Rybbit Tracking Snippet -->- <script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer- ></script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script></head><body>- <noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div>- <!-- If you prefer, you can also place the script here, before </body> --></body></html>```-Make sure to replace `YOUR_SITE_ID` with your actual Site ID.++Placing it before `</body>` also works; `<head>` lets it start loading sooner. Route changes made by React Router and similar libraries are tracked automatically as pageviews.</Step><Step>-### Verify Installation+### Verify installation-After deploying your application, open your Rybbit dashboard to see if data is being received. You can also check your browser's network tab to ensure `script.js` is loaded.+<include>../../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **SPA Page View Tracking**: Rybbit's tracking script is designed to automatically detect route changes in most modern SPAs (including those using React Router or similar libraries) and track them as page views. If you find that page views are not being tracked correctly after navigation, you might need to manually trigger page views using `window.rybbit.pageview()` after each route change. However, try the standard installation first.-</Callout>--## Custom Event Tracking+## Track custom events-Once the script is installed, you can track custom events from any of your React components:+Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw.-```jsx-function MyComponent() {- const handleButtonClick = () => {+```jsx title="src/components/LearnMoreButton.jsx"+export default function LearnMoreButton() {+ const handleClick = () => {if (window.rybbit) {- window.rybbit.event('button_click', { category: 'CTA', label: 'Learn More' });+ window.rybbit.event("button_click", { category: "CTA", label: "Learn More" });}};- return <button onClick={handleButtonClick}>Learn More</button>;+ return <button onClick={handleClick}>Learn More</button>;}```-Ensure `window.rybbit` is available before calling its methods, especially if you load the script dynamically or have strict Content Security Policies.+## Troubleshooting++- **Pageviews missing after navigation**: this is rare with React Router. If it happens, call `window.rybbit.pageview()` after each route change; test the default behaviour first.++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/replit.mdx b/docs/content/docs/(docs)/guides/replit.mdxnew file mode 100644index 000000000..dc11574ce--- /dev/null+++ b/docs/content/docs/(docs)/guides/replit.mdx@@ -0,0 +1,72 @@+---+title: Replit+description: Add Rybbit analytics to your Replit app+category: ai-builders+icon: SiReplit+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Replit has no publishing setting for custom head code, so the snippet goes into the app's HTML entry file: ask Agent to add it, or open the file in the workspace and paste it yourself. The change reaches the live URL only after you republish.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Replit++<Tabs items={["Ask Agent", "Edit the code"]}>+<Tab>+Paste this into the Agent chat, with your snippet in place of the placeholder:++```text+Add this script tag to the <head> of the app's HTML entry file so it loads on every page. Keep all existing head tags.+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+```++Review the change before you approve it: the tag belongs in the HTML document, not in a React component or server file.+</Tab>++<Tab>+Open the file that owns the `<head>` from the **Files** pane of the workspace:++- Agent-built web apps are typically a Vite + React client with an Express server, and the HTML entry is `client/index.html`. Some projects keep it at `index.html` in the project root.+- Next.js projects use `app/layout.tsx` with `next/script`, as in the [Next.js guide](/docs/guides/react/next-js).+- Plain HTML projects (Static deployments): add the tag to every page, or to the shared template if you have one.++Paste the snippet before `</head>`:++```html title="client/index.html"+<head>+ <meta charset="UTF-8" />+ <title>My app</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+```+</Tab>+</Tabs>++Then click **Publish** in the upper right (or **Republish** for an app that is already live) so a new release goes out at the same URL. In-app route changes are tracked as pageviews automatically.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Live app has no script**: changes in the Project Editor do not replace the live release on their own. Test in Preview, then click **Republish**.+- **Agent rewrote the file**: a later request can regenerate `client/index.html`. Tell Agent to keep the Rybbit script when you ask for layout changes, and re-check the page source after large refactors.+- **Numbers differ from Replit's deployment analytics**: Replit counts requests at the server; Rybbit counts browser pageviews after ad blockers and bot filtering, so the two rarely match exactly.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/sanity.mdx b/docs/content/docs/(docs)/guides/sanity.mdxindex f55a4e3f8..07f453ea3 100644--- a/docs/content/docs/(docs)/guides/sanity.mdx+++ b/docs/content/docs/(docs)/guides/sanity.mdx@@ -1,78 +1,60 @@---title: Sanity-description: Integrate Rybbit Analytics with your Sanity-powered website+description: Add Rybbit analytics to your Sanity site+category: cms+icon: SiSanity----import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-Sanity is a headless CMS that provides content management for your applications. Since Sanity is headless, you'll add Rybbit Analytics to your frontend application rather than to Sanity itself.+Sanity is a headless CMS: your frontend queries content from the Content Lake and Sanity Studio is only the editing app. The tracking snippet therefore goes into the frontend that renders your site, not into Sanity.-<Callout type="info">-Sanity only manages your content - it doesn't serve your website directly. The tracking script goes in your frontend framework (Next.js, Gatsby, Nuxt, etc.).-</Callout>--## How to Add Rybbit with Sanity--Choose the guide that matches your frontend framework:--### React-based Frontends-- **[Next.js](/docs/guides/react/next-js)** - Most common choice with Sanity-- **[Gatsby](/docs/guides/react/gatsby)** - Popular for static sites-- **[Remix](/docs/guides/react/remix)**-- **[Vite + React](/docs/guides/react/vite-cra)**--### Vue-based Frontends-- **[Nuxt](/docs/guides/vue/nuxt)**-- **[Vite + Vue](/docs/guides/vue/vite)**--### Other Frontends-- **[Astro](/docs/guides/astro)** - Great for content-heavy sites-- **[SvelteKit](/docs/guides/svelte/sveltekit)**--## Quick Example: Next.js with Sanity+<Steps>+<Step>+### Get your tracking snippet-If you're using Next.js (the most common Sanity frontend), add the tracking script to your root layout:+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-```tsx-// app/layout.tsx-import Script from 'next/script'+<Step>+### Add the snippet to Sanity-export default function RootLayout({- children,-}: {- children: React.ReactNode-}) {- return (- <html lang="en">- <head>- <Script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- strategy="afterInteractive"- />- </head>- <body>{children}</body>- </html>- )-}-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.--## Sanity Studio--If you want to track usage of Sanity Studio itself (your content editing interface), you can add the script to your studio's root:--```tsx-// sanity.config.ts-import { defineConfig } from 'sanity'--export default defineConfig({- // ... your config- document: {- // Add custom studio plugins if needed- }-})-```+<Callout type="info">+Sanity has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Sanity.+</Callout>-However, most users only want to track their public-facing website, not their internal Studio usage.+<Tabs items={["Next.js", "Nuxt", "Other frontends"]}>+<Tab>+Next.js is the most common Sanity frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).+</Tab>+<Tab>+Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).+</Tab>+<Tab>+- [Gatsby](/docs/guides/react/gatsby)+- [Remix](/docs/guides/react/remix)+- [Vite + React](/docs/guides/react/vite-cra)+- [Vite + Vue](/docs/guides/vue/vite)+- [Astro](/docs/guides/astro)+- [SvelteKit](/docs/guides/svelte/sveltekit)+</Tab>+</Tabs>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Embedded Studio pageviews**: if Sanity Studio is mounted inside your frontend (for example at `/studio` in a Next.js app), the snippet in your root layout also runs there. Add `data-skip-patterns='["/studio/**"]'` to the script tag so editor sessions are not counted as visits.+- **Hosted Studio is not tracked**: a Studio deployed to `*.sanity.studio` is a separate app without the snippet, so time spent editing never appears in Rybbit.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/shopify-hydrogen.mdx b/docs/content/docs/(docs)/guides/shopify-hydrogen.mdxnew file mode 100644index 000000000..063f2e276--- /dev/null+++ b/docs/content/docs/(docs)/guides/shopify-hydrogen.mdx@@ -0,0 +1,132 @@+---+title: Shopify Hydrogen+description: Add Rybbit analytics to your Shopify Hydrogen storefront+category: ecommerce+icon: SiShopify+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Hydrogen storefronts render the HTML document from `app/root.tsx`, so the snippet goes in the `<head>` of that file's `Layout` component, and the tracker's host is added to the Content Security Policy that `app/entry.server.tsx` builds. This guide is for headless Hydrogen storefronts; for an Online Store theme, see the [Shopify guide](/docs/guides/shopify).++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Shopify Hydrogen++Hydrogen ships with a nonce-based CSP, so a plain `<script>` tag without the nonce is blocked. Use Hydrogen's `Script` component, which adds the nonce for you.++1. Open `app/root.tsx` and add the tag inside `<head>` of the `Layout` component:++```tsx title="app/root.tsx"+import { Analytics, getShopAnalytics, Script, useNonce } from "@shopify/hydrogen";++export function Layout({children}: {children?: React.ReactNode}) {+ const nonce = useNonce();++ return (+ <html lang="en">+ <head>+ <meta charSet="utf-8" />+ <meta name="viewport" content="width=device-width,initial-scale=1" />+ <Meta />+ <Links />+ <Script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer />+ </head>+ <body>+ {children}+ <ScrollRestoration nonce={nonce} />+ <Scripts nonce={nonce} />+ </body>+ </html>+ );+}+```++2. Open `app/entry.server.tsx` and allow the tracker's host in the CSP. Values you pass for `connectSrc` are merged with Hydrogen's defaults, but `scriptSrc` has no default to merge with (it falls back to `default-src`), so list Shopify's CDN alongside Rybbit:++```tsx title="app/entry.server.tsx"+const {nonce, header, NonceProvider} = createContentSecurityPolicy({+ shop: {+ checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,+ storeDomain: context.env.PUBLIC_STORE_DOMAIN,+ },+ scriptSrc: ["'self'", "https://cdn.shopify.com", "https://app.rybbit.io"],+ connectSrc: ["https://app.rybbit.io"],+});+```++`connect-src` lets the tracker post events; `script-src` is needed because features such as session replay load a second script from the same host at runtime. If you self-host Rybbit, use your instance's domain.++Restart the dev server. Client-side navigation between routes is tracked automatically as pageviews. Projects created before Hydrogen moved to React Router import `Meta`, `Links` and `Scripts` from `@remix-run/react`; the edit is the same.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Hydrogen's `Analytics.Provider` already publishes storefront events (`product_viewed`, `product_added_to_cart`, `cart_updated` and others), so subscribe to them once in a small component instead of instrumenting each route.++```tsx title="app/components/RybbitAnalytics.tsx"+import { useAnalytics } from "@shopify/hydrogen";+import { useEffect } from "react";++export function RybbitAnalytics() {+ const {subscribe, register} = useAnalytics();+ const {ready} = register("Rybbit");++ useEffect(() => {+ subscribe("product_viewed", (data) => {+ const product = data.products[0];+ if (!product) return;+ window.rybbit?.event("view_item", {+ item_id: product.sku || product.variantId,+ item_name: product.title,+ item_variant: product.variantTitle,+ price: Number(product.price),+ });+ });+ subscribe("product_added_to_cart", (data) => {+ const line = data.currentLine;+ if (!line) return;+ window.rybbit?.event("add_to_cart", {+ item_id: line.merchandise.sku || line.merchandise.id,+ item_name: line.merchandise.product.title,+ price: Number(line.cost.totalAmount.amount),+ currency: line.cost.totalAmount.currencyCode,+ quantity: line.quantity,+ });+ });+ ready();+ }, []);++ return null;+}+```++Render `<RybbitAnalytics />` inside `<Analytics.Provider>` in the `App` component of `app/root.tsx`. Declare `window.rybbit` with the type from [Track events](/docs/track-events#typescript-support) so TypeScript accepts the calls. Skip `page_viewed`: the tracker records route changes itself.++<Callout type="info">+Checkout does not run in Hydrogen. Track purchases with the custom web pixel from the [Shopify guide](/docs/guides/shopify#purchase), which works for Hydrogen and Online Store checkouts alike.+</Callout>++## Troubleshooting++- **`Refused to load the script` in the console**: the CSP change in `entry.server.tsx` is missing or the dev server was not restarted. The nonce alone is not enough once session replay loads its second script.+- **`POST /api/track` blocked**: `connectSrc` does not include the tracker's host. Self-hosted instances need their own domain here.+- **Early events dropped**: on a cold load a subscription can fire before the deferred script runs. The optional chaining above skips those; wrap the calls in `window.rybbit.onReady()` if you need every one.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/shopify.mdx b/docs/content/docs/(docs)/guides/shopify.mdxindex 69d9ab98d..a30a37b81 100644--- a/docs/content/docs/(docs)/guides/shopify.mdx+++ b/docs/content/docs/(docs)/guides/shopify.mdx@@ -1,214 +1,129 @@----title: "Shopify"-description: "Integrate Rybbit with your Shopify store to capture events, track conversions, and analyze user behavior."+title: Shopify+description: Add Rybbit analytics to your Shopify store+category: ecommerce+icon: SiShopify----import { Step, Steps } from "fumadocs-ui/components/steps";+import { Steps, Step } from "fumadocs-ui/components/steps";import { Callout } from "fumadocs-ui/components/callout";-# Shopify+On Shopify the snippet goes into your theme's `theme.liquid` layout, which wraps every storefront page. Checkout runs on Shopify's own sandboxed pages, so purchases are tracked separately through a custom web pixel.-Rybbit can be integrated with your Shopify store to capture events, track conversions, and analyze user behavior.+<Steps>+<Step>+### Get your tracking snippet-## How to Add Rybbit to Shopify+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-<Steps><Step>-### Retrieve Your Tracking Script+### Add the snippet to Shopify-Navigate to your Rybbit dashboard to obtain your code snippet.+1. In Shopify admin, go to **Online Store > Themes**.+2. On your current theme, click the **...** button next to **Customize** and choose **Edit code**.+3. Open `theme.liquid` in the **Layout** folder.+4. Paste the snippet just before the closing `</head>` tag and click **Save**.-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```+Theme updates can overwrite `theme.liquid`. Shopify has no child-theme system, so after updating a purchased theme, re-add the snippet.</Step><Step>-### Add the Snippet to Your Shopify Store--- In Shopify, go to **Online Store > Themes**.-- Find your current theme, click the **three dots (...)** button next to **Customize**, and select **Edit code**.-- Open `theme.liquid` in the **Layout** folder.-- Just before the closing `</head>` tag, insert your snippet.-- Save the file to apply the changes to your live store.+### Verify installation-**Note:** If you are editing a theme you purchased or one that receives updates, be aware that theme updates might overwrite your changes, requiring you to re-add the snippet. While Shopify doesn't have a formal "child theme" system like WordPress, some developers use theme duplication or version control as a workaround. For most users, re-adding the snippet after an update is the simplest approach if this occurs.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-## Tracking E-commerce Events+## Track custom events-To get the most out of Rybbit with Shopify, you should track key e-commerce events. This typically involves adding small Liquid and JavaScript snippets to your theme files.+Storefront templates can call `window.rybbit.event()` directly. Wrap the calls in a `DOMContentLoaded` listener because the tracking script is loaded with `defer`, and divide Liquid prices by 100 because they are in cents.<Callout type="warn">- Always back up your theme before making code changes. If you are not comfortable editing theme code, consider hiring a Shopify expert. The following snippets are examples and might need adjustments based on your specific theme structure and Shopify version.+Back up your theme before editing code. Liquid object names such as `product.selected_or_first_available_variant` and the form selectors below vary between themes, so adjust them to match yours.</Callout>-### 1. View Product (`view_item`)--Track when a user views a single product page.+#### View product-**Edit `product.liquid` (or your theme's main product template file, often found in `templates/product.liquid` or `sections/main-product.liquid` or similar):**--Add the following script towards the end of the file, or within a relevant product information block:+Add to your main product template (`sections/main-product.liquid` or `templates/product.liquid`, depending on the theme):```liquid-{% raw %}{% comment %} Add to product.liquid or main product section {% endcomment %}-<script type="text/javascript">- if (typeof window.rybbit !== 'undefined' && {{ product | json }}) {- const rybbitProduct = {{ product | json }};- const rybbitCurrentVariant = {{ product.selected_or_first_available_variant | json }};-- window.rybbit.event('view_item', {- item_id: rybbitCurrentVariant.sku || rybbitCurrentVariant.id,- item_name: rybbitProduct.title,- item_variant: rybbitCurrentVariant.title === 'Default Title' ? null : rybbitCurrentVariant.title,- price: parseFloat(rybbitCurrentVariant.price) / 100, // Price is in cents- currency: {{ cart.currency.iso_code | json }}- });- }-</script>{% endraw %}+<script>+document.addEventListener('DOMContentLoaded', function () {+ var variant = {{ product.selected_or_first_available_variant | json }};+ 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,+ price: variant.price / 100,+ currency: {{ cart.currency.iso_code | json }}+ });+});+</script>```-### 2. Add to Cart (`add_to_cart`)+#### Add to cart-Tracking "add to cart" events can be complex due to themes using AJAX for cart updates. Here's a common approach by attaching an event listener to your "Add to Cart" button.--**Identify your "Add to Cart" button/form in `product.liquid` or your product form section.**--You'll need to add a script that listens for clicks or form submissions. This example assumes your "Add to Cart" button has an ID like `add-to-cart-button` or is part of a form with a specific class or ID. You may need to adjust the selector.+In the same template, listen on the product form. Themes with an AJAX cart drawer usually fire their own JavaScript event after an item is added; hooking that is more reliable than the form submit.```liquid-{% raw %}{% comment %} Add near your product form or Add to Cart button in product.liquid/product form section {% endcomment %}-<script type="text/javascript">-document.addEventListener('DOMContentLoaded', function() {- const addToCartForm = document.querySelector('form[action="/cart/add"]'); // Common selector for product forms- const addToCartButton = document.getElementById('add-to-cart-button') || addToCartForm?.querySelector('[type="submit"]');-- const trackAddToCart = function() {- if (typeof window.rybbit !== 'undefined' && {{ product | json }}) {- const rybbitProduct = {{ product | json }};- const rybbitCurrentVariant = {{ product.selected_or_first_available_variant | json }};- let quantity = 1;- const quantityInput = addToCartForm?.querySelector('[name="quantity"], input[type="number"]'); // Common quantity input selectors- if (quantityInput && quantityInput.value) {- quantity = parseInt(quantityInput.value, 10);- }-- window.rybbit.event('add_to_cart', {- item_id: rybbitCurrentVariant.sku || rybbitCurrentVariant.id,- item_name: rybbitProduct.title,- item_variant: rybbitCurrentVariant.title === 'Default Title' ? null : rybbitCurrentVariant.title,- price: parseFloat(rybbitCurrentVariant.price) / 100,- currency: {{ cart.currency.iso_code | json }},- quantity: quantity > 0 ? quantity : 1- });- }- };-- if (addToCartButton) {- addToCartButton.addEventListener('click', function(event) {- // Delay slightly to allow form submission/validation if needed, or track on form submit- // For themes with AJAX add to cart, this might need to hook into the theme's specific JS events.- setTimeout(trackAddToCart, 100); // Basic click tracking+<script>+document.addEventListener('DOMContentLoaded', function () {+ var form = document.querySelector('form[action="/cart/add"]');+ if (!form) return;+ 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', {+ item_id: variant.sku || variant.id,+ item_name: {{ product.title | json }},+ price: variant.price / 100,+ currency: {{ cart.currency.iso_code | json }},+ quantity: qty && parseInt(qty.value, 10) > 0 ? parseInt(qty.value, 10) : 1});- } else if (addToCartForm) {- addToCartForm.addEventListener('submit', function(event) {- trackAddToCart(); // Track on form submission- });- }+ });});-</script>{% endraw %}+</script>```-<Callout type="info">- For themes with AJAX "Add to Cart" functionality (where the page doesn't reload), you might need to listen for custom JavaScript events fired by your theme after an item is successfully added to the cart, or observe changes to the cart. This can be theme-specific.-</Callout>--### 3. Begin Checkout (`begin_checkout`)--Shopify's checkout process is on a separate domain (`checkout.shopify.com`), and direct script injection into the checkout pages (beyond the "Order status" page) is limited for most plans. However, Rybbit's script, if loaded on your main store, should persist session information.--A common way to track "begin_checkout" is by tracking clicks on checkout buttons.-**Edit `cart.liquid` (or your theme's main cart template, often `templates/cart.liquid` or `sections/main-cart-items.liquid`):**+#### Begin checkout-Find your "Checkout" button and add an ID to it if it doesn't have one (e.g., `id="checkout-button"`). Then add this script:+Add to your cart template (`sections/main-cart-items.liquid` or `templates/cart.liquid`) to track clicks on the checkout button:```liquid-{% raw %}{% comment %} Add to cart.liquid, near the checkout button logic {% endcomment %}-<script type="text/javascript">-document.addEventListener('DOMContentLoaded', function() {- const checkoutButton = document.getElementById('checkout-button') || document.querySelector('[name="checkout"], form[action$="/checkout"] [type="submit"]'); // Common selectors-- if (checkoutButton && typeof window.rybbit !== 'undefined' && {{ cart | json }}) {- checkoutButton.addEventListener('click', function() {- const rybbitCart = {{ cart | json }};- let items = [];- rybbitCart.items.forEach(function(item) {- items.push({- item_id: item.sku || item.variant_id,- item_name: item.product_title,- item_variant: item.variant_title === 'Default Title' ? null : item.variant_title,- price: parseFloat(item.final_price) / 100,- quantity: item.quantity- });- });-- window.rybbit.event('begin_checkout', {- currency: rybbitCart.currency,- value: parseFloat(rybbitCart.total_price) / 100,- items: items- });+<script>+document.addEventListener('DOMContentLoaded', function () {+ var button = document.querySelector('[name="checkout"]');+ if (!button) return;+ button.addEventListener('click', function () {+ var cart = {{ cart | json }};+ window.rybbit.event('begin_checkout', {+ currency: cart.currency,+ value: cart.total_price / 100,+ items: cart.items.map(function (item) {+ return { item_id: item.sku || item.variant_id, quantity: item.quantity, price: item.final_price / 100 };+ })});- }+ });});-</script>{% endraw %}+</script>```-<Callout type="warn">- Rybbit limits an event's `properties` to **2048 characters** once serialized to- JSON, and events that exceed the limit are rejected (not truncated). A full- per-item `items` array can blow past this on large carts. For carts with many- line items, send a compact payload β trimmed item fields (e.g. id, quantity,- price only) or just the aggregate `value`, `currency`, and `transaction_id`.-</Callout>--### 4. Purchase (`purchase`)--Track completed purchases on the Shopify "Thank You" / order status page.+Event properties are limited to 2048 characters of serialised JSON and larger payloads are rejected, not truncated. Keep `items` compact, or send only the totals for large carts.-<Callout type="warn">- The old **Order status page > Additional scripts** field has been deprecated. As- of August 28, 2025 it is view-only (Shopify Plus migration deadline), non-Plus- stores must migrate by August 26, 2026, and automatic upgrades that began in- January 2026 remove any remaining `checkout.liquid` / Additional-scripts- customizations. The supported path for tracking purchases is now- [Checkout Extensibility](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations)- via a **custom web pixel**.-</Callout>+#### Purchase-Custom web pixels run in a sandboxed environment, so they **cannot access-`window.rybbit`** on the storefront. Instead, subscribe to the standard-`checkout_completed` event and send the purchase directly to Rybbit's tracking-endpoint with `fetch`.+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.-**1. Create a custom pixel:**-- In your Shopify Admin, go to **Settings > Customer events**.-- Click **Add custom pixel**, give it a name (e.g. `Rybbit`), and click **Add pixel**.+Pixels run in a sandbox with no access to `window.rybbit`, so the pixel posts the event straight to Rybbit's track endpoint.-**2. Add the pixel code:**-- Paste the following into the code editor, replacing `YOUR_SITE_ID` with your Site ID, then **Save** and **Connect** the pixel.+1. In Shopify admin, go to **Settings > Customer events**.+2. Click **Add custom pixel**, name it `Rybbit`, and click **Add pixel**.+3. Paste the code below, replace `YOUR_SITE_ID`, then **Save** and **Connect** the pixel.```javascriptanalytics.subscribe("checkout_completed", (event) => {const checkout = event.data.checkout;-- // Keep the payload small β Rybbit rejects event properties over 2048 chars- // (serialized JSON). Send compact per-item data for large carts.const items = (checkout.lineItems || []).map((li) => ({id: li.variant?.sku || li.variant?.id,qty: li.quantity,@@ -223,29 +138,20 @@ analytics.subscribe("checkout_completed", (event) => {type: "custom_event",site_id: "YOUR_SITE_ID",event_name: "purchase",- // `properties` must be a JSON string (max 2048 chars).+ // properties must be a JSON string of at most 2048 charactersproperties: JSON.stringify({transaction_id: checkout.order?.id || checkout.token,value: checkout.totalPrice?.amount,currency: checkout.currencyCode,- items: items,+ items,}),}),});});```-**Explanation:**-- `analytics.subscribe("checkout_completed", ...)` fires once when an order is- successfully placed, so purchases are tracked without editing `checkout.liquid`.-- The pixel POSTs a `custom_event` straight to Rybbit's `/api/track` endpoint- because the sandbox has no access to the storefront's `window.rybbit`.-- `properties` is sent as a JSON **string** and must stay under 2048 characters β- see the note above about trimming large carts.--## Important Considerations-* **Theme Differences**: Shopify themes can vary significantly. You may need to adjust Liquid object paths (e.g., `product.selected_or_first_available_variant` vs. `current_variant`) and JavaScript selectors based on your specific theme's structure.-* **Currency Conversion**: Prices in Shopify Liquid objects are often in cents. Ensure you divide by 100 to get the decimal value for Rybbit.-* **AJAX Carts**: If your theme uses an AJAX cart (drawer or pop-up cart that updates without page reload), tracking `add_to_cart` accurately requires hooking into your theme's specific JavaScript events or using MutationObserver to detect cart changes. The provided `add_to_cart` example is a basic starting point.-* **Shopify Customer Events**: For more robust server-side or client-side event tracking, especially for `add_to_cart` and `begin_checkout` without relying on DOM manipulation, explore [Shopify Customer Events](https://shopify.dev/docs/api/customer-events). This allows you to subscribe to events like "product added to cart" or "checkout started" and send data to Rybbit via a custom pixel or by triggering client-side JavaScript. This is a more advanced but often more reliable method.-* **Testing**: Thoroughly test each event in your Rybbit dashboard after implementation. Use your browser's developer console to check for JavaScript errors.\ No newline at end of file+`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.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/solid.mdx b/docs/content/docs/(docs)/guides/solid.mdxnew file mode 100644index 000000000..10a001ebc--- /dev/null+++ b/docs/content/docs/(docs)/guides/solid.mdx@@ -0,0 +1,103 @@+---+title: SolidJS+description: Add Rybbit analytics to your SolidJS app+category: frameworks+icon: SiSolid+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++A client-side Solid app built with Vite has a single `index.html` at the project root; a SolidStart app renders its document from `src/entry-server.tsx`. Paste the snippet into the `<head>` of whichever file your project has and it loads on every route.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to SolidJS++<Tabs items={["Vite", "SolidStart"]}>+<Tab value="Vite">+Open `index.html` at the root of the project (the file `npm create solid@latest` generates for the vanilla templates) and paste the snippet inside `<head>`:++```html title="index.html"+<!DOCTYPE html>+<html lang="en">+ <head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <title>Solid App</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ </head>+ <body>+ <div id="root"></div>+ <script src="/src/index.tsx" type="module"></script>+ </body>+</html>+```+</Tab>+<Tab value="SolidStart">+SolidStart has no `index.html`. The `<html>` document is the `document` prop of `<StartServer>` in `src/entry-server.tsx`; `src/app.tsx` only renders the router inside it. Add the tag to `<head>` next to `{assets}`:++```tsx title="src/entry-server.tsx"+// @refresh reload+import { createHandler, StartServer } from "@solidjs/start/server";++export default createHandler(() => (+ <StartServer+ document={({ assets, children, scripts }) => (+ <html lang="en">+ <head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <link rel="icon" href="/favicon.ico" />+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ {assets}+ </head>+ <body>+ <div id="app">{children}</div>+ {scripts}+ </body>+ </html>+ )}+ />+));+```++Restart the dev server after the change.+</Tab>+</Tabs>++Route changes made by `@solidjs/router` (including SolidStart's file routes) are tracked automatically as pageviews.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `window.rybbit.event()` from any component. Guard the call so a blocked or still-loading script does not throw; in SolidStart the guard also covers server rendering.++```tsx title="src/components/SignupButton.tsx"+export default function SignupButton() {+ const handleClick = () => {+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.event("signup_click", { location: "hero" });+ }+ };++ return <button onClick={handleClick}>Sign up</button>;+}+```++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/squarespace.mdx b/docs/content/docs/(docs)/guides/squarespace.mdxindex 13061b099..3e9880c19 100644--- a/docs/content/docs/(docs)/guides/squarespace.mdx+++ b/docs/content/docs/(docs)/guides/squarespace.mdx@@ -1,74 +1,49 @@----title: "Squarespace"-description: "Integrate Rybbit Analytics with your Squarespace website using the Code Injection feature."+title: Squarespace+description: Add Rybbit analytics to your Squarespace site+category: builders+icon: SiSquarespace----import { Steps, Step } from 'fumadocs-ui/components/steps';+import { Steps, Step } from "fumadocs-ui/components/steps";import { Callout } from "fumadocs-ui/components/callout";-Integrating Rybbit Analytics with your Squarespace website is straightforward. You'll need to use Squarespace's "Code Injection" feature to add the Rybbit tracking script to your site.+Squarespace injects custom HTML into every page through its **Code Injection** panel, so no template edits are needed.-<Steps>-<Step>-### Get Your Tracking Script--First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Script**. It will look something like this:--```html-<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.-</Step>--<Step>-### Go to Squarespace Settings--Log in to your Squarespace account and go to the website you want to track.--From the main dashboard (Home Menu), navigate to:--- **Settings**-</Step>+<Callout type="warn">+Code Injection is available on the **Business** and **Commerce** plans. It is not available on the Personal plan.+</Callout>+<Steps><Step>-### Access Code Injection+### Get your tracking snippet-In the Settings panel, find and click on:--- **Website** (under the "GENERAL" section)-- Then, click on **Code Injection** (under the "ADVANCED" or "DEVELOPER" section, depending on your Squarespace version).--<Callout type="info">- The Code Injection feature is available on Squarespace Business and Commerce plans. It may not be available on Personal plans.-</Callout>+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Paste Your Tracking Script+### Add the snippet to Squarespace-In the Code Injection settings, you'll see several fields (Header, Footer, Lock Page, Order Confirmation Page).+1. From the Home Menu, open **Settings**.+2. Open **Website**, then **Code Injection** (listed under **Advanced** or **Developer** depending on your Squarespace version).+3. Paste the snippet into the **Header** field. The script is deferred, so it does not delay page rendering.+4. Click **Save** at the top of the panel.-For sitewide tracking, paste your Rybbit tracking script into the **Footer** text area. This ensures the script loads after your page content, which is generally better for perceived page load performance.--Alternatively, you can place it in the **Header**, which might track users who leave before the page fully loads, but could slightly impact initial page load speed. For most analytics purposes, the Footer is recommended.+The **Footer** field also works and loads the script on every page. Leave the **Lock Page** and **Order Confirmation Page** fields alone; they only apply to those single pages.</Step><Step>-### Save Changes+### Verify installation-After pasting the script, click the **Save** button at the top of the Code Injection panel.+<include>../../../partials/guides/verify.mdx</include></Step>+</Steps>-<Step>-### Verify Integration+## Troubleshooting-Once you've saved the changes, Rybbit Analytics should start tracking visitors on your Squarespace site.+- **Code Injection is missing from Settings**: the site is on the Personal plan. Upgrade to Business or Commerce.+- **Only the checkout is tracked**: the snippet was pasted into **Order Confirmation Page** instead of **Header** or **Footer**.-- Open your Squarespace website in a new browser tab or incognito window.-- Navigate through a few pages.-- Check your Rybbit dashboard for incoming data. It might take a few minutes for the first events to appear.-</Step>-</Steps>+## Next steps-That's it! Rybbit Analytics is now integrated with your Squarespace website.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/starlight.mdx b/docs/content/docs/(docs)/guides/starlight.mdxnew file mode 100644index 000000000..4e27347dc--- /dev/null+++ b/docs/content/docs/(docs)/guides/starlight.mdx@@ -0,0 +1,71 @@+---+title: Starlight+description: Add Rybbit analytics to your Starlight docs+category: docs+icon: SiAstro+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++Starlight, the documentation theme for Astro, has a `head` option in its integration config that adds tags to every page. The snippet goes there, in `astro.config.mjs`, so no component overrides are needed.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Starlight++Open `astro.config.mjs` at the root of your project and add a `script` entry to the `head` array of the `starlight()` integration:++```javascript title="astro.config.mjs"+import { defineConfig } from "astro/config";+import starlight from "@astrojs/starlight";++export default defineConfig({+ integrations: [+ starlight({+ title: "My Docs",+ head: [+ {+ tag: "script",+ attrs: {+ src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",+ defer: true,+ },+ },+ ],+ }),+ ],+});+```++Each `head` entry becomes an HTML element with the given attributes; `defer: true` renders as a boolean attribute. Rebuild with `npm run build` and deploy the `dist/` directory.++<Callout type="info">+Entries in `head` are written to the page as-is and skip Astro's script bundling, which is what you want for a remote tracker. Only override the `Head` component if you need to import a local asset.+</Callout>++Starlight serves each page as a full document, so every navigation is a normal pageview and no route-change handling is needed.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Local previews are tracked**: `head` applies to `astro dev` as well as `astro build`. Read the site ID from an environment variable that only your deploy sets (`process.env.RYBBIT_SITE_ID`) and push the entry only when it is present, or keep a separate site in Rybbit for development.+- **Tag missing after editing the config**: the dev server restarts itself when `astro.config.mjs` changes, but a deployed site needs a fresh build.+- **Head component override**: if your project already overrides Starlight's `Head` component, make sure it still renders the default head (the override docs show how), otherwise config `head` entries are dropped with it.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/statamic.mdx b/docs/content/docs/(docs)/guides/statamic.mdxnew file mode 100644index 000000000..321f5559b--- /dev/null+++ b/docs/content/docs/(docs)/guides/statamic.mdx@@ -0,0 +1,61 @@+---+title: Statamic+description: Add Rybbit analytics to your Statamic site+category: cms+icon: SiStatamic+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Statamic wraps every template in a layout, and a fresh install uses `resources/views/layout.antlers.html` by default. The snippet goes in that layout's `<head>`, so it loads on every page without touching individual templates.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Statamic++1. Open `resources/views/layout.antlers.html`.+2. Add the tag before `</head>`:++```html title="resources/views/layout.antlers.html"+<!doctype html>+<html lang="{{ site:short_locale }}">+<head>+ <meta charset="utf-8">+ <title>{{ title }} | {{ site:name }}</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+<body>+ {{ template_content }}+</body>+</html>+```++3. Save. Templates rendered through this layout (`{{ template_content }}`) now include the script.++If an entry or collection sets a different `layout` field, add the tag to that layout file too, or move it into a partial such as `resources/views/partials/rybbit.antlers.html` and `{{ partial:rybbit }}` it from each layout. If your views use Blade (`layout.blade.php`), the same tag goes in the same place.++To keep the site ID out of version control, put it in `.env` as `RYBBIT_SITE_ID` and use `{{ config:services:rybbit:site_id }}` after adding a `rybbit` entry to `config/services.php`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Static caching**: with `half` or `full` static caching enabled in `config/statamic/static_caching.php`, run `php please static:clear` after editing the layout, otherwise cached pages keep the old head.+- **Live Preview counts as visits**: the control panel's Live Preview renders your entry in an iframe at its real URL with a `token` query parameter. Editors' previews are tracked like any other visit, so check analytics from the live site rather than the control panel.+- **Control panel is not tracked**: `/cp` uses Statamic's own views, so the snippet never runs there.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/storyblok.mdx b/docs/content/docs/(docs)/guides/storyblok.mdxnew file mode 100644index 000000000..2184c3dbd--- /dev/null+++ b/docs/content/docs/(docs)/guides/storyblok.mdx@@ -0,0 +1,64 @@+---+title: Storyblok+description: Add Rybbit analytics to your Storyblok site+category: cms+icon: SiStoryblok+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Storyblok is a headless CMS: it stores content and delivers it through its APIs, while your frontend renders the pages. The tracking snippet therefore goes into the frontend's root layout, not into Storyblok.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Storyblok++<Callout type="info">+Storyblok has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Storyblok.+</Callout>++<Tabs items={["Next.js", "Nuxt", "Other frontends"]}>+<Tab>+Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).+</Tab>+<Tab>+Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).+</Tab>+<Tab>+- [Astro](/docs/guides/astro)+- [SvelteKit](/docs/guides/svelte/sveltekit)+- [Remix](/docs/guides/react/remix)+- [Gatsby](/docs/guides/react/gatsby)+- [Vite + React](/docs/guides/react/vite-cra)+- [Vite + Vue](/docs/guides/vue/vite)+- [Angular](/docs/guides/angular)+</Tab>+</Tabs>++The script tracks client-side route changes automatically, so navigation between stories in any of these frameworks is counted without extra code.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## 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.+- **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++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/strapi.mdx b/docs/content/docs/(docs)/guides/strapi.mdxindex c89e237e5..77fb306dd 100644--- a/docs/content/docs/(docs)/guides/strapi.mdx+++ b/docs/content/docs/(docs)/guides/strapi.mdx@@ -1,85 +1,60 @@---title: Strapi-description: Integrate Rybbit Analytics with your Strapi-powered website+description: Add Rybbit analytics to your Strapi site+category: cms+icon: SiStrapi----import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-Strapi is an open-source headless CMS that provides an API for your content. Since Strapi is headless, you'll add Rybbit Analytics to your frontend application rather than to Strapi itself.+Strapi is a headless CMS: it exposes your content over a REST or GraphQL API and does not render your website. The tracking snippet therefore goes into the frontend that consumes the Strapi API, not into Strapi.-<Callout type="info">-Strapi only serves your content via API - it doesn't render your website. The tracking script goes in your frontend framework (Next.js, Nuxt, Astro, etc.).-</Callout>--## How to Add Rybbit with Strapi--Choose the guide that matches your frontend framework:--### React-based Frontends-- **[Next.js](/docs/guides/react/next-js)** - Most common choice with Strapi-- **[Gatsby](/docs/guides/react/gatsby)**-- **[Remix](/docs/guides/react/remix)**-- **[Vite + React](/docs/guides/react/vite-cra)**--### Vue-based Frontends-- **[Nuxt](/docs/guides/vue/nuxt)** - Popular with Strapi-- **[Vite + Vue](/docs/guides/vue/vite)**--### Other Frontends-- **[Astro](/docs/guides/astro)**-- **[SvelteKit](/docs/guides/svelte/sveltekit)**-- **[Angular](/docs/guides/angular)**--## Quick Example: Next.js with Strapi+<Steps>+<Step>+### Get your tracking snippet-If you're using Next.js (a common Strapi frontend), add the tracking script to your root layout:+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-```tsx-// app/layout.tsx-import Script from 'next/script'+<Step>+### Add the snippet to Strapi-export default function RootLayout({- children,-}: {- children: React.ReactNode-}) {- return (- <html lang="en">- <head>- <Script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- strategy="afterInteractive"- />- </head>- <body>{children}</body>- </html>- )-}-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.--## Quick Example: Nuxt with Strapi--If you're using Nuxt, add to your `nuxt.config.ts`:--```typescript-export default defineNuxtConfig({- app: {- head: {- script: [- {- src: 'https://app.rybbit.io/api/script.js',- 'data-site-id': 'YOUR_SITE_ID',- defer: true- }- ]- }- }-})-```--## Strapi Admin Panel+<Callout type="info">+Strapi has no template or head setting to paste into. Add the snippet to the `<head>` of the frontend application that fetches content from Strapi.+</Callout>-The Strapi admin panel is typically only accessed by content editors and administrators. Most users don't need to track admin panel usage. If you do want to track it, you would need to customize the Strapi admin, which is an advanced configuration.+<Tabs items={["Next.js", "Nuxt", "Other frontends"]}>+<Tab>+Next.js is the most common Strapi frontend. Add the snippet with `next/script` in your root layout so it loads on every route. Follow the [Next.js guide](/docs/guides/react/next-js).+</Tab>+<Tab>+Nuxt is a popular Strapi frontend. Add the snippet under `app.head.script` in `nuxt.config.ts`. Follow the [Nuxt guide](/docs/guides/vue/nuxt).+</Tab>+<Tab>+- [Gatsby](/docs/guides/react/gatsby)+- [Remix](/docs/guides/react/remix)+- [Vite + React](/docs/guides/react/vite-cra)+- [Vite + Vue](/docs/guides/vue/vite)+- [Astro](/docs/guides/astro)+- [SvelteKit](/docs/guides/svelte/sveltekit)+- [Angular](/docs/guides/angular)+</Tab>+</Tabs>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **The admin panel is not tracked**: the Strapi admin at `/admin` is served by the Strapi server, not by your frontend, so it never loads the snippet. Content editors' activity does not appear in Rybbit, which is usually what you want.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/svelte/meta.json b/docs/content/docs/(docs)/guides/svelte/meta.jsonindex 291f1102d..29b215a30 100644--- a/docs/content/docs/(docs)/guides/svelte/meta.json+++ b/docs/content/docs/(docs)/guides/svelte/meta.json@@ -1,4 +1,7 @@{"title": "Svelte",- "pages": ["vite", "sveltekit"]+ "pages": [+ "sveltekit",+ "vite"+ ]}diff --git a/docs/content/docs/(docs)/guides/svelte/sveltekit.mdx b/docs/content/docs/(docs)/guides/svelte/sveltekit.mdxindex fd552835b..011609c75 100644--- a/docs/content/docs/(docs)/guides/svelte/sveltekit.mdx+++ b/docs/content/docs/(docs)/guides/svelte/sveltekit.mdx@@ -1,105 +1,84 @@---title: SvelteKit-description: Integrate Rybbit with your SvelteKit application for analytics tracking+description: Add Rybbit analytics to your SvelteKit app+category: frameworks+icon: SiSvelte----import { Steps, Step } from 'fumadocs-ui/components/steps'-import { Callout } from 'fumadocs-ui/components/callout'+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your SvelteKit application for analytics tracking.--## How to Add Rybbit to Your SvelteKit App--The recommended and most straightforward method for SvelteKit is to add the Rybbit tracking script directly to your `src/app.html` file. This ensures the script is loaded early on all pages.--### Adding to `src/app.html`+SvelteKit renders every page through a single HTML shell at `src/app.html`, so adding the snippet there loads Rybbit on every route.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet:+### Get your tracking snippet-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Locate Your `app.html` File+### Add the snippet to SvelteKit-In a SvelteKit project, this file is typically located at `src/app.html`.-</Step>--<Step>-### Add the Snippet to `app.html`+Open `src/app.html` and paste the snippet inside `<head>`, next to `%sveltekit.head%`:-Open `src/app.html` and paste the Rybbit tracking snippet into the `<head>` section, usually before `%sveltekit.head%` or just after it.--```html filename="src/app.html"+```html title="src/app.html"<!doctype html><html lang="en">- <head>- <meta charset="utf-8" />- <link rel="icon" href="%sveltekit.assets%/favicon.png" />- <meta name="viewport" content="width=device-width, initial-scale=1" />- <!-- Rybbit Tracking Snippet -->- <script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer- ></script>- %sveltekit.head%- </head>- <body data-sveltekit-preload-data="hover">- <div style="display: contents">%sveltekit.body%</div>- </body>+ <head>+ <meta charset="utf-8" />+ <link rel="icon" href="%sveltekit.assets%/favicon.png" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ %sveltekit.head%+ </head>+ <body data-sveltekit-preload-data="hover">+ <div style="display: contents">%sveltekit.body%</div>+ </body></html>```-Ensure `YOUR_SITE_ID` is replaced.++Rybbit tracks SvelteKit's client-side navigations as pageviews automatically; no router hook is needed.</Step><Step>-### Verify Installation+### Verify installation-Deploy your application and check your Rybbit dashboard for incoming data.+<include>../../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **SPA Page View Tracking**: Rybbit's script is designed to automatically track route changes in SvelteKit applications. If page views aren't tracked correctly after navigation (which is uncommon), you might need to manually trigger them using the `afterNavigate` lifecycle function:- ```svelte- // In a layout or page component- import { afterNavigate } from '$app/navigation';+## Track custom events- afterNavigate(() => {- if (typeof window !== 'undefined' && window.rybbit) {- window.rybbit.pageview();- }- });- ```- Test the default behavior first.-</Callout>--## Custom Event Tracking+Call `window.rybbit.event()` from any Svelte component. Guard the call with `typeof window !== "undefined"`, since SvelteKit components also run on the server:-From any Svelte component within your SvelteKit app, you can track custom events:--```svelte+```svelte title="src/lib/components/ActionButton.svelte"<script>function handleAction() {- if (typeof window !== 'undefined' && window.rybbit) {- window.rybbit.event('user_action_sveltekit', { component: 'MySvelteKitComponent' });+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.event("user_action", { component: "ActionButton" });}}</script>-<button on:click={handleAction}>Perform SvelteKit Action</button>+<button on:click={handleAction}>Perform action</button>```-Always check `typeof window !== 'undefined'` before accessing `window.rybbit` as SvelteKit components can also run on the server.++## 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:++ ```svelte title="src/routes/+layout.svelte"+ <script>+ import { afterNavigate } from "$app/navigation";++ afterNavigate(() => {+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.pageview();+ }+ });+ </script>+ ```++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/svelte/vite.mdx b/docs/content/docs/(docs)/guides/svelte/vite.mdxindex 64ec867bb..035078253 100644--- a/docs/content/docs/(docs)/guides/svelte/vite.mdx+++ b/docs/content/docs/(docs)/guides/svelte/vite.mdx@@ -1,95 +1,73 @@---title: Svelte (Vite / Client-Side)-description: Integrate Rybbit with your client-side Svelte application+description: Add Rybbit analytics to your Svelte app+category: frameworks+icon: SiSvelte----import { Steps, Step } from 'fumadocs-ui/components/steps'-import { Callout } from 'fumadocs-ui/components/callout'+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your standard client-side Svelte applications, typically built using Vite (e.g., via `npm create vite@latest -- --template svelte`).--## How to Add Rybbit to Your Client-Side Svelte App--The most straightforward method is to add the Rybbit tracking script directly to your `index.html` file.+A client-side Svelte app built with Vite (`npm create vite@latest -- --template svelte`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet:+### Get your tracking snippet-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Locate Your `index.html` File--For Vite-based Svelte projects, this file is typically located at the root of your project as `index.html`.-</Step>+### Add the snippet to Svelte-<Step>-### Add the Snippet to `index.html`+Open `index.html` at the root of your project and paste the snippet inside `<head>`:-Open `index.html` and paste the Rybbit tracking snippet just before the closing `</head>` tag or `</body>` tag.--```html filename="index.html (Vite)"-<!DOCTYPE html>+```html title="index.html"+<!doctype html><html lang="en"><head><meta charset="UTF-8" />- <link rel="icon" type="image/svg+xml" href="/vite.svg" /> <!-- Or your favicon -->+ <link rel="icon" type="image/svg+xml" href="/vite.svg" /><meta name="viewport" content="width=device-width, initial-scale=1.0" /><title>My Svelte App</title>- <!-- Rybbit Tracking Snippet -->- <script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer- ></script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script></head><body><div id="app"></div>- <script type="module" src="/src/main.js"></script> <!-- Or main.ts -->- <!-- Or place script here, before </body> -->+ <script type="module" src="/src/main.js"></script></body></html>```-Ensure `YOUR_SITE_ID` is replaced.++Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.</Step><Step>-### Verify Installation+### Verify installation-Deploy your application and check your Rybbit dashboard for incoming data. You can also inspect your browser's network tab to confirm `script.js` is loaded.+<include>../../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **SPA Page View Tracking**: Rybbit's script is designed to automatically track route changes in client-side Svelte SPAs using common routers (like `svelte-routing` or `svelte-spa-router`). If page views aren't tracked correctly after navigation, you might need to manually trigger `window.rybbit.pageview()` after each route change, using your router's specific API for navigation events.-</Callout>+## Track custom events-## Custom Event Tracking+Call `window.rybbit.event()` from any Svelte component:-From any Svelte component, you can track custom events:--```svelte+```svelte title="src/lib/ActionButton.svelte"<script>- function handleClientAction() {- // Ensure running in browser, though for client-side Svelte this is usually the case- if (typeof window !== 'undefined' && window.rybbit) {- window.rybbit.event('user_action_svelte_vite', { component: 'MySvelteViteComponent' });+ function handleAction() {+ if (window.rybbit) {+ window.rybbit.event("user_action", { component: "ActionButton" });}}</script>-<button on:click={handleClientAction}>Perform Client Svelte Action</button>+<button on:click={handleAction}>Perform action</button>```-Always check for `window.rybbit` before calling its methods.++## 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.++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/systeme-io.mdx b/docs/content/docs/(docs)/guides/systeme-io.mdxnew file mode 100644index 000000000..4e511dca6--- /dev/null+++ b/docs/content/docs/(docs)/guides/systeme-io.mdx@@ -0,0 +1,57 @@+---+title: systeme.io+description: Add Rybbit analytics to your systeme.io funnels+category: landing+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++systeme.io has an account-wide **Tracking code** setting under **Settings > Sales Funnels** that adds code to every funnel page, plus a per-page **Tracking** section with a header field in the page editor. Use the account-wide setting unless you only want to track certain pages.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to systeme.io++<Tabs items={["All funnels", "One page"]}>+<Tab>+1. Click your **profile picture** in the top-right corner and choose **Settings**.+2. Select **Sales Funnels** in the left menu.+3. Paste the snippet into the **Tracking code** box and click **Save**.++The code is added to every page in every funnel on the account.+</Tab>++<Tab>+1. Open the funnel, select the page in the list on the left and click **Edit page**.+2. Click **Settings** in the upper-left corner of the editor and scroll to the **Tracking** section.+3. Paste the snippet into the **header** field (the one for code that belongs between `<head>` and `</head>`).+4. Save the page.+</Tab>+</Tabs>++Paste only the `<script>` tag. systeme.io asks that custom code never include `<head>`, `<body>` or `<html>` tags of its own.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Duplicate pageviews**: the snippet is in both the account-wide Tracking code and a page's Tracking section. Keep one.+- **Not visible in preview**: custom code runs on the live page only. Open the published funnel URL to test.+- **Pages outside funnels**: the Sales Funnels tracking code covers funnel pages. Blog and course pages have their own settings, so add the snippet there if you want that traffic in the same site.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/tauri.mdx b/docs/content/docs/(docs)/guides/tauri.mdxnew file mode 100644index 000000000..bb4cb8991--- /dev/null+++ b/docs/content/docs/(docs)/guides/tauri.mdx@@ -0,0 +1,106 @@+---+title: Tauri+description: Add Rybbit analytics to your Tauri app+category: apps+icon: SiTauri+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Tauri v2 bundles your frontend into the app and serves it to the system webview. Install the `@rybbit/js` SDK in the frontend (or put the snippet in its `index.html`), then allow `https://app.rybbit.io` in the `app.security.csp` block of `src-tauri/tauri.conf.json`.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Tauri++<Callout type="info">+Tauri's security guide advises against loading remote scripts such as CDN-hosted files. The SDK keeps all executable code inside the bundle, so it is the recommended method.+</Callout>++<Tabs items={["@rybbit/js SDK", "Script tag"]}>+<Tab>+1. Install the package in your frontend project:++```bash+npm install @rybbit/js+```++2. Initialise it once in the frontend entry file (`src/main.ts` or equivalent):++```ts title="src/main.ts"+import rybbit from "@rybbit/js";++await rybbit.init({+ analyticsHost: "https://app.rybbit.io/api",+ siteId: "YOUR_SITE_ID",+});+```++3. Allow the analytics host in `connect-src`. Keep `ipc:` and `http://ipc.localhost`, which Tauri needs for frontend-to-Rust calls:++```json title="src-tauri/tauri.conf.json"+{+ "app": {+ "security": {+ "csp": {+ "default-src": "'self'",+ "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]+ }+ }+ }+}+```+</Tab>++<Tab>+1. Paste the snippet into the `<head>` of your frontend's `index.html`:++```html title="index.html"+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+```++2. Allow the host in both `script-src` and `connect-src`:++```json title="src-tauri/tauri.conf.json"+{+ "app": {+ "security": {+ "csp": {+ "default-src": "'self'",+ "script-src": ["'self'", "https://app.rybbit.io"],+ "connect-src": ["ipc:", "http://ipc.localhost", "https://app.rybbit.io"]+ }+ }+ }+}+```+</Tab>+</Tabs>++If `app.security.csp` is unset, Tauri applies no CSP and neither change is needed. Route changes inside the app are tracked automatically: the tracker wraps `history.pushState` and `history.replaceState` and listens for `popstate` and `hashchange`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Works in `tauri dev` but not in the built app on macOS, Linux or iOS**: in development the frontend is served from your dev server (`http://localhost:1420` by default), which is a normal http origin. Production builds serve it from `http://tauri.localhost` on Windows and Android but from the custom scheme `tauri://localhost` on macOS, Linux and iOS. Rybbit's tracking endpoints answer CORS preflights for `http://` and `https://` origins only, so requests from `tauri://localhost` are blocked by the webview. On Windows and Android, `app.windows[].useHttpsScheme: true` switches the origin to `https://tauri.localhost`; both forms work.+- **CSP violation in the webview console**: the message names the blocked directive. Add `https://app.rybbit.io` there; the SDK only needs `connect-src`, the script tag also needs `script-src`.+- **Object vs string CSP**: `app.security.csp` accepts either a single policy string or the object form shown above. Do not mix the two.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/teachable.mdx b/docs/content/docs/(docs)/guides/teachable.mdxnew file mode 100644index 000000000..fcea4dd9c--- /dev/null+++ b/docs/content/docs/(docs)/guides/teachable.mdx@@ -0,0 +1,43 @@+---+title: Teachable+description: Add Rybbit analytics to your Teachable site+category: creators+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Teachable adds tracking scripts through **Code Snippets** in the school admin, where the **Head Code Snippets** section places code inside the `<head>` of every page of your school. Code Snippets are available on the Builder plan and above.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Teachable++1. In the school admin, go to **Site > Code Snippets**.+2. Paste the snippet into the **Head Code Snippets** section, which applies to all pages and all users.+3. Click **Save**.++The **Logged In Snippets** and **Logged Out Snippets** sections restrict code to one audience. Leave them empty for Rybbit so students and prospects are tracked alike; if you only want to measure the public site, use **Logged Out Snippets** instead of the head section.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Code Snippets is missing from the Site menu**: it needs the Builder plan or higher. Schools on lower plans cannot add custom scripts.+- **Checkout and login pages are not tracked**: head code snippets do not apply to SSO-based login or checkout pages served from `sso.teachable.com`. Pages on your school domain, including the course area, are covered.+- **Snippet pasted into a lesson's Custom HTML block**: that block only affects one lesson. Use **Code Snippets** for site-wide tracking.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/thinkific.mdx b/docs/content/docs/(docs)/guides/thinkific.mdxnew file mode 100644index 000000000..feba9121b--- /dev/null+++ b/docs/content/docs/(docs)/guides/thinkific.mdx@@ -0,0 +1,44 @@+---+title: Thinkific+description: Add Rybbit analytics to your Thinkific site+category: creators+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Thinkific adds custom scripts through the **Site Footer Code** field under **Settings > Code & Analytics**. The code runs at the bottom of every page, including the Course Player, and editing it is available on paid plans (Basic or higher). Placing the snippet in the footer rather than the head is fine: it loads with `defer`, so timing is the same.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Thinkific++1. In the admin dashboard, go to **Settings** and open the **Code & Analytics** tab.+2. Paste the snippet into **Site Footer Code**.+3. Save.++See Thinkific's [Site Footer Code](https://support.thinkific.com/hc/en-us/articles/360030724953-Site-Footer-Code) article for the field's current limits. Lesson changes inside the Course Player happen without a page reload; Rybbit tracks them as pageviews automatically as the URL changes.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Field is read-only or missing**: editing Site Footer Code needs a paid plan (Basic or higher).+- **Checkout is not tracked**: Site Footer Code does not run on Performance Checkout pages, so purchases complete outside Rybbit's view. Track the enrolment from the first page a student lands on after checkout, or use a webhook on your side.+- **Community pages are not tracked**: pages where students post and comment, and direct-messaging pages, are excluded from Site Footer Code by default.+- **Per-page footer code**: individual site pages also accept footer code in their page settings. Keep the site-wide field as the single place for the snippet so pages are not tracked twice.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/thrivecart.mdx b/docs/content/docs/(docs)/guides/thrivecart.mdxindex 6de27ee70..8c6c27f99 100644--- a/docs/content/docs/(docs)/guides/thrivecart.mdx+++ b/docs/content/docs/(docs)/guides/thrivecart.mdx@@ -1,77 +1,54 @@----title: "ThriveCart"-description: "Integrate Rybbit Analytics with your ThriveCart checkout pages"+title: ThriveCart+description: Add Rybbit analytics to your ThriveCart checkout pages+category: ecommerce----import { Step, Steps } from "fumadocs-ui/components/steps";-import { Callout } from "fumadocs-ui/components/callout";+import { Steps, Step } from "fumadocs-ui/components/steps";-# ThriveCart--Rybbit can be integrated with ThriveCart to track cart views, purchases, and other conversion events on your checkout pages.--<Callout type="warn">- ThriveCart strips out the standard `data-site-id` attribute from scripts. You must use the alternative installation method below for Rybbit to work correctly.-</Callout>--## Adding the Tracking Script--The standard Rybbit script won't work in ThriveCart because ThriveCart removes the `data-site-id` attribute. Instead, use this JavaScript snippet that dynamically creates the script element:+ThriveCart lets you add custom scripts to each checkout page, and its success page is where the purchase event goes. ThriveCart strips `data-*` attributes from script tags, so the site ID must travel in the script URL, as it does in the snippet below.<Steps><Step>-### Access ThriveCart Settings+### Get your tracking snippet-In your ThriveCart dashboard, navigate to the checkout page you want to track. Go to **Settings > Tracking** or the custom scripts section.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Add the Tracking Script+### Add the snippet to ThriveCart-Paste the following script into the header scripts section:+1. In your ThriveCart dashboard, open the checkout page you want to track.+2. Open **Settings > Tracking**, the custom scripts section.+3. Paste the snippet into the header scripts field and save.-```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js';- s.async = true;- s.setAttribute('data-site-id', 'YOUR_SITE_ID');- document.head.appendChild(s);-})();-</script>-```--Replace `YOUR_SITE_ID` with your actual Rybbit Site ID from your dashboard.+Repeat for each checkout page. If checkout runs on a subdomain such as `sales.yourdomain.com` and your main site uses the same site ID, both are tracked as one site, so funnels can follow a visitor from your site through to the purchase.</Step><Step>-### Save and Test+### Verify installation-Save your changes and visit your checkout page. Check your Rybbit dashboard to confirm pageviews are being tracked.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-## Tracking Purchase Events+## Track custom events-ThriveCart also interferes with how events are fired, so purchase events need special handling to ensure they fire reliably and only once per transaction.+#### Purchase-Add this script to your ThriveCart **success page** (the page shown after a completed purchase):+ThriveCart also interferes with how inline events fire, so the success-page script below loads the tracker itself if it is missing, waits for it, and uses `sessionStorage` to send the event once per browser session even if the visitor refreshes or navigates back.++Add it to the checkout's **success page** and fill in the values at the top:```html<script>(function () {- // --- CONFIGURE YOUR EVENT ---var EVENT_NAME = "purchase";- var PAYLOAD = {- content_name: "Your Product Name",- value: 97.00,- currency: "USD"- };+ var PAYLOAD = { content_name: "Your Product Name", value: 97.0, currency: "USD" };var SITE_ID = "YOUR_SITE_ID";- // -----------------------------+ var SCRIPT_SRC = "https://app.rybbit.io/api/script.js?siteId=" + SITE_ID;- // Prevent duplicate events on refresh/back navigation+ // Send once per session, even on refresh or back navigationvar SENT_KEY = "rybbit_" + EVENT_NAME + "_sent_v1";try {if (sessionStorage.getItem(SENT_KEY) === "1") return;@@ -81,77 +58,41 @@ Add this script to your ThriveCart **success page** (the page shown after a compfunction isReady() {return window.rybbit && typeof window.rybbit.event === "function";}-function send() {window.rybbit.event(EVENT_NAME, PAYLOAD);}-function waitThenSend(timeoutMs) {var start = Date.now();(function check() {if (isReady()) return send();- if (Date.now() - start < timeoutMs) return setTimeout(check, 150);- // Fail silently if timeout reached+ if (Date.now() - start < timeoutMs) setTimeout(check, 150);})();}- function ensureScriptLoaded() {- // Avoid duplicate script loads- if (document.querySelector('script[src="https://app.rybbit.io/api/script.js"]')) return;-+ if (isReady()) return send();+ if (!document.querySelector('script[src="' + SCRIPT_SRC + '"]')) {var s = document.createElement("script");- s.src = "https://app.rybbit.io/api/script.js";- s.async = true;- s.setAttribute("data-site-id", SITE_ID);- s.onload = function () { waitThenSend(3000); };+ s.src = SCRIPT_SRC;+ s.defer = true;document.head.appendChild(s);}-- // If Rybbit is already loaded, send immediately- if (isReady()) return send();-- // Otherwise, load the script and wait for it- ensureScriptLoaded();waitThenSend(8000);})();</script>```-### Configuration--Update the configuration variables at the top of the script:--- `EVENT_NAME`: The name of the event (e.g., `"purchase"`, `"checkout_complete"`)-- `PAYLOAD`: An object containing event data:- - `content_name`: The product name- - `value`: The purchase amount- - `currency`: The currency code (e.g., `"USD"`, `"GBP"`, `"EUR"`)-- `SITE_ID`: Your Rybbit Site ID+- `EVENT_NAME`: the event name, for example `purchase` or `checkout_complete`.+- `PAYLOAD`: `content_name` (product name), `value` (amount) and `currency` (`USD`, `GBP`, `EUR` and so on).+- `SITE_ID`: your Rybbit site ID.-## Tracking Multiple Products--If you have different products, create separate success pages or use ThriveCart's dynamic variables (if available) to populate the payload. Each product page should have its own configured script with the appropriate product name and price.--## Using with Subdomains--If your ThriveCart is hosted on a subdomain (e.g., `sales.yourdomain.com`) while your main site is on `yourdomain.com`, Rybbit will track both as part of the same site as long as you use the same Site ID. This allows you to create funnels that track the user journey from your main site through to the ThriveCart checkout and purchase.+Selling several products? The payload is fixed per page, so use a separate success page per product, or fill `PAYLOAD` from ThriveCart's dynamic variables where they are available.## Troubleshooting-### Events not appearing in Rybbit--1. **Check the script is loading**: Open your browser's Developer Tools (F12), go to the Network tab, and look for `script.js` being loaded from `app.rybbit.io`.-2. **Check for JavaScript errors**: In the Console tab, look for any red error messages.-3. **Verify your Site ID**: Make sure you've replaced `YOUR_SITE_ID` with your actual Site ID from the Rybbit dashboard.--### Duplicate events--The script includes session storage protection to prevent duplicate events on page refresh. If you're still seeing duplicates:-- Clear your browser's session storage and test again-- Make sure you only have one instance of the event script on the page+- **Script attributes are stripped**: ThriveCart removes `data-*` attributes, so [script attributes](/docs/script#script-attributes) such as `data-skip-patterns` do not work here. Keep the site ID in the URL.+- **Duplicate purchase events**: the script is guarded by `sessionStorage`. If you still see duplicates, make sure the event script is on the success page only once, and clear session storage before testing again.+- **Script blocked**: if `script.js` never loads, try the footer scripts field instead of the header, or ask ThriveCart support to confirm custom scripts are enabled on your account.-### Script not loading+## Next steps-If the script isn't loading at all, ThriveCart may be blocking it. Try:-- Adding the script to a different location (footer instead of header)-- Contacting ThriveCart support to ensure custom scripts are enabled for your account+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/typo3.mdx b/docs/content/docs/(docs)/guides/typo3.mdxindex bfcf8fb94..ead1ca9bf 100644--- a/docs/content/docs/(docs)/guides/typo3.mdx+++ b/docs/content/docs/(docs)/guides/typo3.mdx@@ -1,108 +1,78 @@---title: TYPO3-description: Integrate Rybbit Analytics with your TYPO3 sitepackage+description: Add Rybbit analytics to your TYPO3 site+category: cms+icon: SiTypo3----import { Steps, Step } from 'fumadocs-ui/components/steps';+import { Steps, Step } from "fumadocs-ui/components/steps";-Integrating Rybbit Analytics with your TYPO3 website is straightforward. You'll-typically add the Rybbit tracking script to your main sitepackage-`setup.typoscript` file.+TYPO3 sitepackages build the page `<head>` from TypoScript rather than an HTML template, so the snippet is added as a `page.includeJS` entry in your sitepackage's `setup.typoscript`.<Steps><Step>-### Get Your Tracking script+### Get your tracking snippet-First, you'll need your Rybbit tracking script. You can find this in your Rybbit-dashboard under **Site Settings > Tracking Code**. It will look something like this:--```html-<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-```--For TYPO3 we will need pieces of this, not the full script.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Locate your main TypoScript config file--In a standard TYPO3 sitepackage you'll have a main TypoScript setup file. This-file is mostly located at: `<sitepackage>/Configuration/TypoScript/setup.typoscript`.--In theory this file could be somewhere else or in a TypoScript record in the-TYPO3 backend.+### Add the snippet to TYPO3++1. Open your main TypoScript setup file, usually `<sitepackage>/Configuration/TypoScript/setup.typoscript`. It is the file that already contains `page = PAGE`. The same TypoScript can also live in a TypoScript record in the backend.+2. Add the script to the `page` object:++ ```+ page = PAGE+ page {+ includeJS {+ rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID+ rybbit.defer = 1+ }+ }+ ```++ Because the Site ID is part of the URL, no `data-*` attribute is needed, so this works on every supported TYPO3 version. Per-include attributes on `includeJS` only exist in TYPO3 12.1+.++3. To track production only, wrap the include in an `applicationContext` condition:++ ```+ [applicationContext == "Production"]+ page.includeJS.rybbit = https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID+ page.includeJS.rybbit.defer = 1+ [END]+ ```++4. Optionally keep the Site ID and instance URL in `constants.typoscript` (or a TypoScript record) so the setup file can be committed without site-specific values:++ ```+ # constants.typoscript+ rybbit {+ host = https://app.rybbit.io+ siteId = YOUR_SITE_ID+ }++ # setup.typoscript+ page.includeJS.rybbit = {$rybbit.host}/api/script.js?siteId={$rybbit.siteId}+ page.includeJS.rybbit.defer = 1+ ```++5. Deploy the sitepackage, or set `applicationContext` accordingly, and flush the TYPO3 caches.</Step><Step>-### Add the Tracking Script to the `setup.typoscript` file--In TYPO3 we normally don't have direct code access to the HTML `<head>`, but-have to add those entries to the `page` object:--```-page = PAGE-page {- # ...- includeJS {- rybbit = https://app.rybbit.io/api/script.js- rybbit.defer = 1- rybbit.data-site-id = YOUR_SITE_ID- }- # ...-}-```--This creates a new `<script>` tag, loads the rybbit script and adds the Site ID-data attribute.--Per-include attributes like `data-site-id` require TYPO3 12.1+ (Feature #91499).-On older TYPO3 versions `includeJS` cannot emit `data-*` attributes, so you'll-need a different install method (for example, adding the full `<script>` tag via-`page.headerData`).--Most likely you will already have the line `page = PAGE` somewhere in your-codebase, this also identifies the file, that is most likely to be your main-TypoScript setup file.--If you want to load the script only for your production environment, you need-to add a condition for the `applicationContext`:--```-[applicationContext == "Production"]-page {- includeJS {- rybbit = https://app.rybbit.io/api/script.js- rybbit.defer = 1- rybbit.data-site-id = YOUR_SITE_ID- }-}-[END]-```+### Verify installation+<include>../../../partials/guides/verify.mdx</include></Step>+</Steps>-<Step>-### Configure values as constants--It's best practice to store your Rybbit Site ID and instance URL in your site-constants. You might have a `constants.typoscript` file in your codebase, which-you'll use when you want to add the values to the Git repository.--You can also add the values into a TypoScript record in the TYPO3 backend.-</Step>+## Troubleshooting-<Step>-### Verify Integration--- Deploy your TYPO3 sitepackage to your production environment or setup- `applicationContext` accordingly.-- Open your live website in a browser.-- Navigate through a few pages.-- Check your Rybbit dashboard for incoming data. It might take a few minutes- for the first events to appear.-</Step>+- **Script not in the page source**: TYPO3 caches rendered pages. Flush caches from the backend toolbar or with `vendor/bin/typo3 cache:flush` after changing TypoScript.+- **Wrong TypoScript file**: if several files define `page`, check the resulting `page.includeJS` in the TypoScript object browser in the backend to see which definition wins.+- **Condition never matches**: the `applicationContext` is set through the `TYPO3_CONTEXT` environment variable. If it is unset, TYPO3 runs as `Production` and the script loads everywhere.-</Steps>+## Next steps-That's it! Rybbit Analytics is now integrated with your TYPO3 sitepackage and-will only track visits in your production environment.+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/umbraco.mdx b/docs/content/docs/(docs)/guides/umbraco.mdxnew file mode 100644index 000000000..9b9832896--- /dev/null+++ b/docs/content/docs/(docs)/guides/umbraco.mdx@@ -0,0 +1,68 @@+---+title: Umbraco+description: Add Rybbit analytics to your Umbraco site+category: cms+icon: SiUmbraco+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Umbraco renders pages with Razor templates stored as `.cshtml` files in the `Views` folder and edited in the backoffice under **Settings > Templates**. A fresh install has no templates until you create one, so the snippet goes into the master (layout) template that your page templates set as their `Layout`.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Umbraco++1. In the backoffice, open the **Settings** section and expand **Templates**.+2. Open the master template that the other templates use as their layout (named `Master` in Umbraco's own tutorial). If you have none yet, click **...** next to **Templates**, choose **Create**, and move the shared `<html>`, `<head>` and `<body>` markup into it.+3. Add the tag before `</head>` and click **Save**:++```razor title="Views/Master.cshtml"+@using Umbraco.Cms.Web.Common.PublishedModels;+@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage+@{+ Layout = null;+}+<!DOCTYPE html>+<html>+<head>+ <meta charset="utf-8" />+ <title>@Model.Name</title>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+</head>+<body>+ @RenderBody()+</body>+</html>+```++4. Check that each page template points at it, for example `Layout = "Master.cshtml";`. Templates with `Layout = null;` render their own `<head>` and need the tag added directly.++Saving in the backoffice writes the same file to `Views/Master.cshtml` in the project, so you can also edit it in your IDE and commit it.++To keep the site ID out of the template, put it in `appsettings.json` and read it with `@Configuration["Rybbit:SiteId"]` after injecting `IConfiguration`.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Change not visible**: Razor views are compiled on first request; if you edited the file outside the backoffice on a published site, restart the app or redeploy. Also clear any output cache or CDN in front of the site.+- **Preview counts as visits**: the backoffice **Preview** button renders your template with unpublished content, so editors' previews are tracked like any other visit. Wrap the tag in `@if (!UmbracoContext.InPreviewMode) { ... }` to leave them out.+- **Backoffice is not tracked**: `/umbraco` is a separate app that does not use your templates, so editing time never appears in Rybbit.+- **Several master templates**: a multi-site install with one layout per site needs the tag in each, or in a partial view rendered from every layout with `@await Html.PartialAsync("Rybbit")`.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/unbounce.mdx b/docs/content/docs/(docs)/guides/unbounce.mdxnew file mode 100644index 000000000..af44f4f1c--- /dev/null+++ b/docs/content/docs/(docs)/guides/unbounce.mdx@@ -0,0 +1,85 @@+---+title: Unbounce+description: Add Rybbit analytics to your Unbounce landing pages+category: landing+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++Unbounce's **Script Manager** applies a script to every page on a domain, including pages you publish later, so that is where the snippet goes. If you only want to track a single Classic Builder page, the page-level **Javascripts** dialog works too.++<Callout type="warn">+Custom scripts and pixels are not available on the Starter plan; you need Build or higher. Script Manager also requires a connected custom domain: it does not apply to pages on the `unbouncepages.com` test domain.+</Callout>++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Unbounce++<Tabs items={["Script Manager", "Classic Builder page"]}>+<Tab>+1. In the left menu, click **Settings**, then **Script Manager**.+2. Click **Add a Script**, choose **Custom Script**, give it a name and click **Add Script Details**.+3. Set **Placement** to **Head** and **Included on** to **All** (main pages and confirmation dialogs).+4. Paste the snippet into the editor.+5. Tick the domain(s) the script should apply to on the right, then click **Save Changes**.++The script is added to every page on those domains and to new pages published there later. If a page does not pick it up, republish that page.+</Tab>++<Tab>+1. Open the page in the Classic Builder and click **Javascripts** in the bottom-left corner.+2. Give the script a name and set **Placement** to **Head**.+3. Paste the snippet and click **Done**.+4. **Save**, then **Publish** (or **Republish**) the page. Custom scripts do not run in the builder or in Preview, only on the published page.++Smart Builder pages have no page-level script dialog; use Script Manager for those.+</Tab>+</Tabs>+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++#### Form submission++Unbounce exposes `window.ub.hooks`, an unofficial hook that runs after a lead is recorded. Add this as a second Script Manager script (or page script) with placement **Before Body End Tag** to send a `lead` event with the page name and variant:++```html+<script>+window.ub.hooks.afterFormSubmit.push(function () {+ if (window.rybbit) {+ window.rybbit.event("lead", {+ page: window.ub.page.name,+ variant: window.ub.page.variantId+ });+ }+});+</script>+```++`window.ub.page.name`, `window.ub.page.variantId` and `window.ub.page.id` are available on every Unbounce page, so you can compare A/B variants in Rybbit without any other setup.++## Troubleshooting++- **Script runs twice**: a script that is both in Script Manager and on an individual page loads twice. Remove the page-level copy and keep the Script Manager one.+- **Nothing on `unbouncepages.com`**: Script Manager only applies to custom domains. Add the snippet at page level to test on the Unbounce test domain.+- **Script Manager missing**: the account is on the Starter plan, which does not include custom scripts.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/v0.mdx b/docs/content/docs/(docs)/guides/v0.mdxnew file mode 100644index 000000000..c92a62569--- /dev/null+++ b/docs/content/docs/(docs)/guides/v0.mdx@@ -0,0 +1,96 @@+---+title: v0+description: Add Rybbit analytics to your v0 app+category: ai-builders+icon: SiV0+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";++v0 generates Next.js apps, so there is no single `index.html` and no project setting for head code. The snippet goes into the root layout, `app/layout.tsx`, through a `next/script` tag that renders on every page. Ask v0 to add it or edit the file in the Code tab, then publish.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to v0++<Tabs items={["Ask v0", "Edit app/layout.tsx"]}>+<Tab>+Paste this into the chat, with your site ID in place of the placeholder:++```text+Add the Rybbit analytics script to the root layout (app/layout.tsx) using next/script with strategy="afterInteractive", so it loads on every page:+https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID+```++Check the diff: the `<Script>` belongs in `app/layout.tsx`, not in a page or component.+</Tab>++<Tab>+Select the **Code** tab in the preview toolbar, open `app/layout.tsx` and add the `Script` component inside `<body>`. The `defer` attribute from the snippet is not needed; the strategy handles timing.++```tsx title="app/layout.tsx"+import Script from "next/script";++export default function RootLayout({ children }: { children: React.ReactNode }) {+ return (+ <html lang="en">+ <body>+ {children}+ <Script+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"+ strategy="afterInteractive"+ />+ </body>+ </html>+ );+}+```++Press **Cmd+S** / **Ctrl+S** to save.+</Tab>+</Tabs>++Click **Publish** in the top right of the chat, then **Publish to Production**. Navigation through `<Link>` and `router.push()` is tracked as pageviews automatically.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++Call `window.rybbit.event()` from a client component. Guard the call, because v0 components can render on the server and the script loads after hydration.++```tsx title="components/signup-button.tsx"+"use client";++export function SignupButton() {+ const handleClick = () => {+ if (typeof window !== "undefined" && window.rybbit) {+ window.rybbit.event("signup_click", { location: "hero" });+ }+ };++ return <button onClick={handleClick}>Sign up</button>;+}+```++## Troubleshooting++- **Production has no script**: the preview updates on save, but the live site only changes after **Publish to Production**. Projects connected to GitHub go through a pull request that v0 merges before the production deployment runs.+- **v0 rewrote the layout**: a later prompt can regenerate `app/layout.tsx`. Add "keep the Rybbit Script tag in app/layout.tsx" to the project's custom instructions, and re-check the page source after large changes.+- **Pages Router**: if your project has `pages/` instead of `app/`, put the `Script` in `pages/_app.tsx` as shown in the [Next.js guide](/docs/guides/react/next-js).++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/vitepress.mdx b/docs/content/docs/(docs)/guides/vitepress.mdxindex cfd92b25f..2e5b7527a 100644--- a/docs/content/docs/(docs)/guides/vitepress.mdx+++ b/docs/content/docs/(docs)/guides/vitepress.mdx@@ -1,116 +1,103 @@---title: VitePress-description: Integrate Rybbit Analytics with your VitePress documentation site+description: Add Rybbit analytics to your VitePress docs+category: docs+icon: SiVitepress----import { Tabs, Tab } from 'fumadocs-ui/components/tabs';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-VitePress is a static site generator powered by Vite and Vue, commonly used for documentation. Here's how to add Rybbit Analytics to your VitePress site.+VitePress has a `head` option in `.vitepress/config.ts` that adds tags to every page, which is where the snippet goes. A custom theme is the fallback when you need to load it conditionally at runtime.-## How to Add Rybbit to VitePress+<Steps>+<Step>+### Get your tracking snippet-<Tabs items={['Config File (Recommended)', 'Custom Theme']}>-<Tab>-### Using VitePress Config+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-The simplest way to add Rybbit is through your VitePress configuration file.+<Step>+### Add the snippet to VitePress-Edit your `.vitepress/config.ts` (or `.js`/`.mts`):+<Tabs items={["Config file", "Custom theme"]}>+<Tab>+Edit `.vitepress/config.ts` (or `.js` / `.mts`) and add the tag to `head`:-```typescript-import { defineConfig } from 'vitepress'+```typescript filename=".vitepress/config.ts"+import { defineConfig } from "vitepress";export default defineConfig({// ... your other confighead: [[- 'script',+ "script",{- src: 'https://app.rybbit.io/api/script.js',- 'data-site-id': 'YOUR_SITE_ID',- defer: ''- }- ]- ]-})+ src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",+ defer: "",+ },+ ],+ ],+});```-Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.-<Callout type="info">-The empty string for `defer` is intentional - VitePress will render it as a boolean attribute.+The empty string for `defer` is intentional. VitePress renders it as a boolean attribute.</Callout>-</Tab>-<Tab>-### Using Custom Theme+To track production only, make `head` conditional:-If you need more control, you can add the script through a custom theme.+```typescript filename=".vitepress/config.ts"+const isProd = process.env.NODE_ENV === "production";-Create or edit `.vitepress/theme/index.ts`:+export default defineConfig({+ head: isProd+ ? [["script", { src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID", defer: "" }]]+ : [],+});+```+</Tab>++<Tab>+If you need runtime control, inject the tag from a custom theme. Create or edit `.vitepress/theme/index.ts`:-```typescript-import { type Theme } from 'vitepress'-import DefaultTheme from 'vitepress/theme'-import { onMounted } from 'vue'+```typescript filename=".vitepress/theme/index.ts"+import { type Theme } from "vitepress";+import DefaultTheme from "vitepress/theme";export default {extends: DefaultTheme,- enhanceApp({ app }) {- // Only run in browser- if (typeof window !== 'undefined') {- onMounted(() => {- const script = document.createElement('script')- script.src = 'https://app.rybbit.io/api/script.js'- script.defer = true- script.setAttribute('data-site-id', 'YOUR_SITE_ID')- document.head.appendChild(script)- })- }- }-} satisfies Theme+ enhanceApp() {+ if (typeof window === "undefined") return;++ const el = document.createElement("script");+ el.src = "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID";+ el.defer = true;+ document.head.appendChild(el);+ },+} satisfies Theme;```-Replace `YOUR_SITE_ID` with your actual Site ID.+The `window` check keeps the injector out of the server-side build.</Tab></Tabs>-## SPA Navigation+VitePress navigates between pages client-side. Rybbit picks up those History API changes as pageviews, so no extra code is needed.+</Step>-VitePress uses client-side navigation between pages. The Rybbit script automatically tracks page views during SPA navigation, so no additional configuration is needed.+<Step>+### Verify installation-## Development vs Production--The script will load in both development and production environments. If you only want to track production:--```typescript-import { defineConfig } from 'vitepress'--const isProd = process.env.NODE_ENV === 'production'--export default defineConfig({- head: isProd ? [- [- 'script',- {- src: 'https://app.rybbit.io/api/script.js',- 'data-site-id': 'YOUR_SITE_ID',- defer: ''- }- ]- ] : []-})-```+<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>## Troubleshooting-### Script not loading in development--By default, the script loads on all environments. Check your browser's developer tools Network tab to see if the script is being requested.+- **Tag missing in `vitepress dev`**: if you used the `isProd` guard, the tag only renders in `vitepress build`. Remove the guard to test locally.+- **Pageviews stop after navigation**: check the browser console for errors thrown by other `head` scripts or theme code; an exception during route change can block Rybbit's listener.-### Page views not tracking on navigation+## Next steps-VitePress handles this automatically through the History API. If you're experiencing issues:-1. Ensure you're using a recent version of VitePress-2. Check the browser console for any JavaScript errors+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/vue/meta.json b/docs/content/docs/(docs)/guides/vue/meta.jsonindex dbd7b3239..5b71fda4b 100644--- a/docs/content/docs/(docs)/guides/vue/meta.json+++ b/docs/content/docs/(docs)/guides/vue/meta.json@@ -1,4 +1,7 @@{"title": "Vue",- "pages": ["vite", "nuxt"]+ "pages": [+ "nuxt",+ "vite"+ ]}diff --git a/docs/content/docs/(docs)/guides/vue/nuxt.mdx b/docs/content/docs/(docs)/guides/vue/nuxt.mdxindex bc543b70e..7e5344014 100644--- a/docs/content/docs/(docs)/guides/vue/nuxt.mdx+++ b/docs/content/docs/(docs)/guides/vue/nuxt.mdx@@ -1,169 +1,130 @@---title: Nuxt.js-description: Integrate Rybbit with your Nuxt.js application for analytics tracking+description: Add Rybbit analytics to your Nuxt app+category: frameworks+icon: SiNuxt----import { Steps, Step } from 'fumadocs-ui/components/steps'-import { Callout } from 'fumadocs-ui/components/callout'+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";--This guide explains how to integrate Rybbit with your Nuxt.js application for analytics tracking.--## Adding Rybbit via Nuxt Scripts (Recommended)--[Nuxt Scripts](https://scripts.nuxt.com/scripts/rybbit-analytics) ships a first-class Rybbit Analytics integration. It loads the script optimally, handles SPA route tracking, and gives you a typed composable for custom events. This is the recommended method for Nuxt 3 and Nuxt 4 applications.+Nuxt has two ways to load Rybbit: the [Nuxt Scripts](https://scripts.nuxt.com/scripts/rybbit-analytics) module, which ships a first-class Rybbit registry entry with a typed composable, or the `app.head.script` array in `nuxt.config.ts`.<Steps><Step>-### Retrieve Your Site ID+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your Site ID. You'll need this for the `siteId` option below.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Install the Nuxt Scripts module+### Add the snippet to Nuxt++<Tabs items={["Nuxt Scripts (Nuxt 3 and 4)", "nuxt.config head"]}>+<Tab value="Nuxt Scripts (Nuxt 3 and 4)">+Install the module. This adds `@nuxt/scripts` to the `modules` array in your `nuxt.config`:```bashnpx nuxi module add scripts```-This installs `@nuxt/scripts` and adds it to the `modules` array in your `nuxt.config`.-</Step>--<Step>-### Configure Rybbit in `nuxt.config.ts`--Register Rybbit Analytics under `scripts.registry` and pass your Site ID:+Register Rybbit under `scripts.registry` with the site ID from your snippet:-```typescript filename="nuxt.config.ts"+```typescript title="nuxt.config.ts"export default defineNuxtConfig({- modules: ['@nuxt/scripts'],+ modules: ["@nuxt/scripts"],scripts: {registry: {rybbitAnalytics: {- siteId: 'YOUR_SITE_ID', // Replace with your Site ID- trigger: 'onNuxtReady',+ siteId: "YOUR_SITE_ID",+ trigger: "onNuxtReady",},},},-})+});```-Useful options:+Options:-- **`siteId`** (required): Your Rybbit site ID.-- **`autoTrackPageview`**: Track page views automatically (enabled by default).-- **`trackSpa`**: Track client-side route changes (enabled by default).-- **`analyticsHost`**: Override the script/API host when using a self-hosted Rybbit instance (e.g. `https://your-instance.com/api`).-- **`sessionReplay`**, **`webVitals`**, **`trackOutbound`**: Optional features you can enable as needed.+- `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.<Callout type="info">- You can keep your Site ID out of source control by setting it via environment variable. Nuxt Scripts reads `NUXT_PUBLIC_SCRIPTS_RYBBIT_ANALYTICS_SITE_ID` at runtime, so you can leave `siteId` unset in config and provide it through your environment instead.+ 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.</Callout>-</Step>--<Step>-### Verify Installation--After restarting your Nuxt development server or deploying your application, open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that the Rybbit script is loaded.-</Step>-</Steps>--### Custom Event Tracking--Use the `useScriptRybbitAnalytics` composable to track custom events from any component. The returned `proxy` queues calls until the script is ready, so it's safe to call immediately:--```vue-<template>- <button @click="handleAction">Track Important Action</button>-</template>--<script setup>-const { proxy } = useScriptRybbitAnalytics()--function handleAction() {- proxy.event('nuxt_interaction', { detail: 'User clicked important button' })-}-</script>-```--## Alternative: Adding Rybbit via `app.head.script`--If you'd rather not use the Nuxt Scripts module, you can add the Rybbit script directly through your Nuxt configuration.+</Tab>+<Tab value="nuxt.config head">+Add the script to the `app.head.script` array in `nuxt.config.ts`:-<Steps>-<Step>-### Modify `nuxt.config.ts` (or `.js`)--**For Nuxt 3:**--Add the Rybbit script to the `app.head.script` array in your `nuxt.config.ts` file:--```typescript filename="nuxt.config.ts"+```typescript title="nuxt.config.ts"export default defineNuxtConfig({- // ... other configurationsapp: {head: {script: [{- src: 'https://app.rybbit.io/api/script.js',+ src: "https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID",defer: true,- 'data-site-id': 'YOUR_SITE_ID', // Replace with your Site ID},],},},-})+});```-**For Nuxt 2:**--Add the Rybbit script to the `head.script` array in your `nuxt.config.js` file:--```javascript filename="nuxt.config.js"-export default {- // ... other configurations- head: {- // ... other head properties- script: [- {- src: 'https://app.rybbit.io/api/script.js',- defer: true,- 'data-site-id': 'YOUR_SITE_ID', // Replace with your Site ID- },- ],- },-}-```-Ensure you replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard. This method ensures the script is included in the `<head>` of all your pages.+On Nuxt 2 the array is `head.script` at the top level of `nuxt.config.js`, with the same entry.+</Tab>+</Tabs></Step><Step>-### Verify Installation+### Verify installation-After restarting your Nuxt.js development server or deploying your application, open your Rybbit dashboard to check if data is being received. You can also inspect your browser's network tab to confirm that `script.js` is loaded.+<include>../../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **SPA Page View Tracking**: Rybbit's tracking script is designed to automatically detect route changes in Nuxt.js applications and track them as page views. If you find that page views are not being tracked correctly after navigation (which is uncommon for Nuxt), you might need to manually trigger page views using `window.rybbit.pageview()` after each route change. You could use Nuxt's router events or middleware for this if necessary, but test the default behavior first.-</Callout>+## Track custom events++With Nuxt Scripts, use the `useScriptRybbitAnalytics` composable. Its `proxy` queues calls until the script is ready, so it is safe to call immediately:-### Custom Event Tracking+```vue title="components/ActionButton.vue"+<template>+ <button @click="handleAction">Track action</button>+</template>++<script setup>+const { proxy } = useScriptRybbitAnalytics();++function handleAction() {+ proxy.event("nuxt_interaction", { detail: "User clicked the action button" });+}+</script>+```-From any Vue component within your Nuxt.js application, you can track custom events directly via `window.rybbit`:+With the `app.head.script` method, call `window.rybbit` directly and guard it with `import.meta.client`, since components also run on the server (on Nuxt 2 use `process.client`):-```vue+```vue title="components/ActionButton.vue"<template>- <button @click="trackCustomEvent">Track Important Action</button>+ <button @click="handleAction">Track action</button></template><script setup>-function trackCustomEvent() {- if (import.meta.client && window.rybbit) { // Ensure running on client and rybbit exists- window.rybbit.event('nuxt_interaction', { detail: 'User clicked important button' });+function handleAction() {+ if (import.meta.client && window.rybbit) {+ window.rybbit.event("nuxt_interaction", { detail: "User clicked the action button" });}}</script>```-Using `import.meta.client` (Nuxt 3+) or checking `typeof window !== 'undefined'` is good practice before accessing `window` if your component might render or execute logic on the server side. (On Nuxt 2, use the legacy `process.client` flag instead.)++## 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.++## Next steps++<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/vue/vite.mdx b/docs/content/docs/(docs)/guides/vue/vite.mdxindex d62de6156..c2853bf46 100644--- a/docs/content/docs/(docs)/guides/vue/vite.mdx+++ b/docs/content/docs/(docs)/guides/vue/vite.mdx@@ -1,117 +1,92 @@---title: Vue.js (Vite / Client-Side)-description: Integrate Rybbit with your client-side Vue.js application+description: Add Rybbit analytics to your Vue app+category: frameworks+icon: SiVuedotjs----import { Steps, Step } from 'fumadocs-ui/components/steps'-import { Callout } from 'fumadocs-ui/components/callout'+import { Steps, Step } from "fumadocs-ui/components/steps";--This guide explains how to integrate Rybbit with your standard client-side Vue.js Single Page Applications (SPAs), typically built using Vite (e.g., via `npm create vue@latest` or `npm create vite@latest -- --template vue`).--## How to Add Rybbit to Your Client-Side Vue.js App--The recommended and simplest method for client-side Vue applications is to add the Rybbit tracking script directly to your `index.html` file. This ensures the script is loaded early and reliably.--### Adding to `index.html`+A client-side Vue app built with Vite (`npm create vue@latest` or `npm create vite@latest -- --template vue`) serves a single `index.html` at the project root. Add the snippet there and it loads on every route.<Steps><Step>-### Retrieve Your Tracking Script--Navigate to your Rybbit dashboard to obtain your code snippet:+### Get your tracking snippet-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```-Replace `YOUR_SITE_ID` with your actual Site ID.+<include>../../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Locate Your `index.html` File--This file is typically located at the root of your Vite-based Vue project.-</Step>+### Add the snippet to Vue.js-<Step>-### Add the Snippet to `index.html`+Open `index.html` at the root of your project and paste the snippet inside `<head>`:-Open `index.html` and paste the Rybbit tracking snippet just before the closing `</head>` tag or `</body>` tag. Placing it in the `<head>` allows it to load sooner.--```html filename="index.html (Vite)"-<!DOCTYPE html>+```html title="index.html"+<!doctype html><html lang="en"><head>- <meta charset="UTF-8">- <link rel="icon" href="/favicon.ico">- <meta name="viewport" content="width=device-width, initial-scale=1.0">+ <meta charset="UTF-8" />+ <link rel="icon" href="/favicon.ico" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><title>My Vue App</title>- <!-- Rybbit Tracking Snippet -->- <script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer- ></script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script></head><body><div id="app"></div><script type="module" src="/src/main.js"></script>- <!-- Or place script here, before </body> --></body></html>```-Ensure `YOUR_SITE_ID` is replaced with your actual Site ID.++Placing it just before `</body>` also works, but `<head>` lets the script start loading sooner.</Step><Step>-### Verify Installation+### Verify installation-Deploy your application and check your Rybbit dashboard for incoming data. You can also inspect your browser's network tab to confirm that `script.js` is loaded.+<include>../../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **SPA Page View Tracking**: Rybbit's script is designed to automatically track route changes in SPAs using Vue Router. If page views aren't tracked correctly after navigation, you might need to manually trigger them using `window.rybbit.pageview()` after each route change. This can be done using Vue Router's navigation guards:- ```javascript- // Example with Vue Router in your router setup file (e.g., src/router/index.js)- import { createRouter, createWebHistory } from 'vue-router';- // ... your routes ...+## Track custom events++Call `window.rybbit.event()` from any component or method:++```vue title="src/components/ActionButton.vue"+<template>+ <button @click="trackAction">Track action</button>+</template>++<script setup>+function trackAction() {+ if (window.rybbit) {+ window.rybbit.event("custom_vue_action", { detail: "User performed an action" });+ }+}+</script>+```++## 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:++ ```javascript title="src/router/index.js"+ import { createRouter, createWebHistory } from "vue-router";const router = createRouter({history: createWebHistory(import.meta.env.BASE_URL),- routes: [ /* ... your routes ... */ ]+ routes: [/* your routes */],});- router.afterEach((to, from) => {- if (window.rybbit && typeof window.rybbit.pageview === 'function') {+ router.afterEach(() => {+ if (window.rybbit) {window.rybbit.pageview();}});export default router;```- Always test the default behavior first, as manual tracking might not be necessary.-</Callout>--## Custom Event Tracking-From any Vue component or method, you can track custom events:+## Next steps-```vue-<template>- <button @click="trackCustomEvent">Track Action</button>-</template>--<script setup>-function trackCustomEvent() {- if (window.rybbit && typeof window.rybbit.event === 'function') {- window.rybbit.event('custom_vue_action', { detail: 'User performed a client-side Vue action' });- }-}-</script>-```-Always check if `window.rybbit` and its methods are available before calling them.+<include>../../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/webflow.mdx b/docs/content/docs/(docs)/guides/webflow.mdxindex ce5ba1df7..e11bb8555 100644--- a/docs/content/docs/(docs)/guides/webflow.mdx+++ b/docs/content/docs/(docs)/guides/webflow.mdx@@ -1,112 +1,75 @@----title: "Webflow"-description: "Enable analytics, custom events, and more on your Webflow site with Rybbit."+title: Webflow+description: Add Rybbit analytics to your Webflow site+category: builders+icon: SiWebflow----import { Step, Steps } from "fumadocs-ui/components/steps";-import { Callout } from "fumadocs-ui/components/callout";+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-Rybbit enables you to collect analytics, capture custom events, and more on your Webflow site.--## How to Add Rybbit to Webflow+Webflow accepts custom `<head>` code either site-wide in **Site settings β Custom code** or per page in the page settings. Either way the code only reaches the live site when you publish.<Steps><Step>-### Retrieve Your Tracking Script+### Get your tracking snippet-Navigate to your Rybbit dashboard to obtain your code snippet.+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-```html-<script- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID"- defer-></script>-```+<Step>+### Add the snippet to Webflow++<Tabs items={["Site-wide", "Single page"]}>+<Tab value="Site-wide">+1. Open your project and go to **Site settings β Custom code**.+2. Paste the snippet into **Head code**.+3. Click **Save**, then **Publish** the site.+</Tab>+<Tab value="Single page">+Use this when you only want to track specific pages.++1. In the Designer, open the page's **Settings** (cog icon next to the page name).+2. Scroll to **Custom code** and paste the snippet into **Inside `<head>` tag**.+3. Click **Save**, then **Publish** the site.+</Tab>+</Tabs></Step><Step>-### Add the Snippet to Your Webflow Project+### Verify installation-- In your Webflow project, go to **Site settings > Custom code**.-- Paste your snippet into the **Head code** section.-- Save and publish your changes.+<include>../../../partials/guides/verify.mdx</include></Step></Steps>-<Callout type="info">- **Page View Tracking in Webflow**:- - **Standard Navigation**: For standard page-to-page navigation in Webflow, Rybbit will track each new page load automatically.- - **Interactions & Animations**: If you use Webflow interactions that change content significantly without changing the URL (e.g., showing/hiding sections to simulate tabs or multi-step forms on a single page), Rybbit will only track the initial page load. For these "virtual" page views, you would need to use custom event tracking to mark those interactions.- - **Single-Page Sites**: If your Webflow site is a single-page design with sections, only one page view will be tracked unless you implement custom event tracking for section views.-</Callout>--## Custom Event Tracking in Webflow--You can track custom events in Webflow by adding custom JavaScript code, either in the **Custom Code** section of your site settings (for global scripts) or within an **Embed** element on a specific page.--**Example: Tracking a button click**--1. **Give your button an ID:**- * Select the button element in the Webflow Designer.- * Go to the **Settings** panel (cog icon).- * Under **General**, set a unique **ID** for the button (e.g., `my-special-button`).--2. **Add Custom JavaScript:**- You can add this script in **Site Settings > Custom Code > Footer Code** to make it available globally, or in an Embed element on the page where the button exists.-- ```html- <script type="text/javascript">- document.addEventListener('DOMContentLoaded', function() {- var specialButton = document.getElementById('my-special-button');- if (specialButton) {- specialButton.addEventListener('click', function() {- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('webflow_button_click', {- button_id: 'my-special-button',- button_text: specialButton.textContent || specialButton.innerText,- page_path: window.location.pathname- });- }- });- }- });- </script>- ```--**Example: Tracking a form submission**--1. **Give your form an ID:**- * Select the Form Block element.- * Go to the **Settings** panel.- * Set a unique **ID** (e.g., `contact-form`).--2. **Add Custom JavaScript (in Footer Code or Embed):**-- ```html- <script type="text/javascript">- document.addEventListener('DOMContentLoaded', function() {- var contactForm = document.getElementById('contact-form');- if (contactForm) {- contactForm.addEventListener('submit', function() {- // It's often good to track *after* successful submission if Webflow provides a callback.- // For a simple submit click, this is how you'd do it.- // For Webflow's native form handling, you might need to hook into its success state if possible,- // or track the click on the submit button itself.- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('webflow_form_submit', {- form_id: 'contact-form',- // You can try to get form field values here if needed, but be mindful of PII.- });- }- });- }+## Track custom events++Give the element an **ID** in the Designer (**Settings** panel β **General** β **ID**), then attach a listener in **Site settings β Custom code β Footer code** or in an **Embed** element on that page:++```html+<script>+ document.addEventListener("DOMContentLoaded", function () {+ var button = document.getElementById("my-special-button");+ if (!button) return;+ button.addEventListener("click", function () {+ window.rybbit?.event("button_click", {+ button_id: "my-special-button",+ page_path: window.location.pathname,+ });});- </script>- ```+ });+</script>+```++The same pattern works for a Form Block's `submit` event. Webflow handles form submission itself, so this fires on the submit attempt, not on confirmed success.++## Troubleshooting++- **Changes not showing on the live site**: custom code is staged until you **Publish**. Check the published site, not the Designer preview.+- **Interactions that show or hide sections** without changing the URL produce a single pageview. Track those states as custom events, or call `window.rybbit.pageview()` from your own script when they appear.+- **Scripts that read the DOM** belong in **Footer code**, not **Head code**, so the elements exist when they run.-<Callout type="warn">- When adding custom JavaScript in Webflow, ensure it's placed correctly (usually in the Footer Code for scripts that need the DOM to be ready) and test thoroughly. Webflow's own interactions might sometimes conflict or require specific timing for custom scripts.-</Callout>+## Next steps-By using these methods, you can enhance Rybbit's tracking on your Webflow site beyond basic page views.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/weebly.mdx b/docs/content/docs/(docs)/guides/weebly.mdxnew file mode 100644index 000000000..bc45be6e6--- /dev/null+++ b/docs/content/docs/(docs)/guides/weebly.mdx@@ -0,0 +1,45 @@+---+title: Weebly+description: Add Rybbit analytics to your Weebly site+category: builders+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Weebly (now part of Square) has site-wide **Header Code** and **Footer Code** fields under its SEO settings. Header code is printed into the `<head>` of every page, so the snippet goes there and no theme edits are needed.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Weebly++1. Open your site in the Weebly editor and go to **Settings > SEO**.+2. Paste the snippet into **Header Code** and click **Save**.+3. Click **Publish**. Header code changes only reach the live site after you publish.++If your editor has no **Settings** tab, the same header-code option is under **Website > General Settings** in the Square dashboard.++Site-level header code covers every page, including blog posts. Each page also has its own **Header Code** box in its page settings; that one is for page-specific code and is not needed for the snippet.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Snippet saved but not in the page source**: the site was not republished. Click **Publish** after every change to header code.+- **Snippet appears twice**: it was added both site-wide and on individual pages. Keep only the site-level entry under **Settings > SEO**.+- **Footer Code instead of Header Code**: both fields are included on every page, so the snippet works from either, but the footer loads later and misses visitors who leave early.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/wix.mdx b/docs/content/docs/(docs)/guides/wix.mdxindex aadfd1bb7..fc7b1b3d8 100644--- a/docs/content/docs/(docs)/guides/wix.mdx+++ b/docs/content/docs/(docs)/guides/wix.mdx@@ -1,85 +1,50 @@----title: "Wix"-description: "Integrate Rybbit Analytics with your Wix website using custom code snippets."+title: Wix+description: Add Rybbit analytics to your Wix site+category: builders+icon: SiWix----import { Steps, Step } from 'fumadocs-ui/components/steps';+import { Steps, Step } from "fumadocs-ui/components/steps";import { Callout } from "fumadocs-ui/components/callout";-Integrating Rybbit Analytics with your Wix website involves adding a custom code snippet to your site's tracking tools.+Wix adds third-party scripts through the **Custom Code** panel in the site dashboard, where you choose which pages load the code and where in the document it goes.-<Steps>-<Step>-### Get Your Tracking Script--First, you'll need your Rybbit tracking script. You can find this in your Rybbit dashboard under **Site Settings > Tracking Script**. It will look something like this:--```html-<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>-```--Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard.-</Step>--<Step>-### Go to Wix Dashboard--Log in to your Wix account and select the site you want to track.--From your site's dashboard, navigate to:--- **Settings** (usually in the left-hand sidebar)-</Step>--<Step>-### Access Tracking Tools / Custom Code--In the Settings menu, look for a section related to tracking or advanced settings. This is often called:--- **Tracking Tools & Analytics** (under "Marketing & SEO" or a similar category)-- Or, **Custom Code** (sometimes under "Advanced Settings")--<Callout type="info">- To add custom code, you'll need a Wix Premium plan and a connected domain. This feature is typically not available on free Wix plans.+<Callout type="warn">+Custom code requires a **Wix Premium plan** and a **connected domain**. It is not available on free Wix sites.</Callout>-</Step>+<Steps><Step>-### Add New Custom Code--Once in the Tracking Tools or Custom Code section:+### Get your tracking snippet-- Click on **+ New Tool** or **+ Add Custom Code**.-- Choose **Custom** from the list of options if prompted.+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Configure the Custom Code--You'll be presented with a form to add your code:--- **Paste your Rybbit tracking script** into the main code snippet box.-- **Name your code:** Give it a recognizable name, like "Rybbit Analytics".-- **Add Code to Pages:** Select **All pages** to track your entire site.- - You might have an option to **Load code once** or **Load code on each new page**. Choose the option that best reflects loading the script on every page view.-- **Place Code in:** Choose **Body - end**. This is generally recommended for analytics scripts to avoid impacting perceived page load speed. Some Wix versions might offer "Head" or "Body - start" as well. "Body - end" is usually the best choice.+### 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**.+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.+6. Under **Place Code in**, choose **Head**.+7. Click **Apply**.</Step><Step>-### Apply Changes+### Verify installation-Click **Apply** or **Save** to add the custom code to your site.+<include>../../../partials/guides/verify.mdx</include></Step>+</Steps>-<Step>-### Verify Integration+## Troubleshooting-After applying the changes, Rybbit Analytics should start tracking visitors on your Wix site.+- **Custom Code is missing from Settings**: the site has no Premium plan or no connected domain. Both are required before the panel appears.+- **Duplicate pageviews**: the code was added with **Load code on each new page**. Edit the entry and switch to **Load code once**.-- Open your Wix website in a new browser tab or incognito window.-- Navigate through a few pages.-- Check your Rybbit dashboard for incoming data. It might take a few minutes for the first events to appear.-</Step>-</Steps>+## Next steps-That's it! Rybbit Analytics is now integrated with your Wix website.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/woocommerce.mdx b/docs/content/docs/(docs)/guides/woocommerce.mdxindex 634a49b43..27b9771e5 100644--- a/docs/content/docs/(docs)/guides/woocommerce.mdx+++ b/docs/content/docs/(docs)/guides/woocommerce.mdx@@ -1,220 +1,165 @@---title: WooCommerce-description: Integrate Rybbit Analytics with your WooCommerce store+description: Add Rybbit analytics to your WooCommerce store+category: ecommerce+icon: SiWoocommerce----import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+WooCommerce runs on WordPress, so the snippet goes in the same way as on any WordPress site. What this guide adds is the WooCommerce action hooks that send purchases, add-to-carts, product views and checkouts to Rybbit as custom events.-This guide explains how to integrate Rybbit with your WooCommerce store (running on WordPress) to track e-commerce events like product views, add to carts, and purchases, in addition to standard page view analytics.+<Steps>+<Step>+### Get your tracking snippet-## Prerequisites+<include>../../../partials/guides/get-snippet.mdx</include>+</Step>-1. **Rybbit Installed on WordPress**: Ensure you have already installed the Rybbit tracking script on your WordPress site using one of the methods described in our [WordPress integration guide](/docs/guides/wordpress). This guide focuses on adding e-commerce event tracking.-2. **Access to `functions.php` or Custom Plugin**: You'll need to add PHP snippets. The recommended way is via your child theme's `functions.php` file or a custom plugin to avoid changes being overwritten by theme updates.+<Step>+### Add the snippet to WooCommerce-## Tracking E-commerce Events+Follow the [WordPress guide](/docs/guides/wordpress) to add the snippet. If you plan to track the e-commerce events below, use the `functions.php` or mini-plugin method there: the event hooks are PHP and belong in the same file.-WooCommerce provides various action hooks that allow you to trigger JavaScript when specific e-commerce events occur. We'll use these to send data to Rybbit.+```php+function rybbit_add_tracking_script() {+ ?>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>+ <?php+}+add_action( 'wp_head', 'rybbit_add_tracking_script' );+```+</Step>-<Callout type="warning">- The following PHP code snippets should be added to your **child theme's `functions.php` file** or a **custom site-specific plugin**. Modifying your parent theme's `functions.php` directly is not recommended as changes will be lost upon theme updates.+<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++WooCommerce fires PHP action hooks at each stage of the shopping flow. The snippets below print a small inline script from those hooks. They wait for `DOMContentLoaded` because the tracking script is loaded with `defer`, so `window.rybbit` does not exist while the page is still parsing.++<Callout type="warn">+Add these to your **child theme's `functions.php`** or a site-specific plugin, never to the parent theme.</Callout>-### 1. View Product (`view_item`)+#### Purchase-Track when a user views a single product page.+`woocommerce_thankyou` fires on the order-received page with the order ID.```php-// Add to your child theme's functions.php or a custom plugin-add_action( 'woocommerce_after_single_product_summary', 'rybbit_track_view_product', 10 );-function rybbit_track_view_product() {- if ( ! is_product() ) { // Ensure it's a single product page+add_action( 'woocommerce_thankyou', 'rybbit_track_purchase', 10, 1 );+function rybbit_track_purchase( $order_id ) {+ $order = wc_get_order( $order_id );+ if ( ! $order ) {return;}- global $product;- if ( ! $product instanceof WC_Product ) {- return;+ $items = array();+ foreach ( $order->get_items() as $item ) {+ $product = $item->get_product();+ $items[] = array(+ 'item_id' => $product && $product->get_sku() ? $product->get_sku() : $item->get_product_id(),+ 'item_name' => $item->get_name(),+ 'price' => (float) $order->get_line_subtotal( $item, false, false ),+ 'quantity' => (int) $item->get_quantity(),+ );}- $product_data = array(- 'item_id' => $product->get_sku() ? $product->get_sku() : $product->get_id(),- 'item_name' => $product->get_name(),- 'price' => (float) $product->get_price(),- 'currency' => get_woocommerce_currency(),+ $purchase = array(+ 'transaction_id' => $order->get_order_number(),+ 'value' => (float) $order->get_total(),+ 'tax' => (float) $order->get_total_tax(),+ 'shipping' => (float) $order->get_shipping_total(),+ 'currency' => $order->get_currency(),+ 'items' => $items,);?>- <script type="text/javascript">- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('view_item', <?php echo json_encode($product_data); ?>);- }+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ window.rybbit.event('purchase', <?php echo wp_json_encode( $purchase ); ?>);+ });</script><?php}```-### 2. Add to Cart (`add_to_cart`)+Event properties are limited to 2048 characters of JSON, so trim `items` to ID, quantity and price, or drop it, for stores with large orders.-Track when a user adds a product to their cart. This example uses a JavaScript approach triggered after the "Add to Cart" button on single product pages. For AJAX add-to-carts (e.g., on archive pages), a JavaScript event listener on `$(document.body).on('added_to_cart', ...)` might be more robust.+#### Add to cart++Two hooks cover both paths: the product-page form submit, and WooCommerce's `added_to_cart` jQuery event for AJAX buttons on shop and category pages.```php-// Add to your child theme's functions.php or a custom plugin-add_action( 'woocommerce_after_add_to_cart_button', 'rybbit_track_add_to_cart_script' );-function rybbit_track_add_to_cart_script() {+// Single product page: track on form submit+add_action( 'woocommerce_after_add_to_cart_button', 'rybbit_track_add_to_cart' );+function rybbit_track_add_to_cart() {global $product;if ( ! $product instanceof WC_Product ) {return;}-- $product_data = array(- 'item_id' => $product->get_sku() ? $product->get_sku() : $product->get_id(),- 'item_name' => $product->get_name(),- 'price' => (float) $product->get_price(),- 'currency' => get_woocommerce_currency(),- // Quantity is typically 1 here, but can be dynamic if your theme supports it before this hook+ $data = array(+ 'item_id' => $product->get_sku() ? $product->get_sku() : $product->get_id(),+ 'item_name' => $product->get_name(),+ 'price' => (float) $product->get_price(),+ 'currency' => get_woocommerce_currency(),);?>- <script type="text/javascript">- document.addEventListener('DOMContentLoaded', function() {- const form = document.querySelector('form.cart');- if (form) {- form.addEventListener('submit', function() {- // Attempt to get quantity, default to 1- let quantity = 1;- const quantityInput = form.querySelector('input.qty');- if (quantityInput && quantityInput.value) {- quantity = parseInt(quantityInput.value, 10);- }-- if (typeof window.rybbit !== 'undefined') {- const eventData = <?php echo json_encode($product_data); ?>;- eventData.quantity = quantity > 0 ? quantity : 1;- window.rybbit.event('add_to_cart', eventData);- }- });- }- });- </script>- <?php-}--// For AJAX add to cart events (e.g., on shop/category pages)-add_action( 'wp_footer', 'rybbit_ajax_add_to_cart_tracker' );-function rybbit_ajax_add_to_cart_tracker() {- if ( is_admin() ) return;- ?>- <script type="text/javascript">- jQuery(document.body).on('added_to_cart', function(event, fragments, cart_hash, $button) {- if (typeof window.rybbit !== 'undefined' && $button && $button.length) {- const productId = $button.data('product_id');- const quantity = $button.data('quantity') || 1; // Or $button.closest('.product').find('input.qty').val()- // Note: Getting full product details here via AJAX might be needed for price, name, SKU- // This example sends basic info. For more details, you might need another AJAX call or pass data via $button.data attributes- window.rybbit.event('add_to_cart', {- item_id: productId,- quantity: quantity,- source: 'ajax_add_to_cart'- // Consider adding more product details if readily available or via a separate AJAX call- });- }+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ var form = document.querySelector('form.cart');+ if (!form) return;+ form.addEventListener('submit', function () {+ 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);});+ });</script><?php}-```--### 3. Begin Checkout (`begin_checkout`)-Track when a user proceeds to the checkout page.--```php-// Add to your child theme's functions.php or a custom plugin-add_action( 'woocommerce_before_checkout_form', 'rybbit_track_begin_checkout', 5 );-function rybbit_track_begin_checkout() {- if ( is_admin() || ! is_checkout() ) return;-- $cart = WC()->cart;- if ( ! $cart ) return;-- $items = [];- foreach ( $cart->get_cart() as $cart_item_key => $cart_item ) {- $_product = apply_filters( 'woocommerce_cart_item_product', $cart_item['data'], $cart_item, $cart_item_key );- $items[] = array(- 'item_id' => $_product->get_sku() ? $_product->get_sku() : $_product->get_id(),- 'item_name' => $_product->get_name(),- 'price' => (float) $_product->get_price(),- 'quantity' => (int) $cart_item['quantity'],- );+// AJAX add-to-cart buttons on shop and category pages+add_action( 'wp_footer', 'rybbit_track_ajax_add_to_cart' );+function rybbit_track_ajax_add_to_cart() {+ if ( is_admin() ) {+ return;}-- $checkout_data = array(- 'currency' => get_woocommerce_currency(),- 'value' => (float) $cart->get_total( 'edit' ), // Get total without formatting- 'items' => $items,- );?>- <script type="text/javascript">- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('begin_checkout', <?php echo json_encode($checkout_data); ?>);- }+ <script>+ jQuery(document.body).on('added_to_cart', function (event, fragments, cartHash, $button) {+ if (!$button || !$button.length) return;+ window.rybbit.event('add_to_cart', {+ item_id: $button.data('product_id'),+ quantity: $button.data('quantity') || 1,+ source: 'ajax_add_to_cart'+ });+ });</script><?php}```-### 4. Purchase (`purchase`)+The AJAX handler only sees the product ID and quantity from the button's `data-*` attributes. Add attributes to the button in your theme if you also want name and price.-Track when a purchase is completed (on the "Thank You" page).+#### View product and begin checkout-```php-// Add to your child theme's functions.php or a custom plugin-add_action( 'woocommerce_thankyou', 'rybbit_track_purchase', 10, 1 );-function rybbit_track_purchase( $order_id ) {- if ( ! $order_id ) {- return;- }- $order = wc_get_order( $order_id );- if ( ! $order ) {- return;- }+The same pattern works for the remaining hooks:- $items = [];- foreach ( $order->get_items() as $item_id => $item ) {- $product = $item->get_product();- $items[] = array(- 'item_id' => $product ? ($product->get_sku() ? $product->get_sku() : $product->get_id()) : $item->get_product_id(),- 'item_name' => $item->get_name(),- 'price' => (float) $order->get_line_subtotal( $item, false, false ), // Price for the line item- 'quantity' => (int) $item->get_quantity(),- );- }+- `woocommerce_after_single_product_summary` runs on product pages. Guard with `is_product()`, then send `view_item` with `item_id`, `item_name`, `price` and `currency` from the global `$product`.+- `woocommerce_before_checkout_form` runs on the checkout page. Build `begin_checkout` from `WC()->cart`: loop over `get_cart()` for the items (each `$cart_item['data']` is the product, `$cart_item['quantity']` the quantity), with `value` from `$cart->get_total( 'edit' )` and `currency` from `get_woocommerce_currency()`.- $purchase_data = array(- 'transaction_id' => $order->get_order_number(),- 'value' => (float) $order->get_total(),- 'tax' => (float) $order->get_total_tax(),- 'shipping' => (float) $order->get_shipping_total(),- 'currency' => $order->get_currency(),- 'items' => $items,- );- ?>- <script type="text/javascript">- if (typeof window.rybbit !== 'undefined') {- window.rybbit.event('purchase', <?php echo json_encode($purchase_data); ?>);- }- </script>- <?php-}-```+## Troubleshooting-## Important Considerations+- **Events fire before the tracker loads**: keep the tracking snippet in `wp_head` and the `DOMContentLoaded` wrapper in place. Deferred scripts run before `DOMContentLoaded`, so `window.rybbit` is ready by then; calling it from a bare inline script drops the event.+- **AJAX carts and mini-carts**: themes that update the cart without a page load never hit the PHP hooks, so rely on the `added_to_cart` listener for those and test each add-to-cart path.+- **Other analytics plugins**: plugins that also print e-commerce data layers can conflict. Test with a real order after enabling both.-* **Script Loading Order**: Ensure the main Rybbit tracking script (added via the WordPress integration guide) is loaded before these event-specific scripts attempt to call `window.rybbit`. Placing the main script in the `<head>` usually ensures this.-* **Data Accuracy**: The product data (SKU, name, price) retrieved in these examples depends on your WooCommerce setup and product configuration. Test thoroughly.-* **AJAX Operations**: For themes or plugins that use AJAX heavily (e.g., AJAX add to cart, mini-cart updates), you might need more sophisticated JavaScript event listeners rather than relying solely on PHP action hooks that fire on page load. The AJAX add-to-cart example provides a starting point.-* **Performance**: While these snippets are generally lightweight, outputting many inline scripts can have a minor impact. For very high-traffic sites, consider consolidating JavaScript or using more advanced techniques if performance becomes a concern.-* **Plugin Conflicts**: Test for conflicts if you are using other analytics or tracking plugins.+## Next steps-By implementing these tracking snippets, you can gain valuable insights into your WooCommerce store's performance using Rybbit.\ No newline at end of file+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/wordpress.mdx b/docs/content/docs/(docs)/guides/wordpress.mdxindex 9a5ea152d..7137aa196 100644--- a/docs/content/docs/(docs)/guides/wordpress.mdx+++ b/docs/content/docs/(docs)/guides/wordpress.mdx@@ -1,265 +1,111 @@---title: WordPress-description: Integrate Rybbit Analytics with your WordPress site+description: Add Rybbit analytics to your WordPress site+category: cms+icon: SiWordpress----import { Tabs, Tab } from 'fumadocs-ui/components/tabs';-import { Steps, Step } from 'fumadocs-ui/components/steps';-import { Callout } from 'fumadocs-ui/components/callout';+import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";+import { Tabs, Tab } from "fumadocs-ui/components/tabs";-You can integrate Rybbit into your WordPress site to track user behavior and gather analytics. There are several ways to do this depending on whether you're using a hosted WordPress.com site or a self-hosted WordPress.org installation.--<Callout type="info">-We recommend using the JavaScript snippet below instead of a plain `<script>` tag. Some WordPress plugins and page builders strip `data-*` attributes from HTML, which can break tracking. The JavaScript approach avoids this issue.-</Callout>--## Quick Start--The easiest method for most users is the **WPCode plugin** (formerly Insert Headers and Footers). This works on both WordPress.com (Business plan+) and self-hosted WordPress.org sites.+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.<Steps><Step>-### Install WPCode Plugin--In your WordPress dashboard, go to **Plugins > Add New** and search for "WPCode". Install and activate the plugin.--Alternatively, download from [WordPress.org](https://wordpress.org/plugins/insert-headers-and-footers/).-</Step>--<Step>-### Add the Tracking Script--1. Go to **Code Snippets > Header & Footer** (or **Settings > Insert Headers and Footers** in older versions)-2. Paste this snippet into the **Header** section:--```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';- s.defer = true;- document.head.appendChild(s);-})();-</script>-```+### Get your tracking snippet-3. Replace `YOUR_SITE_ID` with your actual Site ID from your Rybbit dashboard-4. Click **Save Changes**+<include>../../../partials/guides/get-snippet.mdx</include></Step><Step>-### Verify Installation--Visit your site in a new browser tab, then check your Rybbit dashboard to confirm data is being received.-</Step>-</Steps>+### Add the snippet to WordPress-## Alternative Methods+<Callout type="warn">+If you edit theme files, edit a **child theme**. Changes to a parent theme's `functions.php` or `header.php` are lost on the next theme update.+</Callout>-<Tabs items={['functions.php', 'header.php', 'Manual Plugin']}>+<Tabs items={["WPCode", "functions.php", "header.php", "Mini plugin"]}><Tab>-### Add via functions.php+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.-For self-hosted WordPress, you can add the script via your theme's `functions.php` file.--<Callout type="warn">-**Use a child theme!** If you modify the parent theme's `functions.php`, your changes will be lost when the theme updates.-</Callout>+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).+3. Paste the snippet into the **Header** box and click **Save Changes**.+</Tab>-1. Go to **Appearance > Theme File Editor**-2. Select your child theme's `functions.php`-3. Add this code at the end of the file:+<Tab>+1. Go to **Appearance > Theme File Editor** and open your child theme's `functions.php`.+2. Add this to the end of the file, replacing `YOUR_SITE_ID`:```php-function add_rybbit_analytics() {+function rybbit_add_tracking_script() {?>- <script>- (function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';- s.defer = true;- document.head.appendChild(s);- })();- </script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script><?php}-add_action('wp_head', 'add_rybbit_analytics');+add_action( 'wp_head', 'rybbit_add_tracking_script' );```-4. Replace `YOUR_SITE_ID` with your actual Site ID and save+3. Save the file.</Tab><Tab>-### Modify header.php--You can directly edit your theme's `header.php` file to add the script.--<Callout type="warn">-**Use a child theme!** Changes to the parent theme's `header.php` will be lost on theme updates.-</Callout>--1. Go to **Appearance > Theme File Editor**-2. Open `header.php`-3. Find the closing `</head>` tag and paste this script just before it:+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:```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';- s.defer = true;- document.head.appendChild(s);-})();-</script>+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script></head>```-4. Replace `YOUR_SITE_ID` with your actual Site ID and save+3. Save the file.</Tab><Tab>-### Create a Simple Plugin--Creating a small plugin ensures your tracking code persists through theme changes.+A one-file plugin keeps the snippet in place through theme changes without touching theme files.-1. Connect to your site via FTP/SFTP or use a file manager plugin-2. Navigate to `/wp-content/plugins/`-3. Create a new folder called `rybbit-analytics`-4. Inside that folder, create a file called `rybbit-analytics.php` with this content:+1. Over FTP/SFTP or a file-manager plugin, create the folder `/wp-content/plugins/rybbit-analytics/`.+2. Inside it, create `rybbit-analytics.php` with this content, replacing `YOUR_SITE_ID`:```php<?php/*** Plugin Name: Rybbit Analytics- * Description: Adds Rybbit Analytics tracking to your WordPress site+ * Description: Adds the Rybbit tracking script to every page* Version: 1.0*/function rybbit_add_tracking_script() {?>- <script>- (function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';- s.defer = true;- document.head.appendChild(s);- })();- </script>+ <script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script><?php}-add_action('wp_head', 'rybbit_add_tracking_script');+add_action( 'wp_head', 'rybbit_add_tracking_script' );```-5. Replace `YOUR_SITE_ID` with your actual Site ID-6. Go to **Plugins** in WordPress and activate "Rybbit Analytics"+3. Go to **Plugins** and activate **Rybbit Analytics**.</Tab></Tabs>-## Troubleshooting--### Script not loading--**Check if the script is in the page source:**-1. Visit your site-2. Right-click and select "View Page Source"-3. Search for `rybbit` - you should see the script tag--If the script is missing:-- Make sure you saved your changes-- Clear any caching plugins (WP Super Cache, W3 Total Cache, LiteSpeed Cache, etc.)-- Clear your CDN cache if using one (Cloudflare, etc.)--### Caching plugin conflicts--Many WordPress caching plugins aggressively cache pages. After adding Rybbit:--1. **Clear all caches:**- - Your caching plugin's cache- - Any CDN cache (Cloudflare, etc.)- - Browser cache (Ctrl+Shift+R or Cmd+Shift+R)--2. **Exclude the script from optimization:**- Some optimization plugins try to defer, delay, combine, or minify scripts. "Delay JavaScript execution" features in particular rebuild the script tag and drop its `data-*` attributes, which is why the snippets on this page pass the site ID in the URL (`?siteId=`) instead of a `data-site-id` attribute. If Rybbit still isn't working, exclude `app.rybbit.io` in these plugins:- - **Autoptimize**: Add `app.rybbit.io` to the exclusion list- - **WP Rocket**: Exclude from JavaScript optimization and from "Delay JavaScript execution"- - **Perfmatters / FlyingPress**: Add `app.rybbit.io` to the delay-JS exclusions- - **LiteSpeed Cache**: Add to JS excludes- - **SG Optimizer**: Exclude from combine/minify--### Page builder issues--If you're using a page builder like Elementor, Divi, WPBakery, or Beaver Builder, use the **WPCode plugin method** above rather than adding code through the page builder's custom HTML blocks. Page builders often sanitize HTML and may strip attributes from script tags.--### Security plugin blocking the script--Security plugins like Wordfence or Sucuri may block external scripts. Add `app.rybbit.io` to your allowlist if tracking isn't working.--### WordPress.com limitations--- **Free/Personal/Premium plans**: Cannot add custom JavaScript. You'll need to upgrade to a Business or eCommerce plan.-- **Business/eCommerce plans**: Use the WPCode plugin method above.--### Ad blockers--Some visitors use ad blockers that block analytics scripts. This is expected behavior and will result in those visits not being tracked. If you're testing and see no data, try:-- Disabling your ad blocker temporarily-- Testing in an incognito/private window-- Testing from a different device--## Script Options--You can customize the tracking script with additional `data-*` attributes. When using the JavaScript snippet approach, add them with `s.setAttribute()`. For a full list of options, see the [Tracking Script reference](/docs/script).--### Skip Pages from Tracking--Use `data-skip-patterns` to exclude certain pages (like admin or preview pages) from being tracked. Supports `*` (single segment) and `**` (multiple segments) wildcards.--```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';- s.defer = true;- s.setAttribute('data-skip-patterns', '["/wp-admin/**", "/preview/**"]');- document.head.appendChild(s);-})();-</script>-```--### Mask Sensitive URLs--Use `data-mask-patterns` to track pageviews on sensitive pages without recording the actual URL path. The URL is replaced with the pattern itself in your analytics data.+Running WooCommerce? Once the snippet is in place, see the [WooCommerce guide](/docs/guides/woocommerce) for purchase and add-to-cart events.+</Step>-```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';- s.defer = true;- s.setAttribute('data-mask-patterns', '["/my-account/**", "/orders/*/details"]');- document.head.appendChild(s);-})();-</script>-```+<Step>+### Verify installation-### Session Replay Privacy+<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>-If you have session replay enabled, you can mask or block sensitive content from recordings:+## Troubleshooting-```html-<script>-(function() {- var s = document.createElement('script');- s.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';- s.defer = true;- s.setAttribute('data-replay-block-selector', '.sensitive-content, #payment-form');- s.setAttribute('data-replay-mask-text-selectors', '[".user-name", "#email"]');- s.setAttribute('data-replay-mask-all-inputs', 'true');- document.head.appendChild(s);-})();-</script>-```+- **Caching plugins**: after saving the snippet, purge WP Super Cache, W3 Total Cache, LiteSpeed Cache or whichever cache plugin you run, plus any CDN cache such as Cloudflare, before you check the page source.+- **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.-## Tracking WooCommerce Events+## Next steps-If you're running a WooCommerce store, see our [WooCommerce guide](/docs/guides/woocommerce) for tracking purchases and other e-commerce events.+<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/docs/(docs)/guides/zola.mdx b/docs/content/docs/(docs)/guides/zola.mdxnew file mode 100644index 000000000..3ad08952f--- /dev/null+++ b/docs/content/docs/(docs)/guides/zola.mdx@@ -0,0 +1,65 @@+---+title: Zola+description: Add Rybbit analytics to your Zola site+category: static+icon: SiZola+---++import { Steps, Step } from "fumadocs-ui/components/steps";++Zola pages extend a base Tera template, normally `templates/base.html`, so the snippet goes in that file's `<head>`. Keep the site ID in the `[extra]` section of `config.toml`, which every template can read as `config.extra`.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to Zola++1. Add your site ID under `[extra]` in `config.toml`. `rybbit_instance_url` is only needed if you self-host:++ ```toml title="config.toml"+ [extra]+ rybbit_site_id = "YOUR_SITE_ID"+ rybbit_instance_url = "https://app.rybbit.io"+ ```++2. Open `templates/base.html` and add the tag inside `<head>`. The `config.mode` check keeps the script out of `zola serve`, so local development is not tracked:++ ```html title="templates/base.html"+ <head>+ ...+ {% if config.mode == "build" %}+ <script src="{{ config.extra.rybbit_instance_url }}/api/script.js?siteId={{ config.extra.rybbit_site_id }}" defer></script>+ {% endif %}+ </head>+ ```++ If a theme owns `base.html`, copy it from `themes/<theme>/templates/base.html` into your own `templates/` directory first. A template in your site with the same name overrides the theme's copy, so the theme can be updated without losing the change.++3. Build and deploy the generated `public/` directory:++ ```bash+ zola build+ ```+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Troubleshooting++- **Snippet missing from the page source**: `zola serve` sets `config.mode` to `serve`, so the guard removes the tag. Check the output of `zola build` instead.+- **`config.mode` is not defined**: older Zola releases do not expose it. Upgrade, or drop the `if` block and accept local pageviews.+- **Pages without the tag**: templates that do not `{% extends "base.html" %}` (a custom `404.html`, or a section template that builds its own `<head>`) need the tag added separately.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/partials/guides/README.md b/docs/content/partials/guides/README.mdnew file mode 100644index 000000000..983db30be--- /dev/null+++ b/docs/content/partials/guides/README.md@@ -0,0 +1,45 @@+# Integration guide standard++Every page under `content/docs/(docs)/guides/` follows `TEMPLATE.mdx` in this folder.+`npm run lint:guides` checks every guide against the rules below and runs in CI.++## Rules++1. **Frontmatter**: `title` is the platform name as the vendor spells it. `description` is+ `Add Rybbit analytics to your <Platform> site` (use `app`, `store`, `docs`, `blog` when+ that is the better noun). `category` is one of the values in `scripts/check-guides.mjs`.+ `icon` is an `@icons-pack/react-simple-icons` export name (`SiWordpress`); omit it when+ the brand has no icon.+2. **Skeleton**: intro paragraph, then exactly three `<Step>`s titled+ `Get your tracking snippet`, `Add the snippet to <Platform>`, `Verify installation`.+ Optional `## Track custom events` and `## Troubleshooting`, then `## Next steps`.+3. **Shared content comes from partials**, never retyped:+ - `get-snippet.mdx` β the canonical snippet and the self-hosting note.+ - `verify.mdx` β the verification checklist.+ - `next-steps.mdx` β cross-links.+ Include with `<include>../../../partials/guides/<name>.mdx</include>` (one more `../`+ from a subfolder such as `react/`). Includes are inlined at build time, so they also+ reach the `.mdx` / `llms.txt` endpoints that AI agents read.+4. **Snippet form**: when a guide must show the tag inline (a template file, a config+ value, a JS injector), use the URL form `script.js?siteId=YOUR_SITE_ID` with `defer`.+ Never the legacy `data-site-id` attribute: script optimisers strip `data-*` attributes.+5. **Only platform-specific content belongs in the guide.** Generic explanations of what+ Rybbit is, how events work, GDPR, ad blockers or proxies are linked, not repeated.+6. **Don't invent UI.** Menu paths and file names must be real. If you cannot confirm+ where custom head code goes on a platform, say what the setting is usually called and+ point to the vendor's own page rather than guessing a path.+7. **Tone**: second person, present tense, imperative steps. No "powerful", "seamless",+ "easily". A guide is typically 40β120 lines; length comes from real platform detail,+ not padding.+8. **Imports**: double quotes, `Steps` before `Callout` before `Tabs`, only what is used.+9. **Sidebar**: add the slug to `guides/meta.json` under the matching `---Category---`+ separator, alphabetically. The index page (`guides/index.mdx`) groups by frontmatter+ `category` automatically.++## Adding a guide++```+cp content/partials/guides/TEMPLATE.mdx "content/docs/(docs)/guides/<slug>.mdx"+# fill it in, then+npm run lint:guides+```diff --git a/docs/content/partials/guides/TEMPLATE.mdx b/docs/content/partials/guides/TEMPLATE.mdxnew file mode 100644index 000000000..4fb30186c--- /dev/null+++ b/docs/content/partials/guides/TEMPLATE.mdx@@ -0,0 +1,43 @@+---+title: PLATFORM+description: Add Rybbit analytics to your PLATFORM site+category: CATEGORY+icon: SiPLATFORM+---++import { Steps, Step } from "fumadocs-ui/components/steps";+import { Callout } from "fumadocs-ui/components/callout";++ONE OR TWO SENTENCES: what PLATFORM is and where the snippet goes (which setting, template or file), so a reader knows the shape of the job before the steps.++<Steps>+<Step>+### Get your tracking snippet++<include>../../../partials/guides/get-snippet.mdx</include>+</Step>++<Step>+### Add the snippet to PLATFORM++PLATFORM-SPECIFIC INSTRUCTIONS. Use a numbered list for UI navigation, a code block for file edits. Use `<Tabs>` when there is more than one reasonable method, with the recommended one first.+</Step>++<Step>+### Verify installation++<include>../../../partials/guides/verify.mdx</include>+</Step>+</Steps>++## Track custom events++OPTIONAL. Only when there is something PLATFORM-specific to say (framework component example, e-commerce events, form hooks). Otherwise delete this section; the generic docs are linked under Next steps.++## Troubleshooting++OPTIONAL. Only PLATFORM-specific failure modes (caching plugin, CSP, sandboxed embeds, plan restrictions). Generic checks already live in the Verify step.++## Next steps++<include>../../../partials/guides/next-steps.mdx</include>diff --git a/docs/content/partials/guides/get-snippet.mdx b/docs/content/partials/guides/get-snippet.mdxnew file mode 100644index 000000000..039435f72--- /dev/null+++ b/docs/content/partials/guides/get-snippet.mdx@@ -0,0 +1,7 @@+In your Rybbit dashboard, open **Site Settings β Tracking Script** and copy your snippet. It looks like this:++```html+<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.diff --git a/docs/content/partials/guides/next-steps.mdx b/docs/content/partials/guides/next-steps.mdxnew file mode 100644index 000000000..21bb77523--- /dev/null+++ b/docs/content/partials/guides/next-steps.mdx@@ -0,0 +1,4 @@+- [Track custom events](/docs/track-events) such as signups, purchases and button clicks.+- [Identify users](/docs/identify-users) to connect sessions to accounts.+- [Proxy the script](/docs/proxy-guide) through your own domain to bypass ad blockers.+- [Script attributes](/docs/script#script-attributes) let you skip or mask URLs and tag events.diff --git a/docs/content/partials/guides/verify.mdx b/docs/content/partials/guides/verify.mdxnew file mode 100644index 000000000..db3359181--- /dev/null+++ b/docs/content/partials/guides/verify.mdx@@ -0,0 +1,8 @@+Open your live site in a new tab and click through a few pages. Within a few seconds the pageviews appear in the Rybbit dashboard.++If nothing shows up:++- View the page source and search for `script.js?siteId=` to confirm the snippet is on the page.+- Open the browser Network tab and check that `script.js` returns `200` and that `POST` requests go to `/api/track`.+- Disable ad blockers, or set up a [proxy](/docs/proxy-guide) so the script loads from your own domain.+- See the [script troubleshooting guide](/docs/script-troubleshooting) for other common causes.diff --git a/docs/package.json b/docs/package.jsonindex e315d91d7..fc50323a0 100644--- a/docs/package.json+++ b/docs/package.json@@ -9,7 +9,8 @@"test:agent-readiness": "jiti src/lib/agent-readiness.test.ts","test:agent-http": "node scripts/test-agent-http.mjs","postinstall": "fumadocs-mdx",- "extract": "node scripts/extract-messages.mjs"+ "extract": "node scripts/extract-messages.mjs",+ "lint:guides": "node scripts/check-guides.mjs"},"dependencies": {"@calcom/embed-react": "^1.5.3",diff --git a/docs/scripts/check-guides.mjs b/docs/scripts/check-guides.mjsnew file mode 100644index 000000000..aa7489a4e--- /dev/null+++ b/docs/scripts/check-guides.mjs@@ -0,0 +1,113 @@+#!/usr/bin/env node+// Lint every integration guide against content/partials/guides/README.md.+// Usage: node scripts/check-guides.mjs (exit 1 on any violation)+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";+import { join, relative, dirname, resolve } from "node:path";+import { bundledLanguagesInfo } from "shiki";++// Shiki throws at build time for an unknown fence language, which 500s EVERY docs page.+const knownLangs = new Set(["text", "txt", "plain"]);+for (const l of bundledLanguagesInfo) { knownLangs.add(l.id); for (const a of l.aliases ?? []) knownLangs.add(a); }++const root = resolve(new URL("..", import.meta.url).pathname);+const guidesDir = join(root, "content/docs/(docs)/guides");+const partialsDir = join(root, "content/partials/guides");+const categories = JSON.parse(readFileSync(join(root, "src/lib/guide-categories.json"), "utf8")).map(c => c.key);++const errors = [];+const fail = (file, msg) => errors.push(`${relative(root, file)}: ${msg}`);++function walk(dir) {+ return readdirSync(dir).flatMap(name => {+ const p = join(dir, name);+ if (statSync(p).isDirectory()) return walk(p);+ return name.endsWith(".mdx") ? [p] : [];+ });+}++function frontmatter(src) {+ const m = src.match(/^---\n([\s\S]*?)\n---\n/);+ if (!m) return null;+ const fm = {};+ for (const line of m[1].split("\n")) {+ const kv = line.match(/^(\w+):\s*(.*)$/);+ if (kv) fm[kv[1]] = kv[2].replace(/^["']|["']$/g, "");+ }+ return fm;+}++const guides = walk(guidesDir).filter(p => !p.endsWith("/index.mdx"));+const slugs = new Set();++for (const file of guides) {+ const src = readFileSync(file, "utf8");+ const fm = frontmatter(src);+ const rel = relative(guidesDir, file).replace(/\.mdx$/, "");+ slugs.add(rel);+ const depth = rel.split("/").length; // 1 for top-level, 2 for react/next-js+ const up = "../".repeat(depth + 2);++ if (!fm) { fail(file, "missing frontmatter"); continue; }+ if (!fm.title) fail(file, "frontmatter: title missing");+ if (!fm.description) fail(file, "frontmatter: description missing");+ else if (!/^Add Rybbit analytics to your .+$/.test(fm.description))+ fail(file, `frontmatter: description must start with "Add Rybbit analytics to your" (got "${fm.description}")`);+ if (!fm.category) fail(file, "frontmatter: category missing");+ else if (!categories.includes(fm.category)) fail(file, `frontmatter: unknown category "${fm.category}"`);+ if (fm.icon && !/^Si[A-Z0-9]/.test(fm.icon)) fail(file, `frontmatter: icon must be a simple-icons export name (got "${fm.icon}")`);++ const steps = (src.match(/<Step>/g) ?? []).length;+ if (steps !== 3) fail(file, `expected exactly 3 <Step> blocks, found ${steps}`);+ if (!/^### Get your tracking snippet\s*$/m.test(src)) fail(file, 'missing step heading "### Get your tracking snippet"');+ if (!/^### Add the snippet to .+$/m.test(src)) fail(file, 'missing step heading "### Add the snippet to <Platform>"');+ if (!/^### Verify installation\s*$/m.test(src)) fail(file, 'missing step heading "### Verify installation"');+ if (!/^## Next steps\s*$/m.test(src)) fail(file, 'missing "## Next steps" section');++ for (const partial of ["get-snippet", "verify", "next-steps"]) {+ const tag = `<include>${up}partials/guides/${partial}.mdx</include>`;+ if (!src.includes(tag)) fail(file, `missing ${tag}`);+ }+ for (const m of src.matchAll(/<include>(.*?)<\/include>/g)) {+ const target = resolve(dirname(file), m[1]);+ if (!existsSync(target)) fail(file, `include target does not exist: ${m[1]}`);+ }++ const headings = [...src.matchAll(/^## (.+)$/gm)].map(m => m[1].trim());+ const allowed = ["Track custom events", "Troubleshooting", "Next steps"];+ for (const h of headings) if (!allowed.includes(h)) fail(file, `unexpected H2 "${h}" (allowed: ${allowed.join(", ")}; use H3 inside a step for anything else)`);+ if (headings.length && headings[headings.length - 1] !== "Next steps") fail(file, '"## Next steps" must be the last section');++ for (const m of src.matchAll(/^```([\w+#.-]+)/gm)) {+ if (!knownLangs.has(m[1].toLowerCase())) fail(file, `unknown code fence language "${m[1]}" (Shiki would crash the build); use a shiki language id such as html, razor, liquid, twig, erb, heex, jinja`);+ }+ if (/data-site-id/.test(src)) fail(file, "legacy data-site-id attribute; use script.js?siteId=");+ for (const m of src.matchAll(/api\/script\.js(?!\?siteId=)/g)) {+ // allow parameterised URLs in template languages ("/api/script.js?siteId={{ ... }}") β only the bare form is wrong+ fail(file, `script URL without ?siteId= at offset ${m.index}`);+ }+ for (const m of src.matchAll(/^import .* from '.*';?$/gm)) fail(file, `single-quoted import: ${m[0]}`);+ if (/\b(seamless(ly)?|powerful|easily|effortless(ly)?)\b/i.test(src)) fail(file, "marketing filler word (seamless/powerful/easily/effortless)");+}++// meta.json coverage+function checkMeta(dir, prefix) {+ const metaPath = join(dir, "meta.json");+ if (!existsSync(metaPath)) { fail(metaPath, "missing meta.json"); return; }+ const pages = JSON.parse(readFileSync(metaPath, "utf8")).pages ?? [];+ const listed = pages.filter(p => !p.startsWith("---") && p !== "index" && p !== "...");+ const local = readdirSync(dir).filter(n => n !== "meta.json" && n !== "index.mdx").map(n => n.replace(/\.mdx$/, ""));+ for (const p of listed) if (!local.includes(p)) fail(metaPath, `lists "${p}" which does not exist`);+ for (const n of local) if (!listed.includes(n)) fail(metaPath, `does not list "${n}"`);+ for (const n of local) {+ const sub = join(dir, n);+ if (existsSync(sub) && statSync(sub).isDirectory()) checkMeta(sub, `${prefix}${n}/`);+ }+}+checkMeta(guidesDir, "");++if (errors.length) {+ console.error(errors.join("\n"));+ console.error(`\n${errors.length} problem(s) in integration guides. See content/partials/guides/README.md`);+ process.exit(1);+}+console.log(`${guides.length} guides OK`);diff --git a/docs/source.config.ts b/docs/source.config.tsindex 32ece145e..b761218ec 100644--- a/docs/source.config.ts+++ b/docs/source.config.ts@@ -5,6 +5,11 @@ import {metaSchema,} from 'fumadocs-mdx/config';import { z } from 'zod';+import guideCategories from './src/lib/guide-categories.json';++const guideCategory = z.enum(+ guideCategories.map(c => c.key) as [string, ...string[]]+);export const { docs, meta } = defineDocs({dir: 'content/docs',@@ -12,6 +17,8 @@ export const { docs, meta } = defineDocs({// `method` powers the HTTP verb badge shown next to API endpoints in the sidebarschema: frontmatterSchema.extend({method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).optional(),+ // `category` groups integration guides on /docs/guides (see src/lib/guide-categories.json)+ category: guideCategory.optional(),}),postprocess: {includeProcessedMarkdown: true,diff --git a/docs/src/components/GuideIndex.tsx b/docs/src/components/GuideIndex.tsxnew file mode 100644index 000000000..87703c786--- /dev/null+++ b/docs/src/components/GuideIndex.tsx@@ -0,0 +1,51 @@+import * as simpleIcons from '@icons-pack/react-simple-icons';+import { Card, Cards } from 'fumadocs-ui/components/card';+import { getLocale } from 'next-intl/server';+import { createElement, type ComponentType } from 'react';+import categories from '@/lib/guide-categories.json';+import { source } from '@/lib/source';++type GuidePage = {+ url: string;+ slugs: string[];+ data: { title: string; description?: string; category?: string; icon?: string };+};++function brandIcon(name?: string) {+ if (!name || !(name in simpleIcons)) return undefined;+ const Icon = simpleIcons[name as keyof typeof simpleIcons] as ComponentType<{ className?: string }>;+ return createElement(Icon, { className: 'size-4' });+}++/**+ * Grid of every integration guide, grouped by the `category` frontmatter+ * field in the order defined by src/lib/guide-categories.json. Rendered from+ * content/docs/(docs)/guides/index.mdx so the index never goes stale.+ */+export async function GuideIndex() {+ const locale = await getLocale();+ const pages = (source.getPages(locale) as GuidePage[]).filter(+ p => p.slugs[0] === 'guides' && p.slugs.length > 1,+ );++ return (+ <>+ {categories.map(({ key, label }) => {+ const group = pages+ .filter(p => p.data.category === key)+ .sort((a, b) => a.data.title.localeCompare(b.data.title));+ if (group.length === 0) return null;+ return (+ <section key={key}>+ <h2 id={key}>{label}</h2>+ <Cards>+ {group.map(p => (+ <Card key={p.url} href={p.url} title={p.data.title} icon={brandIcon(p.data.icon)} />+ ))}+ </Cards>+ </section>+ );+ })}+ </>+ );+}diff --git a/docs/src/lib/guide-categories.json b/docs/src/lib/guide-categories.jsonnew file mode 100644index 000000000..20b083c7c--- /dev/null+++ b/docs/src/lib/guide-categories.json@@ -0,0 +1,15 @@+[+ { "key": "frameworks", "label": "JavaScript frameworks" },+ { "key": "static", "label": "Static site generators" },+ { "key": "backend", "label": "Backend frameworks" },+ { "key": "docs", "label": "Documentation tools" },+ { "key": "cms", "label": "Content management systems" },+ { "key": "builders", "label": "Website builders" },+ { "key": "ai-builders", "label": "AI app builders" },+ { "key": "ecommerce", "label": "E-commerce" },+ { "key": "creators", "label": "Courses & communities" },+ { "key": "landing", "label": "Landing pages & funnels" },+ { "key": "tag-managers", "label": "Tag managers" },+ { "key": "apps", "label": "Desktop, mobile & extensions" },+ { "key": "other", "label": "Other platforms" }+]diff --git a/docs/src/lib/source.ts b/docs/src/lib/source.tsindex 400308bbd..08846aca6 100644--- a/docs/src/lib/source.ts+++ b/docs/src/lib/source.ts@@ -2,8 +2,9 @@ import { ApiSidebarLabel } from '@/components/ApiMethodBadge';import { docs, meta } from '@/.source';import { InferPageType, loader } from 'fumadocs-core/source';import { toFumadocsSource } from 'fumadocs-mdx/runtime/server';+import * as simpleIcons from '@icons-pack/react-simple-icons';import { icons } from 'lucide-react';-import { createElement } from 'react';+import { createElement, type ComponentType } from 'react';import { i18n } from './i18n';// See https://fumadocs.vercel.app/docs/headless/source-api for more info@@ -12,10 +13,20 @@ export const source = loader({// it assigns a URL to your pagesbaseUrl: '/docs',// resolve string `icon` names from meta.json to lucide-react icons+ // resolve string `icon` names from meta.json / frontmatter: lucide-react+ // names for docs sections, simple-icons names (`SiWordpress`) for the+ // brand icons on integration guides.icon(icon) {- if (icon && icon in icons) {+ if (!icon) return;+ if (icon in icons) {return createElement(icons[icon as keyof typeof icons]);}+ if (icon in simpleIcons) {+ return createElement(+ simpleIcons[icon as keyof typeof simpleIcons] as ComponentType<{ className?: string }>,+ { className: 'size-4' },+ );+ }},pageTree: {// Append an HTTP method badge to sidebar items whose page has a `method`diff --git a/docs/src/mdx-components.tsx b/docs/src/mdx-components.tsxindex 9d2d49eb2..01766f84c 100644--- a/docs/src/mdx-components.tsx+++ b/docs/src/mdx-components.tsx@@ -1,5 +1,6 @@import defaultMdxComponents from "fumadocs-ui/mdx";import type { MDXComponents } from "mdx/types";+import { GuideIndex } from "@/components/GuideIndex";import { Mermaid } from "@/components/Mermaid";import * as TabsComponents from "fumadocs-ui/components/tabs";import { ImageZoom } from "fumadocs-ui/components/image-zoom";@@ -9,6 +10,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {return {...defaultMdxComponents,...TabsComponents,+ GuideIndex,Mermaid,img: props => <ImageZoom {...(props as any)} />,...components,