Tracking Script
To start tracking user activity on your website, add the Rybbit tracking script to your site’s HTML.
Installation
The webpage should give you this script tag like this when you first add a website. Place it within the <head>
section of your website. Include it on every page you wish to track.
<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
If you are self-hosting Rybbit app.rybbit.io
will be domain of your Rybbit instance.
Configuration Options
You can customize the script’s behavior using data-*
attributes on the <script>
tag:
Attribute | Type | Default | Description |
---|---|---|---|
data-auto-track-pageview | string | "true" | Set to "false" to disable automatic tracking of the initial pageview when the script loads. You will need to manually call window.rybbit.pageview() to track pageviews. |
data-track-spa | string | "true" | Set to "false" to disable automatic pageview tracking for single page applications (React, Vue, etc). You will need to manually call window.rybbit.pageview() or window.rybbit.track() for all but the initial pageview. |
data-track-query | string | "true" | Set to "false" to disable tracking of URL query strings. This enhances privacy by preventing potentially sensitive information in query parameters from being stored in your analytics data. |
data-track-outbound | string | "true" | Set to "false" to disable automatic tracking of outbound link clicks. |
data-track-errors | string | "false" | Set to "true" to enable automatic tracking of JavaScript errors and unhandled promise rejections. Only tracks errors from the same origin to avoid noise from third-party scripts. |
data-session-replay | string | "false" | Set to "true" to enable session replay recording. Captures user interactions, mouse movements, and DOM changes for debugging and user experience analysis. |
data-web-vitals | string | "false" | Set to "true" to enable Web Vitals performance metrics collection (LCP, CLS, INP, FCP, TTFB). Web Vitals are disabled by default to reduce script size and network requests. |
data-skip-patterns | string | [] | A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won’t be tracked. Supports two types of wildcards: * (matches within a segment) and ** (matches across segments). |
data-mask-patterns | string | [] | A JSON string array of URL path patterns to mask for privacy. Pageviews matching these patterns will be tracked, but the actual URL path will be replaced with the pattern itself in analytics data. Supports the same wildcards as data-skip-patterns . |
data-debounce | string | "500" | The delay (in milliseconds) before tracking a pageview after URL changes via the History API (pushState , replaceState ). Set to 0 to disable debouncing. |
data-api-key | string | undefined | API key for tracking from localhost during development. Bypasses origin validation. See Localhost Tracking for details. |
Pattern Matching Details
For data-skip-patterns
and data-mask-patterns
, two types of wildcards are supported:
*
- Matches any characters within a single path segment (doesn’t match across/
)**
- Matches any characters across multiple path segments (includes/
)
Examples:
/admin/*
matches/admin/dashboard
but not/admin/users/list
/admin/**
matches both/admin/dashboard
and/admin/users/list
/blog/*/comments
matches/blog/post-123/comments
but not/blog/category/post/comments
Example usage:
data-skip-patterns='["/admin/**", "/blog/drafts/*", "/preview/**"]'
data-mask-patterns='["/users/*/settings", "/accounts/**", "/orders/*/details"]'
Example with multiple options:
<script
src="https://api.rybbit.io/api/script.js"
async
data-site-id="456"
data-skip-patterns='["/admin/**", "/preview/*"]'
data-mask-patterns='["/users/*/profile", "/orders/**"]'
data-track-query="false"
data-session-replay="true"
data-track-errors="true"
data-web-vitals="true"
data-debounce="300"
></script>
Session Replay
Session replay is disabled by default. When enabled with data-session-replay="true"
, the script will:
- Record user interactions, mouse movements, clicks, and scrolling
- Capture DOM changes and page navigation
- Store replay data for debugging and user experience analysis
- Provide visual playback of user sessions in your analytics dashboard
Enable Session Replay:
<script
src="https://app.rybbit.io/api/script.js"
async
data-site-id="YOUR_SITE_ID"
data-session-replay="true"
></script>
Privacy Note: Session replay captures visual user interactions but does not record sensitive form inputs like passwords or credit card numbers. Text inputs are masked by default to protect user privacy.
Web Vitals Performance Metrics
Web Vitals are disabled by default to keep the script lightweight. When enabled with data-web-vitals="true"
, the script will:
- Load the Web Vitals library from CDN
- Collect Core Web Vitals: LCP (Largest Contentful Paint), CLS (Cumulative Layout Shift), INP (Interaction to Next Paint)
- Collect additional metrics: FCP (First Contentful Paint), TTFB (Time to First Byte)
- Send performance data to your analytics dashboard
Enable Web Vitals:
<script
src="https://app.rybbit.io/api/script.js"
async
data-site-id="YOUR_SITE_ID"
data-web-vitals="true"
></script>
Error Tracking
Error tracking is disabled by default. When enabled with data-track-errors="true"
, the script will:
- Automatically capture JavaScript errors and unhandled promise rejections
- Filter out errors from third-party scripts (only tracks errors from your domain)
- Truncate error messages and stack traces to prevent excessive data storage
- Send error data to your analytics dashboard for monitoring
Enable Error Tracking:
<script
src="https://app.rybbit.io/api/script.js"
async
data-site-id="YOUR_SITE_ID"
data-track-errors="true"
></script>
Error data includes:
- Error type (TypeError, ReferenceError, etc.)
- Error message (truncated to 500 characters)
- Stack trace (truncated to 2000 characters)
- File location and line/column numbers
- Session information for debugging
Privacy Note: Error tracking only captures errors originating from your website’s domain to avoid noise from browser extensions, third-party scripts, or other external sources.