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?siteId=YOUR_SITE_ID" defer></script>

If you are self-hosting Rybbit app.rybbit.io will be domain of your Rybbit instance.

The site ID is passed in the script URL. The older data-site-id="YOUR_SITE_ID" attribute still works, but the URL form is recommended because script optimizers (WP Rocket, Perfmatters, FlyingPress and similar "delay JavaScript" features) rebuild script tags and drop data-* attributes, while leaving the URL intact.

Configuration

Site Settings Configuration

Most tracking options are configured through your site settings in the Rybbit dashboard. The script automatically fetches these settings when it loads:

• Automatic Initial Pageview: Track the first pageview when the script loads
• SPA Navigation: Automatically track navigation in single-page applications
• URL Parameters: Include or exclude query strings from tracked URLs
• URL Fragments: Track ordinary #fragments as part of the path (see Hash routes and URL fragments)
• Outbound Links: Track clicks to external websites
• Button Clicks: Track clicks on buttons
• Copy: Track when visitors copy text
• Form Interactions: Track form submissions and input changes
• Error Tracking: Capture JavaScript errors and unhandled promise rejections
• Session Replay: Record user interactions for debugging and UX analysis
• Web Vitals: Collect Core Web Vitals performance metrics

If the script can't load these settings (for example, a proxy that doesn't forward /site/tracking-config/:siteId), it uses built-in defaults: pageviews, SPA navigation, query strings and outbound links on, everything else off.

Script Attributes

These are the attributes you can pass to the script tag.

Hash routes and URL fragments

Rybbit automatically recognizes hash routes beginning with #/ or #!/. For example, /#/shipping and /#!/shipping are both tracked as /shipping.

Ordinary fragments such as #shipping are ignored by default. If your site uses them for checkout stages or tabs, enable Track URL fragments in your site's Tracking settings. Rybbit will then track /checkout/#shipping and /checkout/#payment as separate paths that you can use in funnels and goals. Enable SPA Navigation to automatically record changes between these stages.

Automatic navigation records a pageview only when the tracked path or tracked query string changes. Ignored anchors and repeated navigation events do not add pageviews. Explicit calls to rybbit.pageview() still record a pageview for the current URL.

This setting applies to future events; previously discarded fragments cannot be recovered.

Session Replay Attributes

These attributes configure rrweb session replay behavior. They only apply when session replay is enabled in your site settings.

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

Regex patterns are also supported when prefixed with re:. The regex is used as-is, so add ^ and $ if you want a full-path match.

Examples:

• re:^/users/\\d+$ matches /users/123 but not /users/abc
• re:^/private/.*$ matches anything under /private/

Example usage:

data-skip-patterns='["/admin/**", "/blog/drafts/*", "/preview/**"]'
data-mask-patterns='["/users/*/settings", "/accounts/**", "/orders/*/details"]'

Regex usage:

data-skip-patterns='["re:^/private/.*$"]'
data-mask-patterns='["re:^/users/\\d+/settings$"]'

Example with debugging overrides:

<script
  src="https://app.rybbit.io/api/script.js?siteId=456"
  defer
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-debounce="300"
></script>

Session Replay Configuration

When session replay is enabled in your site settings, you can fine-tune the recording behavior using the attributes above. This section covers the more complex configuration options.

Each recorded session is capped at 50 MB of replay data. Once a session reaches the cap, the server tells the script to stop recording for the rest of that session. Self-hosted instances can change the cap with the SESSION_REPLAY_MAX_MB_PER_SESSION environment variable (0 turns it off).

Privacy Controls

Protect sensitive user information using these options:

Example - Comprehensive privacy setup:

<script
  src="https://app.rybbit.io/api/script.js?siteId=123"
  defer
  data-replay-block-selector=".admin-panel, #payment-modal"
  data-replay-ignore-selector="input[name='ssn'], input[name='credit-card']"
  data-replay-mask-text-selectors='[".user-name", "#email", "[data-pii]"]'
  data-replay-mask-input-options='{"password":true,"email":true,"tel":true}'
></script>

Sampling Configuration

The data-replay-sampling attribute controls how frequently events are recorded. Lower sampling rates reduce data volume but may miss some interactions.

Default sampling configuration:

{
  "mousemove": false,
  "mouseInteraction": {
    "MouseUp": false,
    "MouseDown": false,
    "Click": true,
    "ContextMenu": false,
    "DblClick": true,
    "Focus": true,
    "Blur": true,
    "TouchStart": false,
    "TouchEnd": false
  },
  "scroll": 500,
  "input": "last",
  "media": 800
}

Sampling options:

• mousemove: false to disable, or number (ms) for sampling interval
• scroll: Sampling interval in milliseconds (e.g., 500 = sample every 500ms)
• input: "last" to only record final value, or "all" to record every keystroke
• media: Sampling interval for media events in milliseconds

Example - Enable mouse tracking for UX analysis:

data-replay-sampling='{"mousemove":100,"scroll":150}'

SlimDOM Options

The data-replay-slim-dom-options attribute controls which DOM elements are excluded from recording to reduce data size.

Default slimDOM configuration:

{
  "script": false,
  "comment": true,
  "headFavicon": true,
  "headWhitespace": true,
  "headMetaDescKeywords": true,
  "headMetaSocial": true,
  "headMetaRobots": true,
  "headMetaHttpEquiv": true,
  "headMetaAuthorship": true,
  "headMetaVerification": true
}

Set to true to enable all slimDOM options, or false to disable all:

data-replay-slim-dom-options="true"

Complete Example

<script
  src="https://app.rybbit.io/api/script.js?siteId=456"
  defer
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-debounce="300"
  data-replay-block-selector=".sensitive-content"
  data-replay-mask-text-selectors='[".user-name", "#email"]'
  data-replay-mask-all-inputs="true"
  data-replay-collect-fonts="false"
  data-replay-sampling='{"mousemove":false,"scroll":500}'
></script>