🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Add tracker metadata and update documentation for tracking script integration
Bill Yang5a18fc69b23c
diff --git a/docs/src/content/_meta.js b/docs/src/content/_meta.jsindex dfd900aa5..5d68bfb57 100644--- a/docs/src/content/_meta.js+++ b/docs/src/content/_meta.js@@ -1,6 +1,7 @@export default {index: "","self-hosting": "",+ tracker: "",features: "",themes: "",advanced: "",diff --git a/docs/src/content/index.mdx b/docs/src/content/index.mdxindex d247d75a7..20d7d2ee7 100644--- a/docs/src/content/index.mdx+++ b/docs/src/content/index.mdx@@ -19,4 +19,6 @@ Choose the option that's right for you:- **Cloud Version:** Sign up for the hosted version at [rybbit.io/signup](https://rybbit.io/signup). Get up and running in minutes.- **Self-Host:** Follow our [Self-Hosting Guide](./self-hosting) to set up Rybbit on your own server.-<Bleed></Bleed>\ No newline at end of file+And then learn how to add the [Tracking Script](./tracker) to your website to start collecting data.++<Bleed></Bleed>diff --git a/docs/src/content/tracker.mdx b/docs/src/content/tracker.mdxnew file mode 100644index 000000000..950ef45ee--- /dev/null+++ b/docs/src/content/tracker.mdx@@ -0,0 +1,104 @@+# 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.++```html+<script src="https://api.ribbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>+```++If you are self-hosting Rybbit `api.ribbit.io` will be instead the base URL of your Rybbit instance.++## Configuration Options++You can customize the script's behavior using `data-*` attributes on the `<script>` tag:++### `data-debounce`++The delay (in milliseconds) before tracking a pageview after URL changes via the History API (`pushState`, `replaceState`). Set to `0` to disable debouncing.++- **Default:** `"500"`+- **Example:** `data-debounce="1000"`++### `data-auto-track`++Set to `"false"` to disable automatic pageview tracking on initial load and History API changes. You will need to manually call `window.rybbit.pageview()` or `window.rybbit.track()`.++- **Default:** `"true"`+- **Example:** `data-auto-track="false"`++### `data-skip-patterns`++A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won't be tracked. Use `*` as a wildcard for path segments (e.g., `/admin/*`).++- **Default:** `[]`+- **Example:** `data-skip-patterns='["/admin", "/blog/*/edit"]'`++### `data-mask-patterns`++A JSON string array of URL path patterns to mask. Pageviews matching these patterns will be tracked, but the `pathname` sent will be replaced with the matching pattern string (e.g., `/users/*/profile`).++- **Default:** `[]`+- **Example:** `data-mask-patterns='["/users/*/settings", "/order/*"]'`++**Example with multiple options:**++```html+<script+ src="https://api.rybbit.io/api/script.js"+ async+ data-site-id="456"+ data-host="https://rybbit.mycompany.com"+ data-auto-track="false"+ data-skip-patterns='["/admin"]'+ data-mask-patterns='["/user/*/dashboard"]'+></script>+```++## Manual Tracking API++The script exposes a global object `window.rybbit` with functions for manual tracking:++### `window.rybbit.track(eventType, eventName, properties)`++The core function to send tracking data.++* `eventType` (String): The type of event. Defaults to `"pageview"`. Use `"custom_event"` for custom events.+* `eventName` (String): The name of the custom event (max 255 characters). **Required** when `eventType` is `"custom_event"`.+* `properties` (Object, Optional): An object containing custom data (max 8192 characters / 8KB when stringified). This will be JSON-stringified before sending.++```javascript+// Track a simple pageview (usually handled automatically)+window.rybbit.track("pageview");++// Track a custom event+window.rybbit.track("custom_event", "Signup Button Clicked");++// Track a custom event with properties+window.rybbit.track("custom_event", "Item Added To Cart", {+ itemId: "PROD123",+ price: 49.99,+ category: "Clothing"+});+```++### `window.rybbit.pageview()`++A convenience function for tracking a pageview. Equivalent to `window.rybbit.track('pageview')`. Useful when `data-auto-track` is set to `"false"`.++```javascript+window.rybbit.pageview();+```++### `window.rybbit.event(eventName, properties)`++A convenience function for tracking custom events. Equivalent to `window.rybbit.track('custom_event', eventName, properties)`.++* `eventName` (String): The name of the custom event (max 255 characters).+* `properties` (Object, Optional): An object containing custom data (max 2048 characters / 2KB when stringified).++```javascript+window.rybbit.event("Video Played", { videoId: "xyz789" });+```diff --git a/server/public/script.js b/server/public/script.jsindex 6cec4919a..7a1776556 100644--- a/server/public/script.js+++ b/server/public/script.js@@ -150,7 +150,7 @@window.addEventListener("popstate", debouncedTrackPageview);}- window.frogstats = {+ window.rybbit = {track,pageview: trackPageview,event: (name, properties = {}) => track("custom_event", name, properties),