π 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
Update README
Blue Mouse80a0225cedb1
diff --git a/packages/tracker-js/README.md b/packages/tracker-js/README.mdindex 366151b0a..2e8bfe14d 100644--- a/packages/tracker-js/README.md+++ b/packages/tracker-js/README.md@@ -1,26 +1,216 @@<picture><source media="(prefers-color-scheme: dark)" srcset="https://swetrix.com/assets/logo_white.png">- <img alt="" src="https://swetrix.com/assets/logo_blue.png" height="80">+ <img alt="Swetrix" src="https://swetrix.com/assets/logo_blue.png" height="80"></picture><br /><br />+[](https://www.npmjs.com/package/swetrix)+[](https://bundlephobia.com/package/swetrix)[](https://data.jsdelivr.com/v1/package/gh/Swetrix/swetrix-js/stats)-[](https://bundlephobia.com/api/size?package=swetrix)[](https://github.com/swetrix/swetrix-js/issues)# Swetrix Tracking Script-This repository contains the analytics script which is used at https://swetrix.com \-You can find the detailed documentation and use cases at our [docs page](https://docs.swetrix.com/).+Privacy-first, lightweight analytics tracking library for [Swetrix](https://swetrix.com). Tracks page views, custom events, errors, feature flags, and A/B experiments β all without cookies or invading user privacy.-Feel free to contribute to the source code by opening a pull requests. \-For any questions, you can open an issue ticket, refer to our [FAQs](https://swetrix.com/#faq) page or reach us at [email protected]+## Installation-The latest live versions of the script are located at [jsDelivr](https://swetrix.org/swetrix.js) and [NPM](https://www.npmjs.com/package/swetrix).+### npm / yarn / pnpm-# Selfhosted API-If you are selfhosting the [Swetrix-API](https://github.com/Swetrix/swetrix-api), be sure to point the `apiUrl` parameter to: `https://yourapiinstance.com/log`+```bash+npm install swetrix+```-# Donate-You can support the project by donating us at https://ko-fi.com/andriir \-We can only run our services by once again asking for your financial support!+### CDN++```html+<script src="https://swetrix.org/swetrix.js" defer></script>+```++## Quick Start++### ES Modules++```javascript+import { init, trackViews, trackErrors } from 'swetrix'++init('YOUR_PROJECT_ID')+trackViews()+trackErrors()+```++### CDN / Script Tag++```html+<script src="https://swetrix.org/swetrix.js" defer></script>+<script>+ document.addEventListener('DOMContentLoaded', () => {+ swetrix.init('YOUR_PROJECT_ID')+ swetrix.trackViews()+ swetrix.trackErrors()+ })+</script>+```++## API++### `init(projectId, options?)`++Initialise the library. Must be called before any other method.++```javascript+init('YOUR_PROJECT_ID', {+ apiURL: 'https://api.swetrix.com/log',+ devMode: false,+ disabled: false,+ respectDNT: false,+ profileId: 'user-123',+})+```++| Option | Description | Default |+|---|---|---|+| `apiURL` | API endpoint. Change this if you're self-hosting. | `'https://api.swetrix.com/log'` |+| `devMode` | When `true`, localhost events are sent to the server. | `false` |+| `disabled` | When `true`, no data is sent. Useful for dev environments. | `false` |+| `respectDNT` | When `true`, disables tracking for users with Do Not Track enabled. | `false` |+| `profileId` | Profile ID for long-term user tracking (MAU/DAU). | `undefined` |++### `trackViews(options?)`++Automatically tracks page views, including navigation changes in SPAs. Returns a `Promise<{ stop() }>`.++```javascript+const { stop } = await trackViews({+ hash: false,+ search: false,+ unique: false,+ heartbeatOnBackground: false,+ callback: undefined,+})++// Stop tracking when needed+stop()+```++| Option | Description | Default |+|---|---|---|+| `hash` | Track hash-based routing (e.g. `/#/path`). | `false` |+| `search` | Track search/query-based routing (e.g. `/path?query`). | `false` |+| `unique` | Only count unique page views per session. | `false` |+| `heartbeatOnBackground` | Send heartbeat when the tab is not active. | `false` |+| `callback` | A function to edit or prevent pageview payloads. Return `false` to block, `true` to send as-is, or return a modified payload object. | `undefined` |++### `track(event)`++Track custom events (e.g. button clicks, sign-ups).++```javascript+track({+ ev: 'signup',+ unique: true,+ meta: { plan: 'pro', source: 'landing' },+})+```++| Option | Description | Default |+|---|---|---|+| `ev` | Event name (max 256 chars). | **required** |+| `unique` | Only count once per session. | `false` |+| `meta` | Key-value metadata (max 20 keys, 1000 chars total). | `{}` |++### `trackErrors(options?)`++Automatically captures client-side errors. Returns `{ stop() }`.++```javascript+const { stop } = trackErrors({+ sampleRate: 1,+ callback: undefined,+})+```++| Option | Description | Default |+|---|---|---|+| `sampleRate` | Fraction of errors to send (`0` to `1`). | `1` |+| `callback` | Edit or prevent error payloads. Return `false` to block. | `undefined` |++### `trackError(payload)`++Manually report an error.++```javascript+trackError({+ name: 'PaymentError',+ message: 'Card declined',+ meta: { gateway: 'stripe' },+})+```++### `pageview(options)`++Manually track a single page view (useful for custom routing).++```javascript+pageview({+ payload: { pg: '/checkout', lc: 'en-US' },+ unique: true,+})+```++### Feature Flags++```javascript+// Get all flags+const flags = await getFeatureFlags({ profileId: 'user-123' })++// Get a single flag+const enabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })++// Clear cache+clearFeatureFlagsCache()+```++### A/B Experiments++```javascript+// Get all experiments+const experiments = await getExperiments({ profileId: 'user-123' })++// Get a specific experiment variant+const variant = await getExperiment('checkout-redesign', { profileId: 'user-123' })++// Clear cache+clearExperimentsCache()+```++### Session & Profile IDs++```javascript+const profileId = await getProfileId()+const sessionId = await getSessionId()+```++These are useful for revenue attribution with payment providers like Paddle.++## Self-Hosting++If you're running a self-hosted [Swetrix API](https://github.com/Swetrix/swetrix-api) instance, point the `apiURL` to your server:++```javascript+init('YOUR_PROJECT_ID', {+ apiURL: 'https://your-api.example.com/log',+})+```++## Documentation++Full reference and guides are available at [docs.swetrix.com](https://docs.swetrix.com).++## Contributing++Contributions are welcome β feel free to [open an issue](https://github.com/swetrix/swetrix-js/issues) or submit a pull request.++## License++MIT