🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Update web SDK docs
Edward Cui88ed7b01e9cf
diff --git a/docs/content/docs/sdks/web.mdx b/docs/content/docs/sdks/web.mdxindex c5c609934..7f9e7429c 100644--- a/docs/content/docs/sdks/web.mdx+++ b/docs/content/docs/sdks/web.mdx@@ -16,6 +16,22 @@ npm install @rybbit/jsyarn add @rybbit/js```+## Peer Dependencies++The SDK has an optional peer dependency for session replay functionality:++```bash+npm install rrweb+```++```bash+yarn add rrweb+```++<Callout type="info">+The `rrweb` package is only required if you enable session replay in your Rybbit dashboard. The SDK will work without it for all other tracking features.+</Callout>+## Initialization<Callout type="warning">@@ -25,7 +41,7 @@ yarn add @rybbit/js### Syntax```typescript-rybbit.init(config: RybbitConfig);+rybbit.init(config: RybbitConfig): Promise<void>;```### Example@@ -33,7 +49,7 @@ rybbit.init(config: RybbitConfig);```javascriptimport rybbit from "@rybbit/js";-rybbit.init({+await rybbit.init({analyticsHost: "https://api.rybbit.io/api",siteId: "1",});@@ -41,26 +57,48 @@ rybbit.init({### Configuration Options-| 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` | `false` | 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. |+#### Required Options++| Option | Type | Description |+| :-------------- | :----------------- | :----------------------------------------------------------------------------------- |+| `analyticsHost` | `string` | URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |+| `siteId` | `string \| number` | The Site ID for your website obtained from your Rybbit instance. |++#### Local Configuration Options++These options are configured in your code and control SDK behavior locally:++| Option | Type | Default | Description |+| :--------------------- | :------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `debounce` | `number` | `500` | Debounce time in milliseconds for tracking pageviews after route changes. Set to `0` to disable debouncing (track immediately). |+| `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. |+| `enableRemoteConfig` | `boolean` | `true` | Enable fetching configuration from your Rybbit instance on init. Disable to skip remote config fetch. |+| `remoteConfigTimeout` | `number` | `3000` | Timeout in milliseconds for fetching remote configuration. |+| `replayBufferSize` | `number` | `250` | Number of session replay events to buffer before sending to server. |+| `replayBatchInterval` | `number` | `5000` | Interval in milliseconds for sending session replay event batches. |+| `replayPrivacyConfig` | `object` | - | Privacy settings for session replay. See [Session Replay](#session-replay). |++#### Remote Configuration++These settings are controlled through your Rybbit dashboard and cannot be set in the init config:++| Dashboard Setting | Description | Default |+| :--------------------- | :--------------------------------------------------------- | :------ |+| Track Initial Pageview | Track pageview on initial page load | `true` |+| Track SPA Navigation | Track pageviews on Single Page Application route changes | `true` |+| Track URL Parameters | Include URL query strings in tracked data | `true` |+| Track Outbound Links | Automatically track clicks on external links | `true` |+| Track Web Vitals | Track Core Web Vitals performance metrics | `false` |+| Capture Errors | Enable automatic error tracking | `false` |+| Session Replay | Enable session replay recording | `false` |++If fetching settings fails or times out, the SDK uses sensible defaults.## Tracking Pageviews-Pageviews are tracked automatically if `autoTrackPageviews` is enabled (default). This includes the initial page load and subsequent route changes in Single Page Applications (SPAs) if `autoTrackSpaRoutes` is also enabled.+Pageviews are tracked automatically based on your dashboard settings. This includes the initial page load and subsequent route changes in Single Page Applications (SPAs).### Syntax@@ -78,7 +116,7 @@ rybbit.pageview(path?: string);### When to Use Manually-- **Automatic tracking disabled:** If you set `autoTrackPageviews: false` during initialization.+- **Automatic tracking disabled:** If you disabled automatic pageview tracking in your dashboard.- **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.@@ -144,7 +182,7 @@ function addToCart(item) {### 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.+The SDK automatically listens 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.@@ -166,7 +204,7 @@ If `trackDataAttributes` is enabled (default), you can track events directly fro## Tracking Outbound Links-Outbound 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.+Outbound links (links to external domains) are tracked automatically by default based on your dashboard settings. The SDK attaches a global click listener to capture clicks on `<a>` tags with external `href` attributes.### Syntax@@ -182,7 +220,7 @@ rybbit.outbound(url: string, text?: string, target?: string);### When to Use Manually-- **Automatic tracking disabled:** If you set `trackOutboundLinks: false` during init.+- **Automatic tracking disabled:** If you disabled outbound link tracking in your dashboard.- **Non-anchor elements:** If you trigger navigation to an external site using JavaScript from an element that isn't an `<a>` tag.### Example@@ -197,6 +235,116 @@ document.getElementById("external-service-button")?.addEventListener("click", ()});```+## Error Tracking++The SDK can automatically capture JavaScript errors and unhandled promise rejections. This feature must be enabled in your Rybbit dashboard.++### Automatic Error Capture++When enabled in your dashboard, the SDK will automatically track:+- Uncaught exceptions (`window.error` events)+- Unhandled promise rejections (`window.unhandledrejection` events)++### Manual Error Capture++You can manually capture errors with additional context:++#### Syntax++```typescript+rybbit.captureError(error: Error | ErrorEvent, context?: TrackProperties);+```++#### Parameters++- **`error`** (`Error | ErrorEvent`, Required): The error object to capture.+- **`context`** (`object`, Optional): Additional context to include with the error.++#### Example++```javascript+try {+ // Some risky operation+ processPayment(orderData);+} catch (error) {+ rybbit.captureError(error, {+ component: "checkout",+ orderId: "order-123",+ userId: currentUser.id+ });+ // Handle error in your UI+ showErrorMessage("Payment failed");+}++// Capture error from async operation+async function fetchUserData(userId) {+ try {+ const response = await fetch(`/api/users/${userId}`);+ return await response.json();+ } catch (error) {+ rybbit.captureError(error, {+ endpoint: "/api/users",+ userId: userId+ });+ throw error;+ }+}+```++<Callout type="info">+Manual error capture only works when error tracking is enabled in your dashboard settings. If it's disabled, calling `captureError()` will log a warning.+</Callout>++## Session Replay++Session replay records user interactions on your website, allowing you to watch how users navigate and interact with your site. This feature requires the `rrweb` peer dependency.++### Installation++```bash+npm install rrweb+```++### Enabling Session Replay++Session replay must be enabled in your Rybbit dashboard under. Once enabled, recording starts automatically when the SDK initializes.++### Manual Controls++You can manually start, stop, and check the status of session replay:++```typescript+// Start recording (only works if enabled in dashboard)+rybbit.startSessionReplay();++// Stop recording+rybbit.stopSessionReplay();++// Check if currently recording+const isRecording = rybbit.isSessionReplayActive();+if (isRecording) {+ console.log("Session is being recorded");+}+```++### Privacy Configuration++Session replay includes privacy-focused defaults and configuration options:++```javascript+await rybbit.init({+ analyticsHost: "https://api.rybbit.io/api",+ siteId: "1",+ replayPrivacyConfig: {+ maskAllInputs: true, // Mask all input values (default: true)+ maskTextSelectors: [+ ".sensitive-data", // Mask text in elements with this class+ "#credit-card" // Mask specific element IDs+ ]+ }+});+```+## User IdentificationYou 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.@@ -246,6 +394,58 @@ let currentUserId = rybbit.getUserId();console.log("Current Rybbit User ID:", currentUserId);```+## Page Change Callbacks++Register callbacks that execute when the page or route changes. This is useful for integrating with third-party tools or triggering custom logic on navigation.++### Syntax++```typescript+rybbit.onPageChange(callback: (newPath: string, previousPath: string) => void): () => void;+```++### Parameters++- **`callback`** (`function`, Required): Function to execute on page change. Receives:+ - `newPath`: The new pathname+ - `previousPath`: The previous pathname++### Returns++Returns an unsubscribe function to remove the callback.++### Example++```javascript+// Register a callback+const unsubscribe = rybbit.onPageChange((newPath, previousPath) => {+ console.log(`Navigated from ${previousPath} to ${newPath}`);++ // Example: Track scroll position reset+ window.scrollTo(0, 0);+});++// Later, to remove the callback+unsubscribe();++// Example: Multiple callbacks can be registered+rybbit.onPageChange((newPath) => {+ // Update page title+ document.title = `${newPath} - My Site`;+});++rybbit.onPageChange((newPath, previousPath) => {+ // Log navigation for debugging+ if (process.env.NODE_ENV === 'development') {+ console.log('Navigation:', { from: previousPath, to: newPath });+ }+});+```++<Callout type="info">+Callbacks are only triggered when the pathname actually changes. Multiple calls to the same path won't trigger callbacks repeatedly.+</Callout>+## CleanupIn Single Page Applications or other dynamic environments, you may need to manually clean up the listeners that the SDK sets up.@@ -256,6 +456,32 @@ In Single Page Applications or other dynamic environments, you may need to manuarybbit.cleanup();```+### What Gets Cleaned Up++- SPA route change listeners (`popstate`, `hashchange`)+- Outbound link click listeners+- Data attribute click listeners+- Error tracking listeners+- Session replay recording+- Page change callbacks+- Resets initialization state++### Example++```javascript+// In React+useEffect(() => {+ rybbit.init({+ analyticsHost: "https://api.rybbit.io/api",+ siteId: "1",+ });++ return () => {+ rybbit.cleanup();+ };+}, []);+```+## Path MatchingThese options allow you to control which page paths are tracked and how they appear in your analytics data using wildcard patterns.@@ -277,7 +503,7 @@ If a page's path matches any pattern in `skipPatterns`, the pageview for that pa```javascript// Example skipPatterns in init-rybbit.init({+await rybbit.init({// ... other optionsskipPatterns: ["/admin/**", // Skip all admin sections@@ -304,11 +530,11 @@ If a path matches both a `skipPatterns` and a `maskPatterns` pattern, **skipping```javascript// Example maskPatterns in init-rybbit.init({+await rybbit.init({// ... other optionsmaskPatterns: ["/users/*/profile", // Group all user profile views"/orders/*" // Mask specific order IDs]});-```\ No newline at end of file+```