https://github.com/dagota12/omni-sdk
A highly extensible, analytics SDK for deep website usage analysis. Deploy as an NPM package
https://github.com/dagota12/omni-sdk
analytics sdk web
Last synced: 5 months ago
JSON representation
A highly extensible, analytics SDK for deep website usage analysis. Deploy as an NPM package
- Host: GitHub
- URL: https://github.com/dagota12/omni-sdk
- Owner: dagota12
- Created: 2025-12-08T22:10:01.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-21T13:52:44.000Z (6 months ago)
- Last Synced: 2025-12-21T21:45:55.678Z (6 months ago)
- Topics: analytics, sdk, web
- Language: TypeScript
- Homepage:
- Size: 8.41 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Omni Analytics SDK
A highly extensible, SOLID-principled analytics SDK for deep website usage analysis. Deploy as an NPM package or via CDN snippet.
```
███████╗██╗ ██████╗ ███╗ ██╗ █████╗ ██████╗ ███████╗
██╔════╝██║██╔════╝ ████╗ ██║██╔══██╗██╔══██╗██╔════╝
███████╗██║██║ ███╗██╔██╗ ██║███████║██║ ██║███████╗
╚════██║██║██║ ██║██║╚██╗██║██╔══██║██║ ██║╚════██║
███████║██║╚██████╔╝██║ ╚████║██║ ██║██████╔╝███████║
╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝╚═════╝ ╚══════╝
Omni Analytics SDK
```
## 🚀 Quick Start
```typescript
import { initializeSDK } from "@omni-analytics/sdk";
const { tracker } = initializeSDK({
projectId: "my-project",
endpoint: "https://api.example.com/events",
});
// That's it! The SDK automatically tracks:
// ✅ Page views
// ✅ User clicks with heatmap data
// ✅ SPA navigation
// ✅ Sessions and users
```
## 📦 What's Included
### Core SDK (`@omni-analytics/sdk`)
- ✅ Automatic page view tracking
- ✅ Automatic click tracking with coordinates & selectors
- ✅ SPA navigation support
- ✅ Session management
- ✅ Event batching & transmission
- ✅ Multiple transmitter strategies (Fetch + Beacon)
- ✅ Plugin system for extensibility
- ✅ Full TypeScript support
### React Integration (`@omni-analytics/react`)
- ✅ `TrackerProvider` context
- ✅ `useTracker` hook
- ✅ Seamless React integration
### Documentation
- 📚 [Getting Started](./docs/GETTING_STARTED.md)
- 📖 [API Reference](./docs/API_REFERENCE.md)
- 🏗️ [Architecture](./docs/ARCHITECTURE.md)
- 🔌 [Plugin Development](./docs/PLUGIN_DEVELOPMENT.md)
## 🎯 Key Features
### Automatic Tracking
Initialize once and get:
- Initial page loads
- SPA route changes (via history.pushState)
- All user clicks with X,Y coordinates
- Element selectors (CSS & XPath)
- Session tracking
- Automatic data batching
### Smart Transmission
- Batch events (configurable size & timeout)
- Fetch API with automatic retry
- Beacon API fallback for page unload
- Exponential backoff on failure
### Plugin System
Extend functionality with plugins:
```typescript
class MyPlugin implements IPlugin {
name = "my-plugin";
version = "1.0.0";
async init(context: PluginContext) {
// Track custom events
context.tracker.trackCustom("my-event", {});
}
}
```
### React Ready
```typescript
import { TrackerProvider, useTracker } from "@omni-analytics/react";
function App() {
return (
);
}
function MyComponent() {
const tracker = useTracker();
return tracker.trackCustom("clicked")}>Click;
}
```
## 📊 Event Data
Events include:
- Unique event ID
- Project & client ID
- Session & user ID
- Event type (pageview/click/custom)
- Timestamp
- Page URL & referrer
- Page & viewport dimensions
- For clicks: coordinates, selectors, element info
- Custom properties
Example click event:
```json
{
"type": "click",
"pageX": 123,
"pageY": 456,
"selector": "body > main > button.cta",
"xpath": "/body/main/button[1]",
"tagName": "button"
}
```
## 🏗️ Architecture (SOLID)
Built with SOLID principles:
| Principle | Implementation |
| --------- | ------------------------------------- |
| **S**RP | Each module has single responsibility |
| **O**CP | Plugins extend without modifying core |
| **L**SP | Transmitters are interchangeable |
| **I**SP | Minimal, focused interfaces |
| **D**IP | DI container manages all dependencies |
See [Architecture](./docs/ARCHITECTURE.md) for details.
## 📦 Installation
### NPM
```bash
npm install @omni-analytics/sdk @omni-analytics/react
```
### PNPM
```bash
pnpm add @omni-analytics/sdk @omni-analytics/react
```
### Yarn
```bash
yarn add @omni-analytics/sdk @omni-analytics/react
```
### CDN
```html
const { initializeSDK } = window.OmniAnalytics;
initializeSDK({
projectId: "my-project",
endpoint: "https://api.example.com/events",
});
```
## 🚀 Usage Examples
### Basic Initialization
```typescript
import { initializeSDK } from "@omni-analytics/sdk";
const { tracker } = initializeSDK({
projectId: "my-project",
endpoint: "https://api.example.com/events",
});
```
### Custom Event Tracking
```typescript
tracker.trackCustom("user-signup", {
plan: "premium",
source: "homepage",
});
```
### User Management
```typescript
// After login
tracker.setUserId("user-123");
// After logout
tracker.setUserId(null);
tracker.newSession();
```
### React Integration
```typescript
import { initializeSDK } from "@omni-analytics/sdk";
import { TrackerProvider, useTracker } from "@omni-analytics/react";
const { tracker } = initializeSDK({
projectId: "my-project",
endpoint: "https://api.example.com/events",
});
function App() {
return (
);
}
```
### Custom Plugin
```typescript
import { IPlugin, PluginContext } from "@omni-analytics/sdk";
class FormTrackingPlugin implements IPlugin {
name = "form-tracking";
version = "1.0.0";
async init(context: PluginContext) {
document.addEventListener("submit", (e) => {
const form = e.target as HTMLFormElement;
context.tracker.trackCustom("form-submitted", {
formId: form.id,
fields: form.elements.length,
});
});
}
async destroy() {}
}
```
## 📈 Event Batching
Events are automatically batched for efficiency:
```typescript
const { tracker } = initializeSDK({
projectId: "my-project",
endpoint: "https://api.example.com/events",
batchSize: 50, // Send after 50 events
batchTimeout: 10000, // Or after 10 seconds
});
```
## 🐛 Debug Mode
Enable debug logging:
```typescript
const { tracker } = initializeSDK({
projectId: "my-project",
endpoint: "https://api.example.com/events",
debug: true,
});
// Console output:
// [OmniSDK] Config initialized: {...}
// [Tracker] Tracking event: {...}
// [EventQueue] Flushing batch: 50 events
```
## 📚 Documentation
- **[Getting Started](./docs/GETTING_STARTED.md)** - Beginner's guide
- **[API Reference](./docs/API_REFERENCE.md)** - Complete API docs
- **[Architecture](./docs/ARCHITECTURE.md)** - Design & internals
- **[Plugin Development](./docs/PLUGIN_DEVELOPMENT.md)** - Create plugins
## 🤝 Workspace Structure
```
omni-sdk/
├── packages/
│ ├── sdk/ # Core SDK
│ │ └── src/
│ │ ├── config/
│ │ ├── di/
│ │ ├── plugins/
│ │ ├── queue/
│ │ ├── session/
│ │ ├── tracker/
│ │ ├── transmitter/
│ │ ├── types/
│ │ └── utils/
│ ├── react/ # React integration
│ │ └── src/
│ │ ├── context/
│ │ ├── hooks/
│ │ └── index.ts
│ └── test-app/ # Example app
├── docs/ # Documentation
└── rollup.config.js # Build config
```
## 🛠️ Development
### Setup
```bash
pnpm install
```
### Build
```bash
pnpm build
```
### Watch Mode
```bash
pnpm dev
```
### Build Output
- **CJS** - `packages/sdk/dist/index.cjs.js` (Node.js, bundlers)
- **ESM** - `packages/sdk/dist/index.esm.js` (Modern bundlers)
- **UMD** - `packages/sdk/dist/index.umd.js` (Browser, CDN)
- **Types** - `packages/sdk/dist/index.d.ts` (TypeScript)
## 📊 Performance
| Metric | Value |
| ------------- | ------------------------ |
| SDK Init | <5ms |
| Event Track | <1ms |
| Batch Size | 50 events (default) |
| Batch Timeout | 10 seconds (default) |
| Bundle Size | 16KB (minified, gzipped) |
| Memory/Event | ~200 bytes |
## 🌐 Browser Support
- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+
## ✅ Features Status
- [x] Core SDK architecture
- [x] Automatic page view tracking
- [x] Automatic click tracking
- [x] Event batching
- [x] Session management
- [x] Plugin system
- [x] React integration
- [x] TypeScript support
- [x] Multiple transmitters
- [x] Documentation
- [ ] Jest unit tests
- [ ] E2E tests
- [ ] Example applications
## 🔮 Roadmap
- Custom event serialization
- Event sampling
- Performance metrics collection
- Error tracking
- Redux middleware
- Vue integration
- Svelte integration
- Analytics dashboard
## 📄 License
ISC
## 🤝 Contributing
Contributions welcome! Please:
1. Follow SOLID principles
2. Add tests for new features
3. Update documentation
4. Keep bundle size small
## 📧 Support
- Email: support@example.com
- Issues: GitHub Issues
- Discussions: GitHub Discussions
---
**Made with ❤️ for analytics**