🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Update web SDK docs
Edward Cui12fe55cc217a
diff --git a/docs/src/content/sdks/web.mdx b/docs/src/content/sdks/web.mdxindex e07125a42..1a816dd25 100644--- a/docs/src/content/sdks/web.mdx+++ b/docs/src/content/sdks/web.mdx@@ -39,22 +39,22 @@ rybbit.init({### Configuration Options-<Callout type="default">-The SDK is currently does not have all features of the tracking script. Currently web vitals and tracking events data attributes are not supported.-</Callout>--| Option (`init`) | Type | Default | Description |-| :------------------- | :----------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `analyticsHost` | `string` | - | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |-| `siteId` | `string \| number` | - | **Required.** The Site ID for your website obtained from your Rybbit instance. |-| `debounce` | `number` | `500` | Debounce time in milliseconds for tracking SPA pageviews after route changes. Set to `0` to disable debouncing (track immediately). |-| `autoTrackPageviews` | `boolean` | `true` | If `true`, automatically tracks pageviews on initial load and (if `autoTrackSpaRoutes` is `true`) on SPA navigation. |-| `autoTrackSpaRoutes` | `boolean` | `true` | If `true` (and `autoTrackPageviews` is `true`), automatically tracks pageviews when browser history changes (`pushState`, `popstate`). |-| `trackQuerystring` | `boolean` | `true` | If `true`, includes the URL's query string (e.g., `?utm_source=google`) in the tracked `querystring` data. |-| `trackOutboundLinks` | `boolean` | `true` | If `true`, automatically tracks clicks on anchor (`<a>`) tags that link to external domains. |-| `skipPatterns` | `string[]` | `[]` | Array of path patterns. Pageviews whose path matches any pattern will **not** be tracked. See [Path Matching](#path-matching). |-| `maskPatterns` | `string[]` | `[]` | Array of path patterns. For matching pageview paths, the original path will be **replaced** by the pattern itself in tracked data. See [Path Matching](#path-matching). |-| `debug` | `boolean` | `false` | If `true`, enables detailed logging to the browser console. |+| Option (`init`) | Type | Default | Description |+| :-------------------- | :----------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `analyticsHost` | `string` | - | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |+| `siteId` | `string \| number` | - | **Required.** The Site ID for your website obtained from your Rybbit instance. |+| `debounce` | `number` | `500` | Debounce time in milliseconds for tracking pageviews after route changes. Set to `0` to disable debouncing (track immediately). |+| `autoTrackPageviews` | `boolean` | `true` | Track pageviews on initial load. |+| `autoTrackSpaRoutes` | `boolean` | `true` | Track pageviews on SPA navigation (if `autoTrackPageviews` is `true`). |+| `trackQuerystring` | `boolean` | `true` | Include the URL's query string (e.g., `?utm_source=google`) in the tracked `querystring` data. |+| `trackOutboundLinks` | `boolean` | `true` | Track clicks on anchor (`<a>`) tags that link to external domains. |+| `trackHashRoutes` | `boolean` | `true` | Track URL hash changes. |+| `trackDataAttributes` | `boolean` | `true` | Track clicks on elements with a `data-rybbit-event` attribute. |+| `trackWebVitals` | `boolean` | `true` | Track website performance metrics. |+| `webVitalsTimeout` | `number` | `20000` | Timeout in milliseconds for sending web vitals. |+| `skipPatterns` | `string[]` | `[]` | Array of path patterns. Pageviews whose path matches any pattern will **not** be tracked. See [Path Matching](#path-matching). |+| `maskPatterns` | `string[]` | `[]` | Array of path patterns. For matching pageview paths, the original path will be **replaced** by the pattern itself in tracked data. See [Path Matching](#path-matching). |+| `debug` | `boolean` | `false` | Enable detailed logging to the browser console. |## Tracking Pageviews@@ -71,14 +71,14 @@ rybbit.pageview(path?: string);- **`path`** (`string`, Optional):- Replaces the detected URL path (`window.location.pathname`) and query string (`window.location.search`) for this specific pageview event.- Should start with a `/` (e.g., `/virtual/my-custom-page`).- - If `path` includes its own query string (e.g., `/virtual/step?id=123&source=email`), that query string will be used for the event. If `path` has no query string, the `querystring` property for the event will be empty.+ - If `path` includes its own query string (e.g., `/virtual/step?id=123`), that query string will be used for the event. If `path` has no query string, the `querystring` property will be empty.- `skipPatterns` and `maskPatterns` will be applied to `path`.### When to Use Manually- **Automatic tracking disabled:** If you set `autoTrackPageviews: false` during initialization.- **Virtual Pageviews:** In SPAs where a significant view change occurs without a URL change.-- **Specific Timing:** If you need to ensure a pageview is tracked only after certain conditions are met or specific data is available.+- **Specific Timing:** If you need to ensure a pageview is tracked only after certain conditions are met.### Example@@ -95,7 +95,7 @@ openUserDetailsModal("user-abc", "contact-info");// Example: Track a virtual pageview with its own query parametersfunction showFilteredProductList(category, sortBy) {- const virtualPathWithQuery = `/products/category/${category}?sort=${sortBy}&view=grid`;+ let virtualPathWithQuery = `/products/category/${category}?sort=${sortBy}&view=grid`;rybbit.pageview(virtualPathWithQuery);}showFilteredProductList("electronics", "price_desc");@@ -103,20 +103,24 @@ showFilteredProductList("electronics", "price_desc");## Tracking Custom Events-Use custom events to track specific user interactions or milestones beyond simple page navigation. Examples include button clicks, form submissions, video plays, item purchases, etc.+Use custom events to track specific user interactions. Examples include button clicks, form submissions, or adding an item to a cart.-### Syntax+### Programmatic Tracking++You can trigger events from your JavaScript code.++#### Syntax```typescriptrybbit.event(name: string, properties?: TrackProperties);```-### Parameters+#### Parameters- **`name`** (`string`, Required): The name of the event you want to track.-- **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values should ideally be strings, numbers, or booleans. Keep the structure flat.+- **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event.-### Example+#### Example```javascript// Track a simple button click@@ -124,16 +128,7 @@ document.getElementById("cta-button")?.addEventListener("click", () => {rybbit.event("cta_click");});-// Track a signup event with properties-function handleSignup(formData) {- // ... process signup ...- rybbit.event("signup_complete", {- plan: formData.plan,- method: "email"- });-}--// Track adding an item to a shopping cart+// Track adding an item to a shopping cart with propertiesfunction addToCart(item) {// ... add item ...rybbit.event("add_to_cart", {@@ -145,14 +140,36 @@ function addToCart(item) {}```-{/* ## Tracking Outbound Links+### Declarative Tracking with Data Attributes++If `trackDataAttributes` is enabled (default), you can track events directly from your HTML. The SDK will automatically listen for clicks on elements with the `data-rybbit-event` attribute.++- **`data-rybbit-event="<event-name>"`**: This attribute makes the element trackable. The value is used as the event name.+- **`data-rybbit-prop-<property-name>="<value>"`**: You can add multiple properties to the event by using this attribute format. The SDK collects all attributes starting with `data-rybbit-prop-` and includes them as key-value pairs in the event data.++#### Example++```html+<button data-rybbit-event="cta_click">Click Me</button>++<button+ data-rybbit-event="add_to_cart"+ data-rybbit-prop-item_id="product-123"+ data-rybbit-prop-item_name="Classic T-Shirt"+ data-rybbit-prop-price="29.99"+>+ Add to Cart+</button>+```++## Tracking Outbound LinksOutbound links (links to external domains) are tracked automatically by default if `trackOutboundLinks` is enabled. The SDK attaches a global click listener to capture clicks on `<a>` tags with external `href` attributes.### Syntax```typescript-rybbit.trackOutboundLink(url: string, text?: string, target?: string);+rybbit.outbound(url: string, text?: string, target?: string);```### Parameters@@ -164,7 +181,6 @@ rybbit.trackOutboundLink(url: string, text?: string, target?: string);### When to Use Manually- **Automatic tracking disabled:** If you set `trackOutboundLinks: false` during init.-- **Dynamically generated links:** If links are added to the DOM after the initial page load and you want to ensure they are tracked immediately upon interaction.- **Non-anchor elements:** If you trigger navigation to an external site using JavaScript from an element that isn't an `<a>` tag.### Example@@ -172,32 +188,90 @@ rybbit.trackOutboundLink(url: string, text?: string, target?: string);```javascript// Manually track an outbound click triggered by a buttondocument.getElementById("external-service-button")?.addEventListener("click", () => {- const url = "https://external-service.com";- rybbit.trackOutboundLink(url, "Visit External Service", "_blank");+ let url = "https://external-service.com";+ rybbit.outbound(url, "Visit External Service", "_blank");// Optionally navigate after trackingwindow.open(url, "_blank");});-``` */}+```++## User Identification++You can associate tracking events with a specific user ID. The ID is persisted in `localStorage` and will be attached to all subsequent tracking events for that user.++### `identify`++Assigns a user ID.++```typescript+rybbit.identify(userId: string);+```++**Example:**++```javascript+// After a user logs in+rybbit.identify("user-xzy-123");+```++### `clearUserId`++Clears the stored user ID.++```typescript+rybbit.clearUserId();+```++**Example:**++```javascript+// When a user logs out+rybbit.clearUserId();+```++### `getUserId`++Retrieves the currently stored user ID.++```typescript+rybbit.getUserId(): string | null;+```++**Example:**++```javascript+let currentUserId = rybbit.getUserId();+console.log("Current Rybbit User ID:", currentUserId);+```++## Cleanup++In Single Page Applications or other dynamic environments, you may need to manually clean up the listeners that the SDK sets up.++### Syntax++```typescript+rybbit.cleanup();+```## Path Matching-These configuration options allow you to control which page paths are tracked and how they appear in your analytics data using wildcard patterns passed in the `rybbit.init()` configuration object.+These options allow you to control which page paths are tracked and how they appear in your analytics data using wildcard patterns.### Wildcards- `*`: Matches any sequence of characters **except** the forward slash (`/`). Useful for matching single path segments.-- `**`: Matches any sequence of characters **including** the forward slash (`/`). Useful for matching multiple path segments or arbitrary endings.+- `**`: Matches any sequence of characters **including** the forward slash (`/`). Useful for matching multiple path segments.### `skipPatterns`-If a page's path (`window.location.pathname`) matches any pattern in the `skipPatterns` array, the pageview event (and any associated data) for that path will **not** be sent to Rybbit.+If a page's path matches any pattern in `skipPatterns`, the pageview for that path will **not** be sent.**Examples:**- `"/admin/*"`: Skips `/admin/login`, `/admin/users`, but **not** `/admin/settings/profile`.- `"/admin/**"`: Skips `/admin/login`, `/admin/users`, *and* `/admin/settings/profile`.- `"/users/*/profile"`: Skips `/users/123/profile`, `/users/abc/profile`, but **not** `/users/123/settings`.-- `"/private"`: Skips only the exact path `/private`.```javascript filename="Example skipPatterns in init"rybbit.init({@@ -212,7 +286,7 @@ rybbit.init({### `maskPatterns`-If a page's path matches a pattern in the `maskPatterns` array, the pageview event **will** be sent, but the `pathname` property in the tracked data will be **replaced** by the pattern string itself. This is useful for grouping similar pages or hiding sensitive information like IDs in URLs while still tracking the view.+If a page's path matches a pattern in `maskPatterns`, the pageview **will** be sent, but the `pathname` will be **replaced** by the pattern string itself. This is useful for grouping similar pages or hiding sensitive IDs.<Callout type="warning">If a path matches both a `skipPatterns` and a `maskPatterns` pattern, **skipping takes priority**.@@ -221,11 +295,9 @@ If a path matches both a `skipPatterns` and a `maskPatterns` pattern, **skipping**Examples:**- Pattern: `"/users/*/profile"`- - `/users/123/profile` is tracked as `pathname: "/users/*/profile"`- - `/users/abc/profile` is tracked as `pathname: "/users/*/profile"`+ - `/users/123/profile` is tracked as `pathname: "/users/*/profile"`.- Pattern: `"/products/**"`- - `/products/electronics/tv-123` is tracked as `pathname: "/products/**"`- - `/products/clothing/shirt-xyz` is tracked as `pathname: "/products/**"`+ - `/products/electronics/tv-123` is tracked as `pathname: "/products/**"`.```javascript filename="Example maskPatterns in init"rybbit.init({