@analyz-product-analytics/analytics-sdk
v1.0.6
Published
A lightweight, developer-friendly analytics SDK
Downloads
44
Readme
Analyz Analytics SDK
A lightweight, developer-friendly analytics SDK for tracking page views, user sessions, and custom events in your web applications.
Features
- 🚀 Lightweight: Minimal footprint (< 5KB gzipped).
- 🔄 Automatic Session Management: Handles session persistence across reloads.
- 🕵️ Anonymous Tracking: auto-generates IDs for unidentified users.
- ⚛️ Framework Agnostic: Works with Vanilla JS, React, Next.js, Vue, etc.
- ⚡ SPA Support: Automatically tracks route changes in Single Page Applications.
- 🛡️ Type-Safe: Built with TypeScript for full autocomplete support.
Installation
npm install @analyz-product-analytics/analytics-sdk
# or
yarn add @analyz-product-analytics/analytics-sdk
# or
pnpm add @analyz-product-analytics/analytics-sdkQuick Start
- Initialize the SDK Initialize the SDK as early as possible in your application (e.g., in your root layout or entry file).
import { init } from '@analyz-product-analytics/analytics-sdk';
init('YOUR_PROJECT_API_KEY', {
debug: false, // Set to true to see logs in console
});- Automatic Page View Tracking For Single Page Applications (Next.js, React Router), start page tracking once. It will automatically listen to History API changes.
import { startPageTracking } from '@analyz-product-analytics/analytics-sdk';
// Starts tracking initial page load + all future navigation
startPageTracking();Usage Guide
Identifying Users
When a user logs in, identify them to link their anonymous session to their actual user ID.
import { identify } from '@analyz-product-analytics/analytics-sdk';
// Call this after successful login
identify('user_12345');Tracking Custom Events
Track specific user interactions like button clicks, form submissions, or errors.
import { track } from '@analyz-product-analytics/analytics-sdk';
// Track a simple event
track('add_to_cart');
// Track with properties
track('purchase_completed', {
item_id: 'prod_999',
value: 49.99,
currency: 'USD',
plan: 'premium'
});Integration Examples
Next.js (App Router)
Create a client component to handle initialization (e.g., components/AnalyticsProvider.tsx).
'use client';
import { useEffect } from 'react';
import { init, startPageTracking } from '@analyz-product-analytics/analytics-sdk';
export function AnalyticsProvider() {
useEffect(() => {
// 1. Initialize
init('YOUR_API_KEY');
// 2. Start automatic page tracking
startPageTracking();
}, []);
return null;
}Then add it to your app/layout.tsx:
import { AnalyticsProvider } from './components/AnalyticsProvider';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<AnalyticsProvider />
{children}
</body>
</html>
);
}API Reference
init(apiKey, options?)
Initializes the SDK instance.
- apiKey string Required. Your project's unique identifier.
- options object Optional configuration settings.
Options Object:
- debug (boolean): If true, logs all events and errors to the browser console. Default: false.
- endpoint (string): Overrides the default API URL. Useful for local testing or proxying events.
identify(userId)
Links the current session to a specific user ID.
- userId string Required. The unique ID of the user from your database.
track(eventName, properties?)
Sends a custom event to the analytics server.
- eventName string Required. The name of the event (e.g., "signup_clicked").
- properties object Optional key-value pairs of metadata (e.g., { price: 100 }).
startPageTracking(options?)
Enables automatic tracking of page views on route changes.
Options Object:
- trackReferrer (boolean): Capture where the user came from. Default: true.
- trackTitle (boolean): Capture the document title. Default: true.