π 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!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
Add more integrations
Blue Mouseaeff2f7a797b
diff --git a/docs/docs/integrations/angular.md b/docs/docs/integrations/angular.mdnew file mode 100644index 000000000..674bea2e5--- /dev/null+++ b/docs/docs/integrations/angular.md@@ -0,0 +1,318 @@+---+title: Angular+slug: /angular-integration+---++Integrate Swetrix with your [Angular](https://angular.dev/) application to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++## Installation++Install the Swetrix npm package:++```bash+npm install swetrix+```++### Basic setup (without routing)++If your app doesn't use the Angular Router, you can initialise Swetrix once in your root component.++Open `src/app/app.component.ts`:++```typescript+import { Component, OnInit } from '@angular/core'+import * as Swetrix from 'swetrix'++@Component({+ selector: 'app-root',+ templateUrl: './app.component.html',+})+export class AppComponent implements OnInit {+ ngOnInit() {+ Swetrix.init('YOUR_PROJECT_ID')+ Swetrix.trackViews()+ }+}+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### With Angular Router++Most Angular apps use the built-in [Router](https://angular.dev/guide/routing) for client-side navigation. Since route changes don't trigger full page loads, you need to notify Swetrix about each navigation so page views are tracked correctly.++The recommended approach is to create a dedicated service.++**1. Create an analytics service**++Create `src/app/services/analytics.service.ts`:++```typescript+import { Injectable } from '@angular/core'+import { NavigationEnd, Router } from '@angular/router'+import { filter } from 'rxjs/operators'+import * as Swetrix from 'swetrix'++@Injectable({ providedIn: 'root' })+export class AnalyticsService {+ constructor(private router: Router) {}++ init() {+ Swetrix.init('YOUR_PROJECT_ID')+ Swetrix.trackViews()++ this.router.events+ .pipe(filter((event) => event instanceof NavigationEnd))+ .subscribe(() => {+ Swetrix.trackViews()+ })+ }+}+```++**2. Call it from your root component**++Open `src/app/app.component.ts`:++```typescript+import { Component, OnInit } from '@angular/core'+import { AnalyticsService } from './services/analytics.service'++@Component({+ selector: 'app-root',+ templateUrl: './app.component.html',+})+export class AppComponent implements OnInit {+ constructor(private analytics: AnalyticsService) {}++ ngOnInit() {+ this.analytics.init()+ }+}+```++:::tip+If you're using **standalone components** (Angular 14+), the same pattern works β just make sure `AnalyticsService` is provided at the application level via `providedIn: 'root'`.+:::++### Noscript fallback (optional)++To track visitors who have JavaScript disabled, add a noscript image pixel to your `src/index.html`:++```html+<body>+ <app-root></app-root>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+</body>+```++## Disable tracking in development++By default, Swetrix ignores `localhost` traffic. You can also explicitly disable it using Angular's environment files.++**1. Define the flag in your environments**++`src/environments/environment.ts` (production):++```typescript+export const environment = {+ production: true,+ swetrixDisabled: false,+}+```++`src/environments/environment.development.ts`:++```typescript+export const environment = {+ production: false,+ swetrixDisabled: true,+}+```++**2. Use it during initialisation**++```typescript+import { environment } from '../environments/environment'+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID', {+ disabled: environment.swetrixDisabled,+})+```++:::tip+If you want to verify tracking locally during development, set `devMode: true` instead:++```typescript+Swetrix.init('YOUR_PROJECT_ID', {+ devMode: true,+})+```++Remember to remove this before deploying to production.+:::++## Check your installation++Build and deploy your application (or temporarily enable `devMode`) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring by adding `trackErrors()` to your analytics service. This captures unhandled JavaScript errors and reports them to Swetrix.++Update your `AnalyticsService`:++```typescript+init() {+ Swetrix.init('YOUR_PROJECT_ID')+ Swetrix.trackViews()+ Swetrix.trackErrors()++ this.router.events+ .pipe(filter((event) => event instanceof NavigationEnd))+ .subscribe(() => {+ Swetrix.trackViews()+ })+}+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β button clicks, form submissions, sign-ups, purchases, and more. Import `swetrix` in any component and call `track()`.++### Example: tracking button clicks++```typescript+import { Component } from '@angular/core'+import * as Swetrix from 'swetrix'++@Component({+ selector: 'app-signup-button',+ template: '<button (click)="onClick()">Sign up</button>',+})+export class SignUpButtonComponent {+ onClick() {+ Swetrix.track({+ ev: 'SIGNUP_CTA_CLICK',+ meta: {+ location: 'navbar',+ },+ })+ }+}+```++### Example: tracking form submissions++```typescript+import { Component } from '@angular/core'+import * as Swetrix from 'swetrix'++@Component({+ selector: 'app-contact-form',+ template: `+ <form (ngSubmit)="onSubmit()">+ <input type="email" placeholder="[email protected]" required />+ <textarea placeholder="How can we help?" required></textarea>+ <button type="submit">Send</button>+ </form>+ `,+})+export class ContactFormComponent {+ onSubmit() {+ Swetrix.track({+ ev: 'CONTACT_FORM_SUBMITTED',+ meta: {+ source: 'support_page',+ },+ })++ // ...submit logic+ }+}+```++### Example: tracking outbound links with a directive++Create a reusable directive for external links:++```typescript+import { Directive, HostListener, Input } from '@angular/core'+import * as Swetrix from 'swetrix'++@Directive({ selector: 'a[appTrackOutbound]' })+export class TrackOutboundDirective {+ @Input() appTrackOutbound = 'OUTBOUND_CLICK'++ @HostListener('click', ['$event.target'])+ onClick(target: HTMLAnchorElement) {+ Swetrix.track({+ ev: this.appTrackOutbound,+ meta: { url: target.href },+ })+ }+}+```++Usage in a template:++```html+<a href="https://example.com" target="_blank" appTrackOutbound>Visit Example</a>++<!-- With a custom event name -->+<a href="https://partner.com" target="_blank" appTrackOutbound="PARTNER_LINK_CLICK">+ Our partner+</a>+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `SIGNUP_CTA_CLICK`, `CONTACT_FORM_SUBMITTED`).++## Using environment variables for your Project ID++Rather than hardcoding your Project ID, you can store it in Angular's environment files.++**1. Add to your environment files:**++`src/environments/environment.ts`:++```typescript+export const environment = {+ production: true,+ swetrixPid: 'YOUR_PROJECT_ID',+}+```++**2. Use it in your analytics service:**++```typescript+import { environment } from '../../environments/environment'+import * as Swetrix from 'swetrix'++Swetrix.init(environment.swetrixPid)+```++## Further reading++- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.+- [Angular documentation](https://angular.dev/) β official Angular docs for routing, services, directives, and more.diff --git a/docs/docs/integrations/astro.md b/docs/docs/integrations/astro.mdnew file mode 100644index 000000000..0e6df6a49--- /dev/null+++ b/docs/docs/integrations/astro.md@@ -0,0 +1,390 @@+---+title: Astro+slug: /astro-integration+---++Integrate Swetrix with your [Astro](https://astro.build/) application to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++Astro is a web framework designed for content-rich websites that ships minimal JavaScript to the browser by default. This guide covers both the **CDN script** approach and the **npm package** approach, including support for Astro's **View Transitions**.++## Installation++There are two ways to add Swetrix to your Astro site:++| Approach | Best for |+| --- | --- |+| **CDN script** | Simple sites, blogs, and documentation β no build-time dependency required |+| **npm package** | Full TypeScript support, tighter integration with island components, more configuration options |++### Option A: CDN script (recommended for most sites)++The simplest way to add Swetrix is to include the tracking script in a shared layout component. No npm install needed.++**1. Add the script to your layout**++Open your base layout (e.g. `src/layouts/Layout.astro`) and add the Swetrix script inside the `<head>`:++```html+---+// src/layouts/Layout.astro+export interface Props {+ title: string;+}++const { title } = Astro.props;+---+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width" />+ <title>{title}</title>++ <!-- Swetrix Analytics -->+ <script src="https://swetrix.org/swetrix.js" defer></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>+ </head>+ <body>+ <slot />+ </body>+</html>+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++**2. Use the layout on your pages**++Make sure your pages use this layout so the script is included on every page:++```html+---+// src/pages/index.astro+import Layout from '../layouts/Layout.astro';+---++<Layout title="Home">+ <h1>Welcome to my site</h1>+</Layout>+```++Since Astro builds multi-page applications by default, each navigation triggers a full page load and Swetrix will automatically track each page view.++### Option B: npm package++If you want full TypeScript support or need fine-grained control (e.g. custom init options, programmatic event tracking from island components), install the npm package instead.++```bash+npm install swetrix+```++Create a client-side script that initialises Swetrix and add it to your layout.++**1. Create the analytics script**++Create `src/scripts/analytics.ts`:++```typescript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+```++**2. Include it in your layout**++Add the script to your base layout with the `client:load` directive via a `<script>` tag:++```html+---+// src/layouts/Layout.astro+export interface Props {+ title: string;+}++const { title } = Astro.props;+---+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width" />+ <title>{title}</title>+ </head>+ <body>+ <slot />+ <script>+ import * as Swetrix from 'swetrix'++ Swetrix.init('YOUR_PROJECT_ID')+ Swetrix.trackViews()+ </script>+ </body>+</html>+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++:::tip+Astro processes `<script>` tags β they're bundled and deduplicated automatically. The script above will only be included once in the final build, even if the layout is used on every page.+:::++## View Transitions support++If you're using [Astro's View Transitions](https://docs.astro.build/en/guides/view-transitions/) for client-side navigation, page changes won't trigger full page loads. You need to tell Swetrix about these navigations so page views are tracked correctly.++### CDN script approach++Update your layout's inline script to listen for the `astro:after-swap` event:++```html+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })++ document.addEventListener('astro:after-swap', function () {+ swetrix.trackViews()+ })+</script>+```++### npm package approach++Update your analytics script:++```typescript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()++document.addEventListener('astro:after-swap', () => {+ Swetrix.trackViews()+})+```++:::tip+If you're **not** using View Transitions, you don't need the `astro:after-swap` listener β standard MPA navigation handles page view tracking automatically.+:::++### Noscript fallback (optional)++To track visitors who have JavaScript disabled, add a noscript image pixel to your layout's `<body>`:++```html+<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+```++## Disable tracking in development++By default, Swetrix ignores `localhost` traffic. If you want to be explicit about it, you can conditionally disable tracking in development.++**CDN script** β wrap the initialisation in a host check:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ var isDev = window.location.hostname === 'localhost'++ swetrix.init('YOUR_PROJECT_ID', { disabled: isDev })+ swetrix.trackViews()+ })+</script>+```++**npm package** β use `import.meta.env`:++```typescript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID', {+ disabled: import.meta.env.DEV,+})+Swetrix.trackViews()+```++:::tip+If you want to verify tracking locally during development, set `devMode: true` instead:++```typescript+Swetrix.init('YOUR_PROJECT_ID', {+ devMode: true,+})+```++Remember to remove this before deploying to production.+:::++## Check your installation++Build and deploy your site (or temporarily enable `devMode`) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring to capture unhandled JavaScript errors and report them to Swetrix.++**CDN script:**++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ swetrix.trackErrors()+ })+</script>+```++**npm package:**++```typescript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+Swetrix.trackErrors()+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β button clicks, form submissions, downloads, and more.++### In Astro components++Use a `<script>` tag with client-side JavaScript to track events from `.astro` components:++```html+---+// src/components/DownloadButton.astro+---+<button id="download-btn">Download PDF</button>++<script>+ document.getElementById('download-btn')?.addEventListener('click', () => {+ if (window.swetrix) {+ swetrix.track({ ev: 'PDF_DOWNLOAD' })+ }+ })+</script>+```++If you're using the npm package, you can import it directly:++```html+---+// src/components/DownloadButton.astro+---+<button id="download-btn">Download PDF</button>++<script>+ import * as Swetrix from 'swetrix'++ document.getElementById('download-btn')?.addEventListener('click', () => {+ Swetrix.track({+ ev: 'PDF_DOWNLOAD',+ meta: { format: 'pdf' },+ })+ })+</script>+```++### In framework island components++If you're using [Astro islands](https://docs.astro.build/en/concepts/islands/) with React, Vue, Svelte, or another UI framework, you can track events from within those components. Just import the npm package and call `track()` as usual.++**React island example:**++```tsx+// src/components/SignUpForm.tsx+import * as Swetrix from 'swetrix'++export default function SignUpForm() {+ const handleSubmit = (e: React.FormEvent) => {+ e.preventDefault()++ Swetrix.track({+ ev: 'SIGNUP_FORM_SUBMITTED',+ meta: { source: 'landing_page' },+ })++ // ...submit logic+ }++ return (+ <form onSubmit={handleSubmit}>+ <input type="email" placeholder="[email protected]" required />+ <button type="submit">Sign up</button>+ </form>+ )+}+```++Then use it in your Astro page with a `client:*` directive:++```html+---+// src/pages/index.astro+import Layout from '../layouts/Layout.astro';+import SignUpForm from '../components/SignUpForm';+---++<Layout title="Home">+ <SignUpForm client:load />+</Layout>+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `PDF_DOWNLOAD`, `SIGNUP_FORM_SUBMITTED`).++## Using environment variables for your Project ID++Rather than hardcoding your Project ID, you can use Astro's built-in environment variable support.++**1. Add to your `.env` file:**++```+PUBLIC_SWETRIX_PID=YOUR_PROJECT_ID+```++**2. Reference it in your analytics script** (npm package approach):++```typescript+import * as Swetrix from 'swetrix'++Swetrix.init(import.meta.env.PUBLIC_SWETRIX_PID)+Swetrix.trackViews()+```++Astro requires client-side environment variables to be prefixed with `PUBLIC_`.++## Further reading++- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.+- [Astro documentation](https://docs.astro.build/) β official Astro docs for layouts, View Transitions, islands, and more.diff --git a/docs/docs/integrations/bigcommerce.md b/docs/docs/integrations/bigcommerce.mdnew file mode 100644index 000000000..248d04325--- /dev/null+++ b/docs/docs/integrations/bigcommerce.md@@ -0,0 +1,144 @@+---+title: BigCommerce+slug: /bigcommerce-integration+---++Integrate Swetrix with your BigCommerce store to track page views, monitor user behaviour, and capture key e-commerce events like purchases.++## Installation++BigCommerce's built-in **Script Manager** is the simplest way to add external scripts without editing theme files.++### 1. Open Script Manager++1. Log in to your BigCommerce admin panel.+2. Navigate to **Storefront > Script Manager**.+3. Click **Create a Script**.++### 2. Add the Swetrix tracking script++Fill in the script settings as follows:++| Setting | Value |+| ----------------- | ----------------------- |+| Name | Swetrix Analytics |+| Description | Swetrix tracking script |+| Placement | **Head** |+| Location | **All pages** |+| Script category | **Analytics** |+| Script type | **Script** |++In the **Script contents** box, paste:++```html+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+```++### 3. Save++Click **Save** to activate the script across your store.++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the Swetrix dashboard, otherwise tracking won't work.+:::++## Check your installation++Visit your storefront and browse a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.++If nothing shows up, open your browser's developer console and confirm the Swetrix script is loading without errors.++## Tracking e-commerce events++Beyond basic page views, you can track key e-commerce interactions as custom events by creating additional scripts in Script Manager. These use Swetrix's `swetrix.track()` function with the `meta` parameter to attach event context.++You can view these events and their metadata in the **Custom events** section of your Swetrix dashboard. Refer to the [tracking script reference](/swetrix-js-reference) for full API details.++:::note+BigCommerce uses [Handlebars templating](https://developer.bigcommerce.com/docs/storefront/stencil/themes/context/handlebars-reference). The `{{double curly brace}}` syntax in the snippets below is processed server-side by BigCommerce to inject dynamic store data β it is not JavaScript template literal syntax.+:::++### Purchase completed++Track confirmed purchases on the order confirmation page by creating a second script in Script Manager.++1. In **Storefront > Script Manager**, click **Create a Script**.+2. Configure it with these settings:++| Setting | Value |+| ----------------- | -------------------------- |+| Name | Swetrix Purchase Tracking |+| Description | Tracks completed purchases |+| Placement | **Footer** |+| Location | **Order Confirmation** |+| Script category | **Analytics** |+| Script type | **Script** |++3. In the **Script contents** box, paste:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ if (typeof swetrix === 'undefined') return++ {{#if checkout.order}}+ swetrix.track({+ ev: 'purchase',+ meta: {+ order_id: '{{checkout.order.id}}',+ total: '{{checkout.subtotal.value}}',+ currency: '{{checkout.currency.code}}'+ }+ })+ {{/if}}+ })+</script>+```++4. Click **Save**.++The `{{#if checkout.order}}` Handlebars block ensures the event only fires when valid order data is present.++:::tip+Test by placing a small test order and checking the **Custom events** section in your Swetrix dashboard. You should see a `purchase` event with the order metadata.+:::++## Troubleshooting++### Script not loading++- Open **Script Manager** and make sure the script's status is enabled.+- Clear your store's cache: go to **Server Settings > Store-level caching** and click **Purge cache**.+- Check the browser developer console for errors. A Content Security Policy (CSP) may be blocking the external script β contact BigCommerce support if you see CSP-related errors.++### Page views not appearing++- Confirm you replaced `YOUR_PROJECT_ID` with your real project ID.+- Check that **Location** is set to **All pages**, not a specific page type.+- Disable any browser extensions (like ad blockers) that may be blocking analytics scripts, then reload.++### Purchase events not tracking++- Verify the purchase script's **Location** is set to **Order Confirmation** β other locations won't have access to the `checkout` Handlebars object.+- Complete a real test order. BigCommerce does not render the order confirmation page in preview mode.+- Make sure the Handlebars variable names (`checkout.order.id`, `checkout.subtotal.value`, `checkout.currency.code`) match your BigCommerce version and storefront setup. Check BigCommerce's [Stencil documentation](https://developer.bigcommerce.com/docs/storefront/stencil/themes/context/object-reference/schemas) for the available objects on the order confirmation page.++## Important considerations++- **Script Manager vs. theme files.** Script Manager is the recommended approach because scripts persist across theme changes. If you edit Stencil theme templates directly instead, your changes will be overwritten when you update or switch themes.+- **Handlebars context.** Not all Handlebars objects are available on every page. The `checkout` object is only accessible on the order confirmation page. If you attempt to reference it elsewhere, the template will silently output nothing.+- **Testing.** After adding each script, use your browser's developer console to verify there are no JavaScript errors, and check that events appear in your Swetrix dashboard.diff --git a/docs/docs/integrations/bubble.md b/docs/docs/integrations/bubble.mdnew file mode 100644index 000000000..d32d42037--- /dev/null+++ b/docs/docs/integrations/bubble.md@@ -0,0 +1,215 @@+---+title: Bubble.io+slug: /bubble-integration+---++Integrate Swetrix with your [Bubble.io](https://bubble.io/) application to track page views, monitor errors, and capture custom events β all without writing backend code.++Bubble lets you add custom scripts globally through its settings panel, making Swetrix integration straightforward even on the free plan.++## Installation++### 1. Open your app settings++1. Open your Bubble application in the editor.+2. Click **Settings** in the left-hand sidebar.+3. Select the **SEO / metatags** tab.++### 2. Add the Swetrix tracking script++Scroll down to **Script/meta tags in header** and paste the following snippet. This injects the script into the `<head>` of every page in your app:++```html+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### 3. Deploy to live++The script you added in the editor only takes effect on your live app after you deploy. Click **Deploy to live** (or use the **Deployment** menu) to publish the changes.++## Check your installation++Open your live Bubble app in a browser and navigate through a few pages. Within a minute you should see pageviews appearing in your Swetrix dashboard.++You can also open your browser's developer tools, switch to the **Network** tab, and confirm that `swetrix.js` loads successfully.++## Page view tracking in Bubble apps++Bubble applications behave like single-page applications (SPAs) β navigating between "pages" often swaps content without a full browser reload. Swetrix's `trackViews()` listens for History API changes, so page transitions that update the URL are tracked automatically.++There are a few scenarios to be aware of:++- **URL-based navigation** (the default for multi-page Bubble apps) β tracked automatically. No extra work needed.+- **Group-based navigation without URL changes** β if you show and hide groups on the same page without changing the URL, Swetrix only records the initial page load. To capture these "virtual" page views, trigger a manual pageview call (see [Manual page views](#manual-page-views) below).+- **Hash-based routing** β if your app uses URL hashes for navigation (e.g. `/#/dashboard`), enable hash tracking in the init options:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews({ hash: true })+ })+</script>+```++### Manual page views++If your Bubble app navigates between views without changing the URL, you can fire a pageview manually when a group becomes visible. Use a **Run JavaScript** workflow action:++```javascript+if (typeof swetrix !== 'undefined') {+ swetrix.pageview({+ payload: {+ pg: '/your-virtual-page',+ },+ })+}+```++Replace `'/your-virtual-page'` with a descriptive path for the view (e.g. `'/pricing'`, `'/signup'`).++## Error tracking++Enable automatic client-side error monitoring by adding `trackErrors()` to the initialisation snippet in **Settings > SEO / metatags**:++```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>+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you measure specific user interactions β button clicks, form submissions, signup completions, and more. In Bubble, you track these by running JavaScript from a workflow.++### Setting up the "Run JavaScript" action++Bubble doesn't include a built-in JavaScript action by default. You need the free **Toolbox** plugin:++1. In the Bubble editor, go to **Plugins > Add plugins**.+2. Search for **Toolbox** and install it.+3. You'll now have access to the **Run JavaScript** workflow action.++### Creating an event workflow++1. Open the **Workflow** tab.+2. Create a new workflow triggered by the interaction you want to track (e.g. **When Button "Sign Up" is clicked**).+3. Add a **Run JavaScript** action and paste your tracking code:++```javascript+if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'SIGNUP_CLICKED',+ })+}+```++### Passing dynamic data++Bubble lets you insert dynamic expressions into the JavaScript action. You can use this to attach contextual metadata:++```javascript+if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'ITEM_ADDED_TO_CART',+ meta: {+ item_name: 'DYNAMIC_ITEM_NAME',+ category: 'DYNAMIC_CATEGORY',+ },+ })+}+```++Replace the placeholder strings with Bubble's **Insert dynamic data** feature inside the Run JavaScript editor β Bubble will substitute them with actual values at runtime.++:::tip+You can pass up to 20 metadata keys per event. Values are converted to strings and the combined length of all values must be under 1,000 characters. See the [tracking script reference](/swetrix-js-reference#track) for full details.+:::++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `SIGNUP_CLICKED`, `ITEM_ADDED_TO_CART`).++### Example: tracking a form submission++```javascript+if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'CONTACT_FORM_SUBMITTED',+ meta: {+ page: window.location.pathname,+ },+ })+}+```++### Example: tracking a purchase++```javascript+if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'PURCHASE_COMPLETED',+ meta: {+ plan: 'DYNAMIC_PLAN_NAME',+ price: 'DYNAMIC_PRICE',+ },+ })+}+```++## Troubleshooting++### Script not loading++- Make sure you pasted the snippet into **Settings > SEO / metatags > Script/meta tags in header**, not into a page element.+- Verify that you deployed the latest version to live β editor preview may not always include header scripts.+- Check the browser developer console for Content Security Policy (CSP) errors. If your Bubble app uses a custom domain with strict CSP headers, you may need to allow `swetrix.org` and `api.swetrix.com`.++### Page views not appearing++- Confirm you replaced `YOUR_PROJECT_ID` with your real project ID.+- Disable browser extensions (like ad blockers) that may block analytics scripts, then reload.+- If your app navigates without URL changes, Swetrix won't detect new pages automatically β use the [manual page view](#manual-page-views) approach.++### Custom events not tracking++- Ensure the **Toolbox** plugin is installed and the **Run JavaScript** action is available in your workflows.+- Wrap your tracking calls in `if (typeof swetrix !== 'undefined')` to avoid errors if the script hasn't loaded yet.+- Check the **Custom events** section in your Swetrix dashboard β events may take a moment to appear.++## Further reading++- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.+- [Bubble.io documentation](https://manual.bubble.io/) β official Bubble docs.diff --git a/docs/docs/integrations/django.md b/docs/docs/integrations/django.mdindex dcf855398..834841c47 100644--- a/docs/docs/integrations/django.md+++ b/docs/docs/integrations/django.md@@ -1,44 +1,285 @@----title: Python Django+title: Djangoslug: /django-integration----After you sign up on Swetrix and create a new project, the only thing left is to add it to your website.+Integrate Swetrix with your [Django](https://www.djangoproject.com/) application to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++This guide covers traditional Django projects using the Django template engine, as well as tips for Django REST Framework setups with a JavaScript frontend.## Installation-1. Go to your Django website codebase and open up the .html templates folder. You need to add the Swetrix tracking script to the base template which is imported by all other templates via `{% extends 'base.html' %}`.-2. In the HTML `<head>` section you need to add the following:+The recommended approach is to add the Swetrix tracking script to your base template so it loads on every page.++### 1. Add the tracking script to your base template++Django projects typically have a base template that all other templates extend via `{% extends 'base.html' %}`. Open (or create) your `templates/base.html` and add the Swetrix script inside the `<head>` tag, and the initialisation snippet before the closing `</body>` tag:```html-<script src="https://swetrix.org/swetrix.js" defer></script>+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="utf-8">+ <meta name="viewport" content="width=device-width, initial-scale=1">+ <title>{% block title %}My Site{% endblock %}</title>++ {% block styles %}{% endblock %}++ <!-- Swetrix Analytics -->+ <script src="https://swetrix.org/swetrix.js" defer></script>+</head>+<body>+ {% block content %}{% endblock %}++ <!-- Swetrix Analytics -->+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>++ {% block scripts %}{% endblock %}+</body>+</html>+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### 2. Disable tracking in development (recommended)++To avoid polluting your analytics with local page views, use Django's `settings.DEBUG` flag to only include the script in production. First, make sure `DEBUG` is available in your templates by adding `django.template.context_processors.debug` to your context processors (it's included by default).++Then wrap the snippets:++```html+{% if not debug %}+ <script src="https://swetrix.org/swetrix.js" defer></script>+{% endif %}+```++And for the body initialisation:++```html+{% if not debug %}+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+{% endif %}+```++:::tip+During development, Swetrix ignores `localhost` traffic by default. If you want to verify tracking locally without changing your environment, you can temporarily set `devMode: true`:++```js+swetrix.init('YOUR_PROJECT_ID', { devMode: true })+```++Remember to remove this before deploying.+:::++## Store your Project ID in settings (optional)++Rather than hardcoding the Project ID in your template, you can manage it through Django's settings and a custom context processor. This keeps configuration in one place and makes it easy to use different IDs per environment.++**1. Add to your settings (e.g. `settings.py`):**++```python+import os++SWETRIX_PROJECT_ID = os.environ.get('SWETRIX_PROJECT_ID', '')```-3. In the `<body>` section you need to add the following:+**2. Create a context processor (e.g. `context_processors.py` in your main app):**++```python+from django.conf import settings++def swetrix(request):+ return {+ 'SWETRIX_PROJECT_ID': getattr(settings, 'SWETRIX_PROJECT_ID', ''),+ }+```++**3. Register it in your `settings.py`:**++```python+TEMPLATES = [+ {+ 'BACKEND': 'django.template.backends.django.DjangoTemplates',+ 'OPTIONS': {+ 'context_processors': [+ # ...existing processors+ 'myapp.context_processors.swetrix',+ ],+ },+ },+]+```++**4. Reference it in your template:**++```html+{% if SWETRIX_PROJECT_ID %}+ <script src="https://swetrix.org/swetrix.js" defer></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('{{ SWETRIX_PROJECT_ID }}')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid={{ SWETRIX_PROJECT_ID }}"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+{% endif %}+```++Set the environment variable in production:++```bash+export SWETRIX_PROJECT_ID=YOUR_PROJECT_ID+```++## Check your installation++Deploy your application (or temporarily enable `devMode`) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring by adding `trackErrors()` to the initialisation snippet. This captures unhandled JavaScript errors and reports them to Swetrix.```html<script>document.addEventListener('DOMContentLoaded', function () {swetrix.init('YOUR_PROJECT_ID')swetrix.trackViews()+ swetrix.trackErrors()})</script>+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β form submissions, button clicks, feature usage, and more. Since the Swetrix script is loaded globally, you can call `swetrix.track()` from any inline script or JavaScript file.++### Example: tracking form submissions++Track when users submit a contact form:-<noscript>- <img- src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"- alt=""- referrerpolicy="no-referrer-when-downgrade"- />-</noscript>+```html+<form id="contact-form" method="POST" action="{% url 'contact' %}">+ {% csrf_token %}+ {{ form.as_p }}+ <button type="submit">Send message</button>+</form>++<script>+ document.getElementById('contact-form')?.addEventListener('submit', function () {+ if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'CONTACT_FORM_SUBMITTED',+ meta: {+ page: window.location.pathname,+ },+ })+ }+ })+</script>```-:::caution-It's very important not to forget to replace `YOUR_PROJECT_ID` with your actual Project ID you can find in the Dashboard, otherwise tracking won't work!-:::+### Example: tracking outbound links-## Check your installation+Track clicks on external links across your site. Add this to your base template:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ document.querySelectorAll('a[href^="http"]').forEach(function (link) {+ if (link.hostname !== window.location.hostname) {+ link.addEventListener('click', function () {+ if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'OUTBOUND_CLICK',+ meta: { url: link.href },+ })+ }+ })+ }+ })+ })+</script>+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `CONTACT_FORM_SUBMITTED`, `OUTBOUND_CLICK`).++## Using Swetrix with HTMX++If your Django application uses [HTMX](https://htmx.org/) for dynamic page updates, the Swetrix script loaded in your base template will still track the initial page load. For HTMX-driven navigations that change the URL (using `hx-push-url`), Swetrix's `trackViews()` automatically detects History API changes and tracks them.++If you use HTMX to swap content without changing the URL and want to track those interactions, use custom events:++```html+<button hx-post="/api/subscribe" hx-swap="outerHTML"+ onclick="if(typeof swetrix!=='undefined') swetrix.track({ ev: 'SUBSCRIBE_CLICKED' })">+ Subscribe+</button>+```++## Using Swetrix with Django and a JavaScript frontend++If you use Django as an API backend (e.g. with Django REST Framework) paired with a JavaScript frontend, add the Swetrix tracking to your frontend project instead:++```bash+npm install swetrix+```++```javascript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+```++See the relevant frontend framework integration guide ([React](/react-integration), [Vue](/vue-integration), etc.) for framework-specific details.-After installing Swetrix tracking script, go to your website and visit some pages.+## Further reading-Within a minute you should be able to see new pageviews being added to your project's dahsboard.+- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.+- [Django documentation](https://docs.djangoproject.com/) β official Django docs.diff --git a/docs/docs/integrations/eleventy.md b/docs/docs/integrations/eleventy.mdnew file mode 100644index 000000000..0bab4de76--- /dev/null+++ b/docs/docs/integrations/eleventy.md@@ -0,0 +1,264 @@+---+title: Eleventy (11ty)+slug: /eleventy-integration+---++Integrate Swetrix with your [Eleventy (11ty)](https://www.11ty.dev/) site to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++Eleventy is a simpler static site generator that builds plain HTML pages. Since there's no client-side routing by default, Swetrix tracks each page view automatically on every navigation.++## Installation++The recommended approach is to add the Swetrix tracking script to a shared layout file that wraps all your pages.++### 1. Add the script to your base layout++Open your base layout β typically `_includes/base.njk` (Nunjucks) or `_includes/base.liquid` (Liquid). If you don't have one yet, create it.++Add the Swetrix script just before the closing `</body>` tag:++**Nunjucks (`_includes/base.njk`):**++```html+<!doctype html>+<html lang="en">+ <head>+ <meta charset="UTF-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />+ <title>{{ title }}</title>+ </head>+ <body>+ {{ content | safe }}++ <script src="https://swetrix.org/swetrix.js" defer></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+ </body>+</html>+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### 2. Use the layout in your pages++Make sure your pages reference this layout. You can set it in each page's front matter:++```markdown+---+layout: base.njk+title: Home+---++# Welcome to my site+```++Or set a default layout for all pages in your Eleventy config (`eleventy.config.js` or `.eleventy.js`):++```js+module.exports = function (eleventyConfig) {+ return {+ dir: {+ input: 'src',+ includes: '_includes',+ output: '_site',+ },+ }+}+```++Then use [directory-level data files](https://www.11ty.dev/docs/data-template-dir/) to set the layout for an entire folder. For example, create `src/src.json`:++```json+{+ "layout": "base.njk"+}+```++## Disable tracking in development++Eleventy doesn't distinguish between development and production builds by default, but you can use an environment variable to conditionally include the tracking script.++**1. Set the environment variable when building for production:**++```bash+ELEVENTY_ENV=production npx @11ty/eleventy+```++**2. Expose the variable to your templates** by adding it as global data. Create `_data/env.js`:++```js+module.exports = {+ isProd: process.env.ELEVENTY_ENV === 'production',+}+```++**3. Wrap the tracking script in a conditional** in your layout:++```html+{% if env.isProd %}+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+{% endif %}+```++:::tip+By default Swetrix ignores `localhost` traffic, so the environment variable approach is optional. It's useful if you want to avoid loading the script entirely during development.+:::++## Using data files for your Project ID++To keep your Project ID out of template code, store it in a global data file.++**1. Create `_data/swetrix.js`:**++```js+module.exports = {+ projectId: process.env.SWETRIX_PID || 'YOUR_PROJECT_ID',+}+```++**2. Reference it in your layout:**++```html+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('{{ swetrix.projectId }}')+ swetrix.trackViews()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid={{ swetrix.projectId }}"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+```++Then set the `SWETRIX_PID` environment variable in your hosting provider or CI/CD pipeline.++## Check your installation++Build your site with `npx @11ty/eleventy` and deploy it (or serve locally with `npx @11ty/eleventy --serve` and `devMode: true`). Visit a few pages β within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring by adding `trackErrors()` alongside your existing initialisation. This captures unhandled JavaScript errors and reports them to Swetrix.++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ swetrix.trackErrors()+ })+</script>+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β button clicks, form submissions, downloads, and more.++Add event tracking to any page or component using inline scripts:++```html+<button id="download-btn">Download PDF</button>++<script>+ document.addEventListener('DOMContentLoaded', function () {+ var btn = document.getElementById('download-btn')+ if (!btn || typeof swetrix === 'undefined') return++ btn.addEventListener('click', function () {+ swetrix.track({ ev: 'PDF_DOWNLOAD' })+ })+ })+</script>+```++### Example: tracking form submissions++```html+<form id="contact-form" action="/thank-you">+ <input type="email" placeholder="[email protected]" required />+ <button type="submit">Subscribe</button>+</form>++<script>+ document.addEventListener('DOMContentLoaded', function () {+ var form = document.getElementById('contact-form')+ if (!form || typeof swetrix === 'undefined') return++ form.addEventListener('submit', function () {+ swetrix.track({+ ev: 'NEWSLETTER_SIGNUP',+ meta: { source: 'footer' },+ })+ })+ })+</script>+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `PDF_DOWNLOAD`, `NEWSLETTER_SIGNUP`).++## Using Eleventy with a JavaScript framework++If you're using Eleventy with a client-side JavaScript framework via [WebC](https://www.11ty.dev/docs/languages/webc/) or [Islands architecture](https://is-land.11ty.dev/), you can install the `swetrix` npm package for tighter integration:++```bash+npm install swetrix+```++Then import and use it in your client-side JavaScript:++```js+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+```++## Further reading++- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.+- [Eleventy documentation](https://www.11ty.dev/docs/) β official 11ty docs for layouts, data files, plugins, and more.diff --git a/docs/docs/integrations/flask.md b/docs/docs/integrations/flask.mdnew file mode 100644index 000000000..117f741cf--- /dev/null+++ b/docs/docs/integrations/flask.md@@ -0,0 +1,308 @@+---+title: Flask+slug: /flask-integration+---++Integrate Swetrix with your [Flask](https://flask.palletsprojects.com/) application to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++This guide covers both traditional multi-page Flask apps (using Jinja2 templates) and single-page setups with client-side routing.++## Installation++The recommended approach is to add the Swetrix tracking script to your base Jinja2 template so it loads on every page.++### 1. Add the tracking script to your base template++Flask uses Jinja2 templates, and most projects define a shared base template that other templates extend. Open (or create) your `templates/base.html` and add the Swetrix script inside the `<head>` tag, and the initialisation snippet before the closing `</body>` tag:++```html+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="utf-8">+ <meta name="viewport" content="width=device-width, initial-scale=1">+ <title>{% block title %}My App{% endblock %}</title>++ {% block styles %}{% endblock %}++ <!-- Swetrix Analytics -->+ <script src="https://swetrix.org/swetrix.js" defer></script>+</head>+<body>+ {% block content %}{% endblock %}++ <!-- Swetrix Analytics -->+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>++ {% block scripts %}{% endblock %}+</body>+</html>+```++All page templates that extend this base will automatically include the tracking script:++```html+{% extends "base.html" %}++{% block title %}Home{% endblock %}++{% block content %}+ <h1>Welcome to my Flask app</h1>+{% endblock %}+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### 2. Disable tracking in development (recommended)++To avoid polluting your analytics with local page views, wrap the snippet in an environment check so it only loads in production. You can use Flask's configuration or an environment variable:++```html+{% if config.ENV == 'production' or not config.DEBUG %}+ <script src="https://swetrix.org/swetrix.js" defer></script>+{% endif %}+```++And for the body initialisation:++```html+{% if config.ENV == 'production' or not config.DEBUG %}+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+{% endif %}+```++:::tip+During development, Swetrix ignores `localhost` traffic by default. If you want to verify tracking locally without changing your environment, you can temporarily set `devMode: true`:++```js+swetrix.init('YOUR_PROJECT_ID', { devMode: true })+```++Remember to remove this before deploying.+:::++## Store your Project ID in config (optional)++Rather than hardcoding the Project ID in your template, you can manage it through Flask's configuration system. This keeps your templates clean and makes it easy to use different IDs per environment.++**1. Set an environment variable or add it to your config:**++```bash+export SWETRIX_PROJECT_ID=YOUR_PROJECT_ID+```++**2. Load it in your Flask app:**++```python+import os++app = Flask(__name__)+app.config['SWETRIX_PROJECT_ID'] = os.environ.get('SWETRIX_PROJECT_ID', '')+```++**3. Reference it in your template:**++```html+{% if config.SWETRIX_PROJECT_ID %}+ <script src="https://swetrix.org/swetrix.js" defer></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('{{ config.SWETRIX_PROJECT_ID }}')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid={{ config.SWETRIX_PROJECT_ID }}"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+{% endif %}+```++If you use a `.env` file with [python-dotenv](https://pypi.org/project/python-dotenv/), add the variable there:++```+SWETRIX_PROJECT_ID=YOUR_PROJECT_ID+```++And load it in your app:++```python+from dotenv import load_dotenv++load_dotenv()+```++## Check your installation++Deploy your application (or temporarily enable `devMode`) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring by adding `trackErrors()` to the initialisation snippet. This captures unhandled JavaScript errors and reports them to Swetrix.++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ swetrix.trackErrors()+ })+</script>+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β form submissions, button clicks, feature usage, and more. Since the Swetrix script is loaded globally, you can call `swetrix.track()` from any inline script or JavaScript file.++### Example: tracking form submissions++Track when users submit a registration form:++```html+<form id="register-form" method="POST" action="/register">+ <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">+ <input type="email" name="email" placeholder="[email protected]">+ <button type="submit">Register</button>+</form>++<script>+ document.getElementById('register-form')?.addEventListener('submit', function () {+ if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'REGISTER_FORM_SUBMITTED',+ meta: {+ page: window.location.pathname,+ },+ })+ }+ })+</script>+```++### Example: tracking outbound links++Track clicks on external links across your site. Add this to your base template:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ document.querySelectorAll('a[href^="http"]').forEach(function (link) {+ if (link.hostname !== window.location.hostname) {+ link.addEventListener('click', function () {+ if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'OUTBOUND_CLICK',+ meta: { url: link.href },+ })+ }+ })+ }+ })+ })+</script>+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `REGISTER_FORM_SUBMITTED`, `OUTBOUND_CLICK`).++## Using Swetrix with Flask blueprints++If your application is structured with [blueprints](https://flask.palletsprojects.com/en/stable/blueprints/), the Swetrix script in your base template will work across all blueprints automatically β as long as each blueprint's templates extend the same `base.html`.++If a blueprint uses its own base template, add the Swetrix snippet there as well, or create a shared partial:++```html+{# templates/partials/swetrix.html #}++{% if config.SWETRIX_PROJECT_ID %}+ <script src="https://swetrix.org/swetrix.js" defer></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('{{ config.SWETRIX_PROJECT_ID }}')+ swetrix.trackViews()+ swetrix.trackErrors()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid={{ config.SWETRIX_PROJECT_ID }}"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+{% endif %}+```++Then include it in any base template:++```html+{% include "partials/swetrix.html" %}+```++## Using Swetrix with Flask and a JavaScript frontend++If you use Flask as an API backend with a JavaScript frontend (e.g. React, Vue, or HTMX), you have two options:++1. **CDN script** β Add the Swetrix script to your frontend's HTML as shown above. This works well with HTMX or any server-rendered approach.+2. **npm package** β Install the Swetrix npm package in your frontend project for full programmatic control:++```bash+npm install swetrix+```++```javascript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+```++See the relevant frontend framework integration guide ([React](/react-integration), [Vue](/vue-integration), etc.) for framework-specific details.++## Further reading++- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.+- [Flask documentation](https://flask.palletsprojects.com/) β official Flask docs.diff --git a/docs/docs/integrations/gatsby.md b/docs/docs/integrations/gatsby.mdnew file mode 100644index 000000000..92561cb9f--- /dev/null+++ b/docs/docs/integrations/gatsby.md@@ -0,0 +1,191 @@+---+title: Gatsby+slug: /gatsby-integration+---++Integrate Swetrix with your [Gatsby](https://www.gatsbyjs.com/) site to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++## Installation++Install the Swetrix npm package:++```bash+npm install swetrix+```++### Set up tracking in `gatsby-browser.js`++Gatsby provides a [`gatsby-browser.js`](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-browser/) (or `gatsby-browser.tsx`) file at the root of your project where you can hook into client-side lifecycle events. Use the `onClientEntry` API to initialise Swetrix and `onRouteUpdate` to track page views on every navigation.++Create or update `gatsby-browser.js` in your project root:++```js+import * as Swetrix from 'swetrix'++export const onClientEntry = () => {+ Swetrix.init('YOUR_PROJECT_ID')+}++export const onRouteUpdate = () => {+ Swetrix.trackViews()+}+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### Noscript fallback (optional)++To track visitors who have JavaScript disabled, add a noscript image pixel using Gatsby's [`gatsby-ssr.js`](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-ssr/) (or `gatsby-ssr.tsx`) file.++Create or update `gatsby-ssr.js` in your project root:++```jsx+import React from 'react'++export const onRenderBody = ({ setPostBodyComponents }) => {+ setPostBodyComponents([+ <noscript key="swetrix-noscript">+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerPolicy="no-referrer-when-downgrade"+ />+ </noscript>,+ ])+}+```++## Disable tracking in development++By default, Swetrix ignores `localhost` traffic. If you want to be explicit about it, you can conditionally disable tracking based on your environment:++```js+Swetrix.init('YOUR_PROJECT_ID', {+ disabled: process.env.NODE_ENV === 'development',+})+```++:::tip+If you want to verify tracking locally during development, set `devMode: true` instead:++```js+Swetrix.init('YOUR_PROJECT_ID', {+ devMode: true,+})+```++Remember to remove this before deploying to production.+:::++## Check your installation++Build and deploy your site with `gatsby build && gatsby serve` (or deploy to your hosting provider). Visit a few pages β within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring by adding `trackErrors()` to your `gatsby-browser.js`. This captures unhandled JavaScript errors and reports them to Swetrix.++```js+import * as Swetrix from 'swetrix'++export const onClientEntry = () => {+ Swetrix.init('YOUR_PROJECT_ID')+ Swetrix.trackErrors()+}++export const onRouteUpdate = () => {+ Swetrix.trackViews()+}+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β button clicks, form submissions, sign-ups, purchases, and more. Import `swetrix` in any component and call `track()`.++### Example: tracking button clicks++```jsx+import * as Swetrix from 'swetrix'++export default function PricingCTA() {+ const handleClick = () => {+ Swetrix.track({+ ev: 'PRICING_CTA_CLICK',+ meta: {+ plan: 'pro',+ location: 'hero',+ },+ })+ }++ return (+ <button onClick={handleClick}>+ Upgrade to Pro+ </button>+ )+}+```++### Example: tracking form submissions++```jsx+import * as Swetrix from 'swetrix'++export default function NewsletterForm() {+ const handleSubmit = (e) => {+ e.preventDefault()++ Swetrix.track({+ ev: 'NEWSLETTER_SIGNUP',+ meta: {+ source: 'footer',+ },+ })++ // ...submit logic+ }++ return (+ <form onSubmit={handleSubmit}>+ <input type="email" placeholder="[email protected]" required />+ <button type="submit">Subscribe</button>+ </form>+ )+}+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `PRICING_CTA_CLICK`, `NEWSLETTER_SIGNUP`).++## Using environment variables for your Project ID++Rather than hardcoding your Project ID, you can use Gatsby's environment variables. Prefix the variable with `GATSBY_` so it's available in client-side code.++**1. Add to your `.env.production` file:**++```+GATSBY_SWETRIX_PID=YOUR_PROJECT_ID+```++**2. Reference it in `gatsby-browser.js`:**++```js+Swetrix.init(process.env.GATSBY_SWETRIX_PID)+```++## Further reading++- [React integration](/react-integration) β generic React setup guide for Vite and CRA.+- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.diff --git a/docs/docs/integrations/jekyll.md b/docs/docs/integrations/jekyll.mdnew file mode 100644index 000000000..26bfa5557--- /dev/null+++ b/docs/docs/integrations/jekyll.md@@ -0,0 +1,163 @@+---+title: Jekyll+slug: /jekyll-integration+---++After you sign up on Swetrix and create a new project, the only thing left is to add it to your website.++## Installation++The recommended approach is to create a Jekyll include file for the Swetrix tracking script and add it to your site's default layout.++### 1. Create an include file++In your Jekyll project, create the file `_includes/swetrix-analytics.html` with the following content:++```html+{% if jekyll.environment == "production" %}+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+{% endif %}+```++The `{% if jekyll.environment == "production" %}` condition ensures the tracking script is only included in production builds. This prevents inflating your analytics with local page views during development.++:::caution+It's very important not to forget to replace `YOUR_PROJECT_ID` with your actual Project ID you can find in the Dashboard, otherwise tracking won't work!+:::++### 2. Include it in your layout++Open your default layout file β typically `_layouts/default.html`. If you're using a gem-based theme, you may need to copy the layout into your project's `_layouts/` directory first to override it.++Add the include just before the closing `</body>` tag:++```html+ {% include swetrix-analytics.html %}+ </body>+</html>+```++### 3. Set the environment for production++Jekyll doesn't set the environment to `production` by default when building locally. To ensure tracking is active on your live site, build with:++```bash+JEKYLL_ENV=production jekyll build+```++:::tip+If you deploy via **GitHub Pages**, the environment is automatically set to `production` β no extra configuration needed.+:::++## Using Jekyll config variables (optional)++To keep your Project ID out of the template and make it easy to manage, you can store it in your `_config.yml`.++**1. Add to `_config.yml`:**++```yaml+swetrix:+ project_id: "YOUR_PROJECT_ID"+```++**2. Update `_includes/swetrix-analytics.html`:**++```html+{% if jekyll.environment == "production" and site.swetrix.project_id %}+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('{{ site.swetrix.project_id }}')+ swetrix.trackViews()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid={{ site.swetrix.project_id }}"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+{% endif %}+```++## Error tracking++To enable automatic client-side error monitoring, add `trackErrors()` after `init()` in your include file:++```html+{% if jekyll.environment == "production" %}+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ swetrix.trackErrors()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+{% endif %}+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++You can track custom events (button clicks, form submissions, etc.) anywhere on your site by calling `swetrix.track()`:++```html+<button onclick="swetrix.track({ ev: 'SIGNUP_CLICK' })">+ Sign up+</button>+```++For events with metadata:++```javascript+swetrix.track({+ ev: 'NEWSLETTER_SIGNUP',+ meta: {+ source: 'footer',+ },+})+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++## Check your installation++After installing the Swetrix tracking script, build your site with `JEKYLL_ENV=production jekyll build` and deploy it.++Visit your live website and navigate through a few pages. Within a minute you should be able to see new pageviews being added to your project's dashboard.++## Further reading++- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.diff --git a/docs/docs/integrations/ruby-on-rails.md b/docs/docs/integrations/ruby-on-rails.mdnew file mode 100644index 000000000..887b52c67--- /dev/null+++ b/docs/docs/integrations/ruby-on-rails.md@@ -0,0 +1,286 @@+---+title: Ruby on Rails+slug: /ruby-on-rails-integration+---++Integrate Swetrix with your [Ruby on Rails](https://rubyonrails.org/) application to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++This guide covers both traditional multi-page Rails apps and modern setups using **Turbo** (the default in Rails 7+).++## Installation++The recommended approach is to add the Swetrix tracking script to your application layout so it loads on every page.++### 1. Add the tracking script to your layout++Open `app/views/layouts/application.html.erb` and add the Swetrix script inside the `<head>` tag, and the initialisation snippet before the closing `</body>` tag:++```html+<!DOCTYPE html>+<html>+<head>+ <title><%= content_for(:title) || "My App" %></title>+ <meta name="viewport" content="width=device-width, initial-scale=1">+ <%= csrf_meta_tags %>+ <%= csp_meta_tag %>+ <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>+ <%= javascript_importmap_tags %>++ <!-- Swetrix Analytics -->+ <script src="https://swetrix.org/swetrix.js" defer></script>+</head>+<body>+ <%= yield %>++ <!-- Swetrix Analytics -->+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+</body>+</html>+```++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### 2. Disable tracking in development (recommended)++To avoid polluting your analytics with local page views, wrap the snippet in an environment check so it only loads in production:++```erb+<% if Rails.env.production? %>+ <script src="https://swetrix.org/swetrix.js" defer></script>+<% end %>+```++And for the body initialisation:++```erb+<% if Rails.env.production? %>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+<% end %>+```++:::tip+During development, Swetrix ignores `localhost` traffic by default. If you want to verify tracking locally without changing your environment, you can temporarily set `devMode: true`:++```js+swetrix.init('YOUR_PROJECT_ID', { devMode: true })+```++Remember to remove this before deploying.+:::++## Turbo support (Rails 7+)++Rails 7 and later ship with [Turbo](https://turbo.hotwired.dev/) by default. Turbo intercepts link clicks and form submissions, performing navigations without full page reloads. This means the `DOMContentLoaded` event only fires once, on the initial page load.++Swetrix's `trackViews()` listens for History API changes, so most Turbo Drive navigations are tracked automatically. If you notice any gaps, you can explicitly listen for Turbo's navigation event:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })++ document.addEventListener('turbo:load', function () {+ swetrix.trackViews()+ })+</script>+```++:::tip+If your app does **not** use Turbo (e.g. you removed it or are on Rails 6 or earlier), you don't need the `turbo:load` listener β standard full-page navigation handles page view tracking automatically.+:::++## Store your Project ID in credentials (optional)++Rather than hardcoding the Project ID in your layout, you can manage it through Rails credentials. This keeps configuration in one place and out of your templates.++**1. Add to your credentials:**++```bash+bin/rails credentials:edit+```++Add the following:++```yaml+swetrix:+ project_id: YOUR_PROJECT_ID+```++**2. Reference it in your layout:**++```erb+<% if Rails.env.production? %>+ <script src="https://swetrix.org/swetrix.js" defer></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('<%= Rails.application.credentials.dig(:swetrix, :project_id) %>')+ swetrix.trackViews()+ })+ </script>++ <noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=<%= Rails.application.credentials.dig(:swetrix, :project_id) %>"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+ </noscript>+<% end %>+```++Alternatively, you can use an environment variable. Add `SWETRIX_PROJECT_ID` to your environment and reference it with `ENV['SWETRIX_PROJECT_ID']`.++## Check your installation++Deploy your application (or temporarily enable `devMode`) and visit a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring by adding `trackErrors()` to the initialisation snippet. This captures unhandled JavaScript errors and reports them to Swetrix.++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ swetrix.trackErrors()+ })+</script>+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β form submissions, button clicks, feature usage, and more. Since the Swetrix script is loaded globally, you can call `swetrix.track()` from any inline script or JavaScript file.++### Example: tracking form submissions++Track when users submit a sign-up form:++```html+<%= form_with url: "/signup", id: "signup-form" do |f| %>+ <%= f.email_field :email, placeholder: "[email protected]" %>+ <%= f.submit "Sign up" %>+<% end %>++<script>+ document.getElementById('signup-form')?.addEventListener('submit', function () {+ if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'SIGNUP_FORM_SUBMITTED',+ meta: {+ page: window.location.pathname,+ },+ })+ }+ })+</script>+```++### Example: tracking outbound links++Track clicks on external links across your site. Add this to your layout file:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ document.querySelectorAll('a[href^="http"]').forEach(function (link) {+ if (link.hostname !== window.location.hostname) {+ link.addEventListener('click', function () {+ if (typeof swetrix !== 'undefined') {+ swetrix.track({+ ev: 'OUTBOUND_CLICK',+ meta: { url: link.href },+ })+ }+ })+ }+ })+ })+</script>+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `SIGNUP_FORM_SUBMITTED`, `OUTBOUND_CLICK`).++## Using Swetrix with the Asset Pipeline or import maps++The examples above use the CDN script, which works with any Rails asset setup. If you prefer to manage Swetrix as a JavaScript dependency:++### With import maps (Rails 7+ default)++Pin the Swetrix package:++```bash+bin/importmap pin swetrix+```++Then use it in your JavaScript entry point (e.g. `app/javascript/application.js`):++```javascript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+```++### With jsbundling (esbuild, webpack, rollup)++Install the package:++```bash+yarn add swetrix+```++Then import it in your JavaScript entry point:++```javascript+import * as Swetrix from 'swetrix'++Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+```++## Further reading++- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.+- [Ruby on Rails documentation](https://guides.rubyonrails.org/) β official Rails guides.diff --git a/docs/docs/integrations/vitepress.md b/docs/docs/integrations/vitepress.mdnew file mode 100644index 000000000..f8b1c5d5e--- /dev/null+++ b/docs/docs/integrations/vitepress.md@@ -0,0 +1,278 @@+---+title: VitePress+slug: /vitepress-integration+---++Integrate Swetrix with your [VitePress](https://vitepress.dev/) documentation site to track page views, monitor errors, and capture custom events β all while staying privacy-friendly and GDPR-compliant.++## Installation++There are two ways to add Swetrix to a VitePress site: via the **config file** (quickest) or via the **npm package** (more flexible, enables custom events from Vue components).++### Option A: Script tag via config (quickest)++Add the Swetrix tracking script to your `.vitepress/config.ts` (or `.js` / `.mts`):++```ts+import { defineConfig } from 'vitepress'++export default defineConfig({+ // ...your existing config+ head: [+ [+ 'script',+ { src: 'https://swetrix.org/swetrix.js', defer: '' },+ ],+ [+ 'script',+ {},+ `document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+})`,+ ],+ ],+})+```++The empty string for `defer` is intentional β VitePress renders it as a boolean attribute (`<script defer>`).++:::caution+Replace `YOUR_PROJECT_ID` with your actual Project ID from the [Swetrix dashboard](https://swetrix.com/projects), otherwise tracking won't work.+:::++### Option B: npm package (recommended for custom events)++If you want to track custom events from Vue components or need finer control, install the npm package:++```bash+npm install swetrix+```++Then extend your VitePress theme to initialise Swetrix. Create or edit `.vitepress/theme/index.ts`:++```ts+import DefaultTheme from 'vitepress/theme'+import type { Theme } from 'vitepress'+import { watch } from 'vue'+import * as Swetrix from 'swetrix'++export default {+ extends: DefaultTheme,+ enhanceApp({ router }) {+ if (typeof window === 'undefined') return++ Swetrix.init('YOUR_PROJECT_ID')+ Swetrix.trackViews()++ watch(() => router.route.path, () => {+ Swetrix.trackViews()+ })+ },+} satisfies Theme+```++This initialises Swetrix once and re-tracks page views whenever VitePress navigates to a new route.++### Noscript fallback (optional)++To track visitors who have JavaScript disabled, add a noscript image pixel via the `head` config:++```ts+export default defineConfig({+ head: [+ // ...your script tags+ [+ 'noscript',+ {},+ `<img src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID" alt="" referrerpolicy="no-referrer-when-downgrade" />`,+ ],+ ],+})+```++## SPA navigation++VitePress uses client-side routing β clicking a link doesn't trigger a full page reload. The Swetrix tracking script detects these navigations automatically via the History API, so **no extra configuration is needed** if you're using Option A (script tag).++If you're using Option B (npm package), the `watch` on `router.route.path` in the theme setup handles this for you.++## Disable tracking in development++By default, Swetrix ignores `localhost` traffic. If you want to be explicit about it, you can conditionally exclude the script in development.++**Option A β conditional `head` config:**++```ts+import { defineConfig } from 'vitepress'++const isProd = process.env.NODE_ENV === 'production'++export default defineConfig({+ head: isProd+ ? [+ [+ 'script',+ { src: 'https://swetrix.org/swetrix.js', defer: '' },+ ],+ [+ 'script',+ {},+ `document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+})`,+ ],+ ]+ : [],+})+```++**Option B β `disabled` flag with the npm package:**++```ts+Swetrix.init('YOUR_PROJECT_ID', {+ disabled: import.meta.env.DEV,+})+```++:::tip+If you want to verify tracking locally during development, set `devMode: true` instead:++```ts+Swetrix.init('YOUR_PROJECT_ID', {+ devMode: true,+})+```++Remember to remove this before deploying to production.+:::++## Check your installation++Build your site with `vitepress build` and deploy it. Visit a few pages on your live site β within a minute you should see new pageviews appearing in your Swetrix dashboard.++## Error tracking++Enable automatic client-side error monitoring to capture unhandled JavaScript errors.++**Option A β update the inline script in your config:**++```js+document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ swetrix.trackErrors()+})+```++**Option B β update your theme setup:**++```ts+Swetrix.init('YOUR_PROJECT_ID')+Swetrix.trackViews()+Swetrix.trackErrors()+```++Errors will appear in the **Errors** tab of your project dashboard. See the [tracking script reference](/swetrix-js-reference#trackerrors) for options like `sampleRate` and `callback`.++## Tracking custom events++Custom events let you track specific user interactions β button clicks, feedback responses, outbound links, and more. This requires **Option B** (npm package).++### Example: docs feedback widget++Track whether visitors find a page helpful:++```vue+<script setup lang="ts">+import { ref } from 'vue'+import { useRoute } from 'vitepress'+import * as Swetrix from 'swetrix'++const route = useRoute()+const submitted = ref(false)++function sendFeedback(answer: string) {+ Swetrix.track({+ ev: 'DOCS_FEEDBACK',+ meta: {+ answer,+ path: route.path,+ },+ })++ submitted.value = true+}+</script>++<template>+ <div v-if="!submitted">+ <p>Was this page helpful?</p>+ <button @click="sendFeedback('Yes')">Yes</button>+ <button @click="sendFeedback('No')">No</button>+ </div>+ <p v-else>Thank you for your feedback!</p>+</template>+```++Place this component in `.vitepress/theme/components/DocsFeedback.vue` and use it in your Markdown pages or theme layout.++### Example: tracking outbound links++Create a reusable component for external links. Save as `.vitepress/theme/components/TrackedLink.vue`:++```vue+<script setup lang="ts">+import * as Swetrix from 'swetrix'++const props = withDefaults(+ defineProps<{+ href: string+ eventName?: string+ }>(),+ {+ eventName: 'OUTBOUND_CLICK',+ },+)++function handleClick() {+ Swetrix.track({+ ev: props.eventName,+ meta: { url: props.href },+ })+}+</script>++<template>+ <a :href="href" target="_blank" rel="noopener noreferrer" @click="handleClick">+ <slot />+ </a>+</template>+```++Usage in Markdown:++```md+<script setup>+import TrackedLink from '../.vitepress/theme/components/TrackedLink.vue'+</script>++Check out the <TrackedLink href="https://github.com/example/repo">source code</TrackedLink>.+```++### Event naming rules++Event names must:++- Contain only English letters (a-Z), numbers (0-9), underscores (`_`), and dots (`.`)+- Be fewer than 64 characters+- Start with an English letter++We recommend `UPPER_SNAKE_CASE` for consistency (e.g. `DOCS_FEEDBACK`, `OUTBOUND_CLICK`).++## Further reading++- [Vue integration](/vue-integration) β general Vue setup guide.+- [Tracking script reference](/swetrix-js-reference) β full API documentation for `init()`, `track()`, `trackViews()`, `trackErrors()`, and more.+- [Swetrix npm package](https://www.npmjs.com/package/swetrix) β package details and changelog.diff --git a/docs/docs/integrations/weebly.md b/docs/docs/integrations/weebly.mdnew file mode 100644index 000000000..c76a2d0db--- /dev/null+++ b/docs/docs/integrations/weebly.md@@ -0,0 +1,89 @@+---+title: Weebly+slug: /weebly-integration+---++Integrate Swetrix with your Weebly website using the built-in Header/Footer Code feature.++## Prerequisites++Adding custom code to Weebly requires a **paid plan** (Personal, Professional, Performance, or any Business plan). The free plan does not support custom header/footer code injection.++## Installation++### 1. Open your site's code settings++1. Log in to your [Weebly](https://www.weebly.com) account and open the site editor.+2. Click **Settings** in the top menu.+3. Select the **SEO** tab.++### 2. Add the Swetrix script++In the **Header Code** field, paste the following:++```html+<script src="https://swetrix.org/swetrix.js" defer></script>+```++### 3. Add the initialisation snippet++In the **Footer Code** field, paste the following:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ })+</script>++<noscript>+ <img+ src="https://api.swetrix.com/log/noscript?pid=YOUR_PROJECT_ID"+ alt=""+ referrerpolicy="no-referrer-when-downgrade"+ />+</noscript>+```++### 4. Save and publish++Click **Save**, then **Publish** your site to apply the changes.++:::caution+Don't forget to replace `YOUR_PROJECT_ID` with your actual Project ID from the Swetrix dashboard, otherwise tracking won't work.+:::++## Check your installation++After publishing, open your Weebly site in a new tab (or an incognito window) and browse a few pages. Within a minute you should see new pageviews appearing in your Swetrix dashboard.++:::tip+The tracking script only runs on your published site. You won't see analytics data while previewing inside the Weebly editor.+:::++## Optional: track custom events++You can use `swetrix.track()` to capture custom interactions β button clicks, form submissions, etc. Add the following in the same **Footer Code** field, after the main tracking snippet:++```html+<script>+ document.addEventListener('DOMContentLoaded', function () {+ var form = document.querySelector('form')+ if (!form || typeof swetrix === 'undefined') return++ form.addEventListener('submit', function () {+ swetrix.track({ ev: 'form_submission' })+ })+ })+</script>+```++Refer to the [tracking script reference](/swetrix-js-reference) for the full list of options and functions available.++## Troubleshooting++- **No Header/Footer Code option.** This feature is only available on paid Weebly plans. Upgrade from the free plan to access it.+- **No data in dashboard.** Make sure you published the site after adding the code. Changes are not live until you publish.+- **Check the source.** Open your published site, right-click and select "View Page Source", then search for `swetrix` to confirm the script is present.+- **Console errors.** Open your browser's developer tools (F12) and check the Console tab for JavaScript errors. Look for network requests to `api.swetrix.com` to verify data is being sent.diff --git a/docs/sidebars.js b/docs/sidebars.jsindex 754ecd800..51987d0b9 100644--- a/docs/sidebars.js+++ b/docs/sidebars.js@@ -10,37 +10,54 @@ module.exports = {type: 'category',label: 'Integrations',items: [- 'integrations/django',+ 'integrations/angular',+ 'integrations/astro',+ 'integrations/bigcommerce',+ 'integrations/bubble','integrations/docusaurus','integrations/drupal',+ 'integrations/eleventy','integrations/framer','integrations/ghost','integrations/gitbook','integrations/google-search-console','integrations/google-tag-manager','integrations/hugo',+ 'integrations/jekyll','integrations/joomla','integrations/laravel','integrations/prestashop',+ {+ type: 'category',+ label: 'Python',+ items: ['integrations/django', 'integrations/flask'],+ },{type: 'category',label: 'React (Vite / CRA)',items: [- 'integrations/react',+ 'integrations/gatsby','integrations/nextjs',+ 'integrations/react','integrations/remix',],},+ 'integrations/ruby-on-rails','integrations/shopify','integrations/squarespace','integrations/sveltekit',+ 'integrations/thrivecart',{type: 'category',label: 'Vue',- items: ['integrations/vue', 'integrations/nuxt'],+ items: [+ 'integrations/nuxt',+ 'integrations/vitepress',+ 'integrations/vue',+ ],},- 'integrations/thrivecart','integrations/webflow',+ 'integrations/weebly','integrations/wix','integrations/woocommerce','integrations/wordpress',