clickchutney-analytics
Version:
Privacy-first web analytics - bite-sized insights for your website 🌶️
193 lines (145 loc) • 3.73 kB
Markdown
# clickchutney-analytics 🌶️
Privacy-first web analytics - bite-sized insights for your website
## Features
- 🍪 **Cookie-free tracking** - GDPR compliant by design
- 🏃♂️ **Lightweight** - Under 2KB gzipped
- ⚡ **Fast** - Uses sendBeacon API for optimal performance
- 🔒 **Privacy-first** - No personal data collection
- 📱 **Universal** - Works with any framework or vanilla JS
- 🚀 **Real-time** - Instant event tracking to Cloudflare Workers
## Quick Start
### Next.js (App Router)
```tsx
// app/layout.tsx
import { Analytics } from 'clickchutney-analytics/react'
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Analytics />
</body>
</html>
)
}
```
### Next.js (Pages Router)
```tsx
// pages/_app.tsx
import { Analytics } from 'clickchutney-analytics/react'
export default function App({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<Analytics />
</>
)
}
```
### React
```tsx
import { Analytics } from 'clickchutney-analytics/react'
function App() {
return (
<div>
<h1>My App</h1>
<Analytics />
</div>
)
}
```
### Vanilla JavaScript
```html
<script type="module">
import { inject, track } from 'https://unpkg.com/clickchutney-analytics'
// Initialize
inject()
// Track custom events
track('button_click', { button: 'cta' })
</script>
```
Or using the global:
```html
<script src="https://unpkg.com/clickchutney-analytics/dist/index.js"></script>
<script>
// Initialize
ccAnalytics.inject()
// Track custom events
ccAnalytics.track('signup', { plan: 'premium' })
</script>
```
## API
### `inject(options?)`
Initialize the analytics tracking.
```typescript
import { inject } from 'clickchutney-analytics'
inject({
endpoint: 'https://your-worker.domain.com/api/collect', // optional
debug: true, // optional, default: false
beforeSend: (event) => {
// Optional: filter or modify events before sending
if (event.url.includes('localhost')) return null
return event
}
})
```
### `track(eventName, properties?)`
Track a custom event.
```typescript
import { track } from 'clickchutney-analytics'
track('purchase', {
value: 99.99,
currency: 'USD',
items: 3
})
```
### `page(path?)`
Manually track a page view (automatically done on route changes).
```typescript
import { page } from 'clickchutney-analytics'
page('/custom-page')
```
### `<Analytics />` Component Props
```typescript
interface AnalyticsProps {
endpoint?: string; // Custom endpoint URL
debug?: boolean; // Enable debug logging
enabled?: boolean; // Toggle analytics on/off
beforeSend?: (event: any) => any | null;
}
```
## Configuration
### Custom Endpoint
By default, analytics are sent to `https://clickchutney-analytics.contact-sushilpandey.workers.dev/api/collect`. You can specify a custom endpoint:
```typescript
inject({
endpoint: 'https://your-domain.com/api/collect'
})
```
### Development Mode
Analytics are automatically disabled in development mode unless `debug: true` is set.
## Event Data
Each event includes:
```typescript
{
type: 'pageview' | 'custom_event_name',
timestamp: number,
url: string,
referrer?: string,
title: string,
sessionId: string,
userId: string,
userAgent: string,
screen: { width: number, height: number },
viewport: { width: number, height: number },
properties?: { [key: string]: any }
}
```
## Privacy
- No cookies are used
- No personal information is collected
- Session/User IDs are randomly generated
- GDPR compliant by design
- Data is processed on Cloudflare's edge network
## License
MIT