Skip to content

πŸ“ˆ Open source, privacy-first web analytics β€” a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

Better documentation

Blue Moused07ca68c5a36
diff --git a/docs/content/docs/analytics-dashboard/captcha.mdx b/docs/content/docs/analytics-dashboard/captcha.mdx
index d183e1fba..311fdea2d 100644
--- a/docs/content/docs/analytics-dashboard/captcha.mdx
+++ b/docs/content/docs/analytics-dashboard/captcha.mdx
@@ -13,7 +13,7 @@ The Captcha Analytics dashboard provides detailed insights into how users are in
Swetrix offers a privacy-friendly, cookieless CAPTCHA solution that uses a Proof of Work mechanism. This dashboard allows you to track the performance of this feature and ensure legitimate users are successfully accessing your protected content while bots are kept at bay.
<Callout type="info">
-For more details on how Swetrix CAPTCHA works and how to integrate it, please refer to the [Captcha documentation](../captcha/introduction.md).
+For more details on how Swetrix CAPTCHA works and how to integrate it, please refer to the [Captcha documentation](/captcha/introduction).
</Callout>
diff --git a/docs/content/docs/analytics-dashboard/error-tracking.mdx b/docs/content/docs/analytics-dashboard/error-tracking.mdx
index d732e364f..b6d51afc7 100644
--- a/docs/content/docs/analytics-dashboard/error-tracking.mdx
+++ b/docs/content/docs/analytics-dashboard/error-tracking.mdx
@@ -12,10 +12,10 @@ Error Tracking allows you to monitor and analyse exceptions that occur in your w
To start collecting errors, you need to integrate the error tracking functionality into your website. You can do this automatically by enabling the global error listener or by manually reporting errors.
-Please refer to the [Script Reference](../script-reference.md#trackerrors) for detailed installation and usage instructions:
+Please refer to the [Script Reference](/swetrix-js-reference#trackerrors) for detailed installation and usage instructions:
-- [**swetrix.trackErrors()**](../script-reference.md#trackerrors): Automatically captures unhandled exceptions.
-- [**swetrix.trackError()**](../script-reference.md#trackerror): Manually reports specific errors.
+- [**swetrix.trackErrors()**](/swetrix-js-reference#trackerrors): Automatically captures unhandled exceptions.
+- [**swetrix.trackError()**](/swetrix-js-reference#trackerror): Manually reports specific errors.
## Aggregated Errors View
@@ -94,4 +94,4 @@ You don't have to constantly check the dashboard to stay on top of issues. You c
- **New errors** are detected (useful for catching regressions after a deployment).
- The **total number of errors** exceeds a certain threshold.
-Learn more about setting up these notifications in the [Alerts](./alerts.md) documentation.
+Learn more about setting up these notifications in the [Alerts](/analytics-dashboard/alerts) documentation.
diff --git a/docs/content/docs/analytics-dashboard/revenue-tracking.mdx b/docs/content/docs/analytics-dashboard/revenue-tracking.mdx
index 6b8f7714d..9f760d4fb 100644
--- a/docs/content/docs/analytics-dashboard/revenue-tracking.mdx
+++ b/docs/content/docs/analytics-dashboard/revenue-tracking.mdx
@@ -3,30 +3,115 @@ title: Revenue Tracking
slug: /analytics-dashboard/revenue-tracking
---
-Swetrix allows you to track revenue generated by your users, giving you insights into your project's financial performance alongside your analytics data.
+Swetrix integrates with **Stripe** and **Paddle** to automatically track your revenue alongside your analytics data. Once connected, you can see revenue trends, refunds, and per-user attribution directly in your traffic dashboard β€” no code changes required.
-## Overview
+## How it works
-Revenue tracking enables you to:
+1. You connect your payment provider (Stripe or Paddle) in your project settings.
+2. Swetrix syncs your transaction data every 30 minutes using read-only API access.
+3. Revenue appears as a metric in your [Traffic Analytics](/analytics-dashboard/traffic) chart, broken down by the same time periods and filters you already use.
-- Monitor total revenue and trends over time.
-- Attribute revenue to specific users (profiles).
-- Integrate seamlessly with payment providers like Stripe and Paddle.
+Revenue is displayed as stacked bars on the chart: net revenue in solid orange, with refunds overlaid on top.
-## Configuration
+## Supported providers
-To set up revenue tracking:
+| Provider | Connection method | Transaction types |
+| -------- | ------------------------------ | ------------------------------------------- |
+| Stripe | Restricted API key (read-only) | Sales, subscriptions, refunds |
+| Paddle | API key | Sales, subscriptions, refunds (adjustments) |
-1. Go to your project dashboard.
-2. Navigate to **Project Settings**.
-3. Click on the **Revenue** tab.
+## Setting up Stripe
-Here you can connect your Stripe or Paddle account. Once connected, Swetrix will automatically start tracking revenue events associated with your project.
+1. Go to your project dashboard and open **Project Settings > Revenue**.
+2. Select **Stripe** as the provider.
+3. Create a restricted API key in your Stripe dashboard. Swetrix needs the following read-only permissions:
+ - Charges, Subscriptions, Customers, Payment Intents, Checkout Sessions, Invoices, Products (read)
+ - Webhooks (write β€” for real-time sync)
-## User Attribution
+<Callout type="info">
+ The settings page includes a direct link to create a Stripe restricted key with the correct
+ permissions pre-selected β€” just click "Create key on Stripe" and confirm.
+</Callout>
-To correctly attribute revenue to specific users, you need to ensure that the user's `profileId` is consistent between Swetrix and your payment provider.
+4. Paste the restricted key (starts with `rk_live_`) into the API key field.
+5. Choose your preferred display currency (USD, EUR, or GBP). Swetrix will convert all transactions to this currency automatically.
+6. Click **Connect**.
-Swetrix generates a `profileId` for users (or you can supply your own). When a user makes a purchase, you should ensure that this identifier is passed to the payment provider so that the revenue event can be linked back to the correct user profile in Swetrix.
+## Setting up Paddle
-For more details on handling `profileId` in your application, refer to the [Script Reference](/swetrix-js-reference#init).
+1. Go to your project dashboard and open **Project Settings > Revenue**.
+2. Select **Paddle** as the provider.
+3. Generate an API key in your [Paddle dashboard](https://vendors.paddle.com/) with the following permissions:
+ - Transactions, Subscriptions, Customers, Products, Prices (read)
+4. Paste the API key (starts with `pdl_live_`) into the API key field.
+5. Choose your display currency and click **Connect**.
+
+## Viewing revenue data
+
+Once connected, a **Revenue** metric becomes available in the Traffic Analytics chart. Toggle it on using the metric selector above the chart.
+
+The chart displays:
+
+- **Revenue** β€” total net revenue for each time bucket (hour, day, week, etc.)
+- **Refunds** β€” refund amounts stacked on top for visual comparison
+
+You can combine revenue with any other metric (pageviews, sessions, etc.) and use all standard dashboard features: date ranges, comparisons, filters, and segments.
+
+## User attribution
+
+Swetrix can attribute revenue to specific visitors using profile IDs. This lets you see which users generated revenue and connect purchases to browsing sessions.
+
+### How attribution works
+
+When Swetrix syncs transactions, it looks for a `swetrix_profile_id` field in the transaction metadata:
+
+- **Stripe**: checks `metadata.swetrix_profile_id` on the PaymentIntent or Charge
+- **Paddle**: checks `custom_data.swetrix_profile_id` on the Transaction
+
+If found, the transaction is linked to that visitor's profile in the [Profiles & Sessions](/analytics-dashboard/profiles-and-sessions) view.
+
+### Passing the profile ID to your payment provider
+
+First, get the visitor's profile ID using the Swetrix script:
+
+```javascript
+const profileId = await swetrix.getProfileId();
+```
+
+Then include it when creating a payment:
+
+**Stripe example (server-side):**
+
+```javascript
+const paymentIntent = await stripe.paymentIntents.create({
+ amount: 2000,
+ currency: "usd",
+ metadata: {
+ swetrix_profile_id: profileId,
+ },
+});
+```
+
+**Paddle example (client-side checkout):**
+
+```javascript
+Paddle.Checkout.open({
+ items: [{ priceId: "pri_xxxxx", quantity: 1 }],
+ customData: {
+ swetrix_profile_id: profileId,
+ },
+});
+```
+
+You can also pass `swetrix_session_id` (from [`getSessionId()`](/swetrix-js-reference#getsessionid)) to attribute revenue to a specific browsing session.
+
+<Callout type="info">
+ See the [Script Reference](/swetrix-js-reference#getprofileid) for full details on
+ `getProfileId()` and `getSessionId()`.
+</Callout>
+
+## Managing your connection
+
+You can disconnect or change your payment provider at any time from **Project Settings > Revenue**. Disconnecting removes the API key but keeps previously synced revenue data in your dashboard.
+
+To change the display currency after connecting, use the currency selector on the same settings page. Currency conversion is applied to all transactions (past and future) based on exchange rates at sync time.
diff --git a/docs/content/docs/analytics-dashboard/traffic.mdx b/docs/content/docs/analytics-dashboard/traffic.mdx
index 72fb69ce9..647098c44 100644
--- a/docs/content/docs/analytics-dashboard/traffic.mdx
+++ b/docs/content/docs/analytics-dashboard/traffic.mdx
@@ -91,7 +91,7 @@ You can also **Compare** the current period with a previous one (e.g., "Previous
You can save specific filter configurations as **Segments** to quickly access them later. This is useful for frequently analyzing specific user groups, such as "Mobile Users from US" or "Paid Traffic".
-- [Learn more about Segments](./segments.md)
+- [Learn more about Segments](/analytics-dashboard/segments)
## Annotations
@@ -99,7 +99,7 @@ Annotations allow you to mark significant events directly on your chart, such as
To create an annotation, simply **right-click** on a data point on the chart and select "Add annotation".
-- [Learn more about Annotations](../sitesettings/annotations.md)
+- [Learn more about Annotations](/annotations)
## Exporting Data
diff --git a/docs/content/docs/error-tracking.mdx b/docs/content/docs/error-tracking.mdx
index 6af2f1801..73960c259 100644
--- a/docs/content/docs/error-tracking.mdx
+++ b/docs/content/docs/error-tracking.mdx
@@ -4,10 +4,94 @@ slug: /error-tracking
icon: Bug
---
-As well as providing you with regular data insights such as traffic or site speed, Swetrix also offers client-side error tracking.
-This allows you to track when, on which pages and what kind of errors your users are experiencing. The error tracking script is included in swetrix.js by default and can be easily enabled with a [one line of code](/swetrix-js-reference#trackerrors).
+Swetrix provides built-in client-side error tracking alongside your analytics. Monitor when, where, and what kind of errors your users encounter β€” complete with stack traces, affected sessions, and detailed breakdowns by device, browser, and page.
+
+<img alt="Error tracking dashboard" src="/assets/screenshot_errors_light.png" />
+
+## Quick setup
+
+Error tracking is bundled with the Swetrix tracking script. Enable it by calling `trackErrors()` after initialising Swetrix:
+
+### Script tag
+
+```html
+<script src="https://swetrix.org/swetrix.js" defer></script>
+<script>
+ document.addEventListener("DOMContentLoaded", function () {
+ swetrix.init("YOUR_PROJECT_ID");
+ swetrix.trackViews();
+ swetrix.trackErrors();
+ });
+</script>
+```
+
+### NPM package
+
+```javascript
+import * as Swetrix from "swetrix";
+
+Swetrix.init("YOUR_PROJECT_ID");
+Swetrix.trackViews();
+Swetrix.trackErrors();
+```
+
+That's it β€” unhandled errors will now be captured and sent to your Swetrix dashboard automatically.
+
+## What gets tracked
+
+Each error event includes:
+
+- **Error name and message** β€” e.g. `TypeError: Cannot read properties of undefined`
+- **File, line, and column** β€” pinpoints where the error occurred
+- **Stack trace** β€” the full call stack for debugging
+- **Page URL** β€” which page the user was on
+- **Locale and timezone** β€” user's language and region
+- **Custom metadata** β€” attach your own context via the `callback` option
+
+## Manual error reporting
+
+You can also report errors manually using `trackError()`. This is useful for catching errors in `try/catch` blocks or logging errors from third-party libraries:
+
+```javascript
+swetrix.trackError({
+ name: "PaymentError",
+ message: "Card declined",
+ meta: {
+ provider: "stripe",
+ step: "checkout",
+ },
+});
+```
+
+## Configuration options
+
+You can fine-tune error tracking with options like `sampleRate` (to control how many errors are sent) and `callback` (to filter or enrich error data before sending):
+
+```javascript
+swetrix.trackErrors({
+ sampleRate: 0.5,
+ callback: (error) => {
+ if (error.message.includes("ResizeObserver")) return false;
+ return error;
+ },
+});
+```
+
+See the full [tracking script reference](/swetrix-js-reference#trackerrors) for all available options.
+
+## Dashboard features
+
+Once errors start coming in, the **Errors** tab in your project dashboard gives you:
+
+- **Aggregated error list** β€” errors grouped by signature with occurrence counts, affected users, and last-seen timestamps
+- **Error details** β€” full stack traces, metadata, and affected sessions for each error
+- **Status management** β€” mark errors as Resolved; Swetrix auto-detects regressions
+- **Breakdowns** β€” slice error data by country, browser, OS, device type, and page
+- **Real-time alerts** β€” get notified via Email, Slack, Discord, or Telegram when new errors appear
+
+Learn more about the error tracking dashboard in the [Error Tracking dashboard guide](/analytics-dashboard/error-tracking).
<Callout type="info">
- Error tracking is included in all plans and is charged as 1 error event = 1 regular event (like a
+ Error tracking is included in all plans. Each error event counts as 1 regular event (same as a
pageview or custom event).
</Callout>
diff --git a/docs/content/docs/script-reference.mdx b/docs/content/docs/script-reference.mdx
index 19bde5b93..2748e8e36 100644
--- a/docs/content/docs/script-reference.mdx
+++ b/docs/content/docs/script-reference.mdx
@@ -299,7 +299,9 @@ Arguments:
## getProfileId()
-Gets the anonymous profile ID for the current visitor. If `profileId` was set via `init`, returns that. Otherwise, requests server to generate one from IP/UA hash. This ID can be used for revenue attribution.
+Gets the anonymous profile ID for the current visitor. If `profileId` was set via `init`, returns that. Otherwise, requests server to generate one from IP/UA hash.
+
+This ID is commonly used for [revenue attribution](/analytics-dashboard/revenue-tracking#user-attribution) β€” pass it as `swetrix_profile_id` in your payment provider's metadata to link transactions to specific visitors.
```javascript
const profileId = await swetrix.getProfileId();