rozmova-analytics

A lightweight JavaScript analytics library designed to streamline event tracking, user identification, and common analytics parameter management. This package integrates with Mixpanel, Google Analytics, Customer.io, and Microsoft Clarity to provide seamless data collection and insights.

Installation

Install the package using npm:

npm install rozmova-analytics

Alternatively, you can include the library via jsDelivr to use in browser:

<script src="https://cdn.jsdelivr.net/npm/rozmova-analytics/dist/index.umd.js"></script>

Usage

Import the library in your project and initialize it:

import Analytics from "rozmova-analytics";

// Initialize the library
Analytics.init({ locale: "en", platform: "web", isClearly: true });

// Set user
Analytics.setUser("user-id-123", {
  email: "[email protected]",
  name: "John Doe",
  numberOfSessions: 5,
  locale: "en",
  phone: "+1234567890",
  isB2B: false
});

// Track an event
Analytics.trackEvent("button_click", { button_name: "Sign Up" });

Or use in browser:

// Initialize the library
window.Analytics.init({ locale: "en", platform: "web" });

// Set user
window.Analytics.setUser("user-id-123", {
  email: "[email protected]",
  name: "John Doe",
  numberOfSessions: 1,
  locale: "en"
});

// Track an event
window.Analytics.trackEvent("button_click", { button_name: "Sign Up" });

API Reference

init(config?)

Initializes the analytics library, setting up Mixpanel, Google Analytics, Customer.io, and Microsoft Clarity integrations.

Parameters:

• config.locale?: string - The locale for analytics data (default: auto-detected or "uk")
• config.platform?: string - The platform identifier (default: "web")
• config.isClearly?: boolean - Whether to enable Clearly-specific features like cookie consent banner

Example:

Analytics.init({
  locale: "en",
  platform: "web",
  isClearly: true
});

trackEvent(eventName, properties?, services?)

Tracks an event across the specified analytics providers.

Parameters:

• eventName: string - The name of the event to track
• properties?: EventParams - Additional event properties (optional)
• services?: object - Which services to track to (optional, default: all enabled)
  • ga?: boolean - Google Analytics (default: true)
  • mixpanel?: boolean - Mixpanel (default: true)
  • customerIO?: boolean - Customer.io (default: true)

Example:

// Track to all services
Analytics.trackEvent("purchase", {
  product_id: "123",
  price: 29.99,
  currency: "USD"
});

// Track to specific services only
Analytics.trackEvent("newsletter_signup", {
  source: "footer"
}, {
  ga: true,
  mixpanel: false,
  customerIO: true
});

setUser(userId, userParams)

Associates a user with the provided user ID and sets user properties across all analytics providers.

Parameters:

• userId: string - Unique user identifier
• userParams: object - User properties
  • email: string - User's email address
  • name: string - User's full name
  • numberOfSessions: number - Number of user sessions
  • locale: string - User's locale
  • phone?: string - User's phone number (optional)
  • isB2B?: boolean - Whether the user is a business user (optional)

Example:

Analytics.setUser("user-456", {
  email: "[email protected]",
  name: "Jane Doe",
  numberOfSessions: 3,
  locale: "en",
  phone: "+1234567890",
  isB2B: true
});

resetUser()

Resets the current user across all analytics providers, clears stored user data, generates a new user ID, and reinitializes the library.

Example:

Analytics.resetUser();

setUserTag(key, value)

Sets a user tag in Microsoft Clarity for enhanced user identification and session analysis.

Parameters:

• key: string - The tag key
• value: string - The tag value

Example:

Analytics.setUserTag("user_type", "premium");
Analytics.setUserTag("subscription_plan", "pro");

setConfig(params?)

Updates the analytics configuration with new parameters.

Parameters:

• params.userId?: string - User ID to set
• params.email?: string - User email to set
• params.locale?: string - Locale to set

Example:

Analytics.setConfig({
  userId: "new-user-id",
  locale: "fr"
});

setLocale(newLocale)

Updates the locale for analytics data.

Parameters:

• newLocale: string - The new locale to set

Example:

Analytics.setLocale("es");

trackPageView()

Tracks a page view event with current page information including title, location, and referrer.

Example:

Analytics.trackPageView();

getCommonParams()

Returns an object with common analytics parameters including device information, browser details, UTM parameters, user data, and session information.

Returns: AnalyticsCommonParams

Example:

const params = Analytics.getCommonParams();
console.log(params.device, params.browser, params.locale);

getUserId()

Retrieves the current user ID from cookies, localStorage, or URL query parameters. Generates a new one if not found.

Returns: string

Example:

const userId = Analytics.getUserId();

Analytics Providers

The library integrates with multiple analytics providers out of the box:

Mixpanel

• Event tracking with custom properties
• User identification and profile management
• Automatic page view tracking
• User property registration

Google Analytics 4

• Event tracking with enhanced ecommerce support
• User identification with custom user properties
• Server-side container support
• Automatic ecommerce event handling

Customer.io

• Behavioral event tracking
• User identification and profile management
• Automated messaging and email triggers

Microsoft Clarity

• Session recording and heatmaps
• User tagging for enhanced insights
• Automatic session tracking

Features

Event Queuing

Events tracked before initialization are queued and processed once the library is ready.

Error Handling

Individual service failures don't affect other providers - the library includes comprehensive error handling.

Cookie Consent

Automatic cookie consent banner integration for GDPR compliance when isClearly is enabled.

Meta Browser Detection

Special handling for Meta (Facebook) browsers with automatic URL parameter tracking.

Geo Parameter Storage

Automatic storage and tracking of geographic parameters.

Session Management

Comprehensive session tracking with Google Analytics session IDs and user pseudo IDs.

Browser Support

The package works on modern browsers and supports:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Example Integration

import Analytics from "rozmova-analytics";

// Initialize analytics
Analytics.init({ 
  locale: "en", 
  platform: "web", 
  isClearly: true 
});

// Track a page view (automatically called during init)
Analytics.trackPageView();

// Set user details
Analytics.setUser("user-456", {
  email: "[email protected]",
  name: "Jane Doe",
  numberOfSessions: 1,
  locale: "en",
  phone: "+1234567890",
  isB2B: false
});

// Track custom events
Analytics.trackEvent("feature_used", {
  feature_name: "advanced_search",
  user_tier: "premium"
});

// Set user tags for Clarity
Analytics.setUserTag("subscription", "premium");
Analytics.setUserTag("user_segment", "power_user");

// Update configuration
Analytics.setConfig({
  locale: "fr"
});

// Reset user on logout
Analytics.resetUser();

Configuration

Make sure to configure your analytics provider tokens in your constants file:

// constants.js
export const MIXPANEL_TOKEN = "your-mixpanel-token";
export const GOOGLE_ANALYTICS_ID = "your-ga-measurement-id";
export const CLARITY_ID = "your-clarity-project-id";
export const GA_SERVER_CONTAINER_URL = "your-server-container-url";

Common Parameters

The library automatically collects and includes common parameters with every event:

• Device type, browser, and operating system
• User language and locale
• UTM parameters and referrer information
• Session IDs and user pseudo IDs
• Facebook tracking parameters (fbc, fbp)
• Current URL and page information
• User login status and profile data

TypeScript Support

The library includes TypeScript definitions for better development experience:

import Analytics from "rozmova-analytics";
import type { EventParams } from "rozmova-analytics";

// Type-safe event tracking
const eventParams: EventParams = {
  product_id: "123",
  category: "electronics"
};

Analytics.trackEvent("product_view", eventParams);

Contributing

Contributions are welcome! Please fork the repository and create a pull request with your changes.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License.