@click-chutney/clickanalytics
Version:
Simplified analytics library inspired by Vercel Analytics - privacy-first, lightweight tracking
466 lines (347 loc) • 10.1 kB
Markdown
# ClickAnalytics
A lightweight, privacy-first analytics library inspired by Vercel Analytics. Simple, powerful, and framework-agnostic.
## Features
- 🚀 **Zero Configuration** - Works out of the box with minimal setup
- 🔒 **Privacy-First** - No personal data collection, GDPR compliant
- ⚡ **Lightweight** - < 5KB gzipped, minimal performance impact
- 🎯 **Framework Agnostic** - Works with React, Next.js, Vue, Svelte, or vanilla JS
- 🛡️ **TypeScript Support** - Full type safety included
- 🔧 **Flexible** - Multiple integration methods to fit your workflow
- 📊 **Real-time** - Events sent immediately for accurate tracking
## Quick Start
### React/Next.js
```bash
npm install @click-chutney/clickanalytics
```
Add the Analytics component to your app:
```tsx
import { Analytics } from '@click-chutney/clickanalytics/react';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Analytics trackingId="your-tracking-id" />
</body>
</html>
);
}
```
Track custom events with the hook:
```tsx
import { useAnalytics } from '@click-chutney/clickanalytics/react';
function MyComponent() {
const analytics = useAnalytics();
const handleClick = () => {
analytics.event('button_click', { button: 'signup' });
};
return <button onClick={handleClick}>Sign Up</button>;
}
```
### Vanilla JavaScript
```bash
npm install @click-chutney/clickanalytics
```
```javascript
import { inject } from '@click-chutney/clickanalytics';
// Initialize
inject({ trackingId: 'your-tracking-id' });
// Track events
import { event } from '@click-chutney/clickanalytics';
event('button_click', { button: 'signup' });
```
### CDN/Script Tag
```html
<script src="https://unpkg.com/@click-chutney/clickanalytics/dist/clickanalytics.min.js"></script>
<meta name="clickanalytics-tracking-id" content="your-tracking-id">
<script>
// Automatically initialized from meta tag
// Track custom events
caPV(); // page view
caEV('button_click', { button: 'signup' }); // custom event
caID('user-123'); // identify user
</script>
```
## Installation Methods
### Method 1: React/Next.js Component
Perfect for React applications with automatic page view tracking.
```tsx
// 1. Install the package
npm install @click-chutney/clickanalytics
// 2. Add to your root layout
import { Analytics } from '@click-chutney/clickanalytics/react';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Analytics trackingId="your-tracking-id" />
</body>
</html>
);
}
// 3. Use the hook for custom events
import { useAnalytics } from '@click-chutney/clickanalytics/react';
function MyComponent() {
const analytics = useAnalytics();
return (
<button onClick={() => analytics.event('click', { button: 'cta' })}>
Click me
</button>
);
}
```
### Method 2: Inject Function (Any Framework)
Great for Vue, Svelte, Angular, or vanilla JS applications.
```javascript
import { inject, event, pageview } from '@click-chutney/clickanalytics';
// Initialize once in your app
inject({
trackingId: 'your-tracking-id',
debug: true
});
// Track events anywhere
event('user_signup', { method: 'email' });
pageview('/dashboard');
```
### Method 3: Script Tag (No Build Step)
Perfect for static sites, WordPress, or any HTML page.
```html
<!DOCTYPE html>
<html>
<head>
<meta name="clickanalytics-tracking-id" content="your-tracking-id">
<script src="https://unpkg.com/@click-chutney/clickanalytics/dist/clickanalytics.min.js"></script>
</head>
<body>
<button onclick="caEV('button_click', { button: 'signup' })">
Sign Up
</button>
</body>
</html>
```
## API Reference
### React Component
```tsx
<Analytics
trackingId="your-id" // Required: Your tracking ID
debug={true} // Optional: Enable debug logging
disableInDev={true} // Optional: Disable in development
apiUrl="/api/analytics" // Optional: Custom API endpoint
beforeSend={(event) => event} // Optional: Modify events before sending
/>
```
### React Hook
```tsx
const analytics = useAnalytics();
analytics.pageview('/custom-page', 'Custom Title');
analytics.event('custom_event', { key: 'value' });
analytics.identify('user-123');
analytics.flush(); // Force send queued events
```
### Inject Function
```javascript
import { inject, event, pageview, identify } from '@click-chutney/clickanalytics';
// Initialize
inject({
trackingId: 'your-tracking-id',
debug: false,
disableInDev: true,
apiUrl: '/api/analytics',
beforeSend: (event) => {
// Modify or filter events
return event;
}
});
// Track events
pageview(); // Auto-tracks current page
pageview('/custom-path', 'Custom Title');
event('button_click', { button: 'signup' });
identify('user-123');
```
### Script Tag Globals
When using the script tag, these functions are available globally:
```javascript
caPV(url?, title?) // Page view
caEV(eventName, properties?) // Custom event
caID(userId) // Identify user
```
## Configuration
### Environment Variables
Set your tracking ID using environment variables:
```bash
# React/Next.js
NEXT_PUBLIC_CLICKANALYTICS_ID=your-tracking-id
# Or alternative names
NEXT_PUBLIC_CLICKCHUTNEY_ID=your-tracking-id
CLICKANALYTICS_TRACKING_ID=your-tracking-id
```
### Meta Tag
Add a meta tag to auto-initialize:
```html
<meta name="clickanalytics-tracking-id" content="your-tracking-id">
```
### Advanced Configuration
```javascript
inject({
trackingId: 'your-tracking-id',
debug: true, // Enable console logging
disableInDev: true, // Disable in development
apiUrl: '/api/analytics', // Custom API endpoint
beforeSend: (event) => { // Filter/modify events
// Add custom data
event.customData = { version: '1.0' };
// Block certain events
if (event.event === 'spam') return false;
return event;
}
});
```
## Event Types
### Page Views
Automatically tracked when using React component or inject function.
```javascript
// Manual page view tracking
pageview('/dashboard', 'Dashboard');
```
### Custom Events
Track any user interaction or business event.
```javascript
event('button_click', {
button: 'signup',
location: 'header',
user_type: 'anonymous'
});
event('purchase', {
item_id: 'prod_123',
price: 29.99,
currency: 'USD'
});
```
### User Identification
Associate events with specific users.
```javascript
identify('user-123');
// All subsequent events will include this user ID
event('page_view'); // Will include userId: 'user-123'
```
## Integration Examples
### Next.js App Router
```tsx
// app/layout.tsx
import { Analytics } from '@click-chutney/clickanalytics/react';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Analytics />
</body>
</html>
);
}
// app/page.tsx
import { useAnalytics } from '@click-chutney/clickanalytics/react';
export default function HomePage() {
const analytics = useAnalytics();
return (
<button onClick={() => analytics.event('cta_click')}>
Get Started
</button>
);
}
```
### Vue.js
```javascript
// main.js
import { inject } from '@click-chutney/clickanalytics';
inject({ trackingId: 'your-tracking-id' });
// component
import { event } from '@click-chutney/clickanalytics';
export default {
methods: {
trackClick() {
event('button_click', { component: 'header' });
}
}
}
```
### Svelte
```javascript
// app.js
import { inject } from '@click-chutney/clickanalytics';
inject({ trackingId: 'your-tracking-id' });
// Component.svelte
<script>
import { event } from '@click-chutney/clickanalytics';
function handleClick() {
event('button_click', { button: 'subscribe' });
}
</script>
<button on:click={handleClick}>Subscribe</button>
```
### WordPress
```html
<!-- Add to theme header.php or use a plugin -->
<meta name="clickanalytics-tracking-id" content="your-tracking-id">
<script src="https://unpkg.com/@click-chutney/clickanalytics/dist/clickanalytics.min.js"></script>
<!-- Track events in your theme -->
<button onclick="caEV('button_click', { button: 'contact' })">
Contact Us
</button>
```
## Development
Disable analytics during development:
```javascript
// Automatically disabled in development
inject({
trackingId: 'your-tracking-id',
disableInDev: true // Default: true
});
// Or use environment detection
const isDev = process.env.NODE_ENV === 'development';
if (!isDev) {
inject({ trackingId: 'your-tracking-id' });
}
```
## Privacy & GDPR
ClickAnalytics is designed to be privacy-first:
- ✅ No personal data collection
- ✅ No cross-site tracking
- ✅ No fingerprinting
- ✅ IP addresses used only for geolocation, not stored
- ✅ GDPR compliant by design
- ✅ No third-party cookies
## Troubleshooting
### Common Issues
**1. Events not appearing**
- Check your tracking ID is correct
- Verify network requests in browser dev tools
- Enable debug mode: `inject({ debug: true })`
**2. Multiple initializations**
- Only call `inject()` once in your app
- Use `reset()` to reinitialize if needed
**3. TypeScript errors**
- Ensure you're importing from the correct path
- React components: `@click-chutney/clickanalytics/react`
- Inject functions: `@click-chutney/clickanalytics`
### Debug Mode
Enable debug logging to troubleshoot issues:
```javascript
inject({
trackingId: 'your-tracking-id',
debug: true
});
```
This will log all events and API calls to the console.
## Getting Your Tracking ID
1. Sign up at [clickchutney.com](https://clickchutney.com)
2. Create a new project
3. Copy your tracking ID from the dashboard
4. Add it to your environment variables or configuration
## License
MIT License - see LICENSE file for details.
## Support
- 📧 Email: support@clickchutney.com
- 🐛 Issues: [GitHub Issues](https://github.com/clickchutney/clickanalytics/issues)
- 📖 Docs: [clickchutney.com/docs](https://clickchutney.com/docs)