rozmova-analytics 1.1.12 → 1.1.14

package/README.md

@@ -3,7 +3,7 @@
 [![npm-version](https://img.shields.io/npm/v/rozmova-analytics.svg)](https://www.npmjs.com/package/rozmova-analytics)
 [![minified-size](https://img.shields.io/bundlephobia/minzip/rozmova-analytics@1.0.7)](https://bundlephobia.com/package/rozmova-analytics)
 
-A lightweight JavaScript analytics library designed to streamline event tracking, user identification, and common analytics parameter management. This package integrates with Mixpanel and Google Analytics to provide seamless data collection and insights.
+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
 
@@ -15,7 +15,7 @@ npm install rozmova-analytics
 
 Alternatively, you can include the library via jsDelivr to use in browser:
 
-```bash
+```html
 <script src="https://cdn.jsdelivr.net/npm/rozmova-analytics/dist/index.umd.js"></script>
 ```
 
@@ -24,25 +24,23 @@ Alternatively, you can include the library via jsDelivr to use in browser:
 Import the library in your project and initialize it:
 
 ```javascript
-import {
-  generateUserId,
-  getCommonParams,
-  getUserId,
-  init,
-  resetUser,
-  setUser,
-  trackEvent,
-  setLocale,
-} from "rozmova-analytics";
+import Analytics from "rozmova-analytics";
 
 // Initialize the library
-init({ locale: "en", platform: "web", isClearly: true });
+Analytics.init({ locale: "en", platform: "web", isClearly: true });
 
 // Set user
-setUser("user-id-123", { email: "user@example.com", name: "John Doe" });
+Analytics.setUser("user-id-123", {
+  email: "user@example.com",
+  name: "John Doe",
+  numberOfSessions: 5,
+  locale: "en",
+  phone: "+1234567890",
+  isB2B: false
+});
 
 // Track an event
-trackEvent("button_click", { button_name: "Sign Up" });
+Analytics.trackEvent("button_click", { button_name: "Sign Up" });
 ```
 
 Or use in browser:
@@ -55,77 +53,325 @@ window.Analytics.init({ locale: "en", platform: "web" });
 window.Analytics.setUser("user-id-123", {
   email: "user@example.com",
   name: "John Doe",
+  numberOfSessions: 1,
+  locale: "en"
 });
 
 // Track an event
 window.Analytics.trackEvent("button_click", { button_name: "Sign Up" });
 ```
 
-## API
+## API Reference
 
-### `init(initParams:{locale?: string, platform?: string})`
+### `init(config?)`
 
-Initializes the analytics library, setting up Mixpanel and Google Analytics integrations. Optionally, set a locale and platform.
+Initializes the analytics library, setting up Mixpanel, Google Analytics, Customer.io, and Microsoft Clarity integrations.
 
-### `generateUserId()`
+**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
 
-Generates a unique user ID, stores it in cookies and localStorage, and returns the ID.
+**Example:**
+```javascript
+Analytics.init({
+  locale: "en",
+  platform: "web",
+  isClearly: true
+});
+```
 
-### `getUserId()`
+### `trackEvent(eventName, properties?, services?)`
 
-Retrieves the user ID from cookies, localStorage, or URL query parameters. If not found, generates a new one.
+Tracks an event across the specified analytics providers.
 
-### `getCommonParams()`
+**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)
 
-Returns an object with common analytics parameters such as device, browser, referrer, and UTM parameters.
+**Example:**
+```javascript
+// Track to all services
+Analytics.trackEvent("purchase", {
+  product_id: "123",
+  price: 29.99,
+  currency: "USD"
+});
 
-### `setLocale(newLocale: string)`
+// Track to specific services only
+Analytics.trackEvent("newsletter_signup", {
+  source: "footer"
+}, {
+  ga: true,
+  mixpanel: false,
+  customerIO: true
+});
+```
+
+### `setUser(userId, userParams)`
 
-Sets the locale for analytics data.
+Associates a user with the provided user ID and sets user properties across all analytics providers.
 
-### `setUser(userId: string, userParams: { email: string; name: string })`
+**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)
 
-Associates a user with the provided user ID and sets user properties in Mixpanel and Google Analytics.
+**Example:**
+```javascript
+Analytics.setUser("user-456", {
+  email: "jane@example.com",
+  name: "Jane Doe",
+  numberOfSessions: 3,
+  locale: "en",
+  phone: "+1234567890",
+  isB2B: true
+});
+```
 
 ### `resetUser()`
 
-Resets the current user, generating a new user ID and reinitializing the library.
+Resets the current user across all analytics providers, clears stored user data, generates a new user ID, and reinitializes the library.
+
+**Example:**
+```javascript
+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:**
+```javascript
+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:**
+```javascript
+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:**
+```javascript
+Analytics.setLocale("es");
+```
+
+### `trackPageView()`
+
+Tracks a page view event with current page information including title, location, and referrer.
+
+**Example:**
+```javascript
+Analytics.trackPageView();
+```
+
+### `getCommonParams()`
 
-### `trackEvent(eventName: string, properties?: EventParams, services = {ga: true, mixpanel: true, customerIO: true})`
+Returns a promise that resolves to an object with common analytics parameters including device information, browser details, UTM parameters, user data, and session information.
 
-Tracks an event with the specified name and optional properties, services.
+**Returns:** `Promise<AnalyticsCommonParams>`
+
+**Example:**
+```javascript
+const params = await 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:**
+```javascript
+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 the following:
+The package works on modern browsers and supports:
 
-- Chrome
-- Firefox
-- Safari
-- Edge
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
 
 ## Example Integration
 
 ```javascript
-import { init, trackEvent, setUser, resetUser } from "rozmova-analytics";
+import Analytics from "rozmova-analytics";
 
 // Initialize analytics
-init({ locale: "en", platform: "ios", isClearly: true });
+Analytics.init({ 
+  locale: "en", 
+  platform: "web", 
+  isClearly: true 
+});
 
-// Track a page view event
-trackEvent("page_view", { page: "Home" });
+// Track a page view (automatically called during init)
+Analytics.trackPageView();
 
 // Set user details
-setUser("user-456", { email: "user456@example.com", name: "Jane Doe" });
+Analytics.setUser("user-456", {
+  email: "user456@example.com",
+  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:
 
-// Reset the user
-resetUser();
+```javascript
+// 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:
+
+```typescript
+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.
+This project is licensed under the MIT License.

package/dist/analytics.d.ts

@@ -16,3 +16,6 @@ export declare const initialLoginEvent: (trackEvent: (eventName: string, propert
 export declare const setProfileId: (profileId: string) => void;
 export declare const getProfileId: () => string | undefined;
 export declare const resetProfileId: () => void;
+export declare const setProfileEmail: (email: string) => void;
+export declare const getProfileEmail: () => string | undefined;
+export declare const resetProfileEmail: () => void;

package/dist/constants.d.ts

@@ -8,3 +8,4 @@ export declare const CUSTOMER_IO_WRITE_KEY = "e6d009719c77519432c3";
 export declare const CLARITY_ID = "irbqmnlbwz";
 export declare const SUPPORTED_LANGUAGES: string[];
 export declare const GA_ECOMMERCE_EVENTS: string[];
+export declare const INTERNAL_USER_EMAILS: string[];

package/dist/helpers.d.ts

@@ -12,3 +12,4 @@ export declare const getClientIdFromCookies: () => string;
 export declare const getGAClientId: () => Promise<string>;
 export declare function getGASessionId(): string | null;
 export declare const getLocaleFromURL: (isClearly?: boolean) => string;
+export declare const getUserType: (email?: string) => "external" | "internal";

package/dist/index.d.ts

@@ -9,12 +9,19 @@ declare class Analytics {
         platform?: string;
         isClearly?: boolean;
     }): void;
+    private processDataLayer;
     setUserTag(key: string, value: string): void;
     trackEvent(eventName: string, properties?: EventParams, services?: {
         ga?: boolean;
         mixpanel?: boolean;
         customerIO?: boolean;
     }): Promise<void>;
+    setConfig({ userId, email, locale, }?: {
+        userId?: string;
+        email?: string;
+        locale?: string;
+    }): void;
+    trackPageView(): void;
     setUser(userId: string, userParams: {
         email: string;
         name: string;

package/dist/index.esm.js

@@ -12003,6 +12003,7 @@ const GA_ECOMMERCE_EVENTS = [
     "begin_checkout",
     "add_payment_info",
 ];
+const INTERNAL_USER_EMAILS = ["rozmova.me", "uptech.team"];
 
 const setQueryParam = (name, value) => {
     const url = new URL(window.location.href);
@@ -12183,6 +12184,12 @@ const getLocaleFromURL = (isClearly) => {
     else
         return isClearly ? "en" : "uk";
 };
+const getUserType = (email) => {
+    if (!email)
+        return "external";
+    const isInternal = INTERNAL_USER_EMAILS.some((internalEmail) => email.includes(internalEmail));
+    return isInternal ? "internal" : "external";
+};
 
 function insertCustomerIOScript() {
     const scriptContent = `
@@ -12298,6 +12305,18 @@ const resetProfileId = () => {
     const domain = getDomain();
     api.remove(PROFILE_ID_KEY, { domain });
 };
+const PROFILE_EMAIL_KEY = "my_profile_email";
+const setProfileEmail = (email) => {
+    const domain = getDomain();
+    api.set(PROFILE_EMAIL_KEY, email, { domain });
+};
+const getProfileEmail = () => {
+    return api.get(PROFILE_EMAIL_KEY);
+};
+const resetProfileEmail = () => {
+    const domain = getDomain();
+    api.remove(PROFILE_EMAIL_KEY, { domain });
+};
 
 /*!
 * CookieConsent 3.0.1
@@ -12551,12 +12570,25 @@ class Analytics {
         Clarity.init(CLARITY_ID);
         const userProperties = this.getCommonParams();
         mixpanel.register(userProperties);
+        this.setConfig();
+        this.trackPageView();
         gtag("config", GOOGLE_ANALYTICS_ID, {
             user_properties: userProperties,
             server_container_url: GA_SERVER_CONTAINER_URL,
         });
         initialLoginEvent(this.trackEvent.bind(this));
         this.initialized = true;
+        this.processDataLayer();
+    }
+    processDataLayer() {
+        const priorityEvents = ["g_config", "page_view"];
+        for (const priorityEvent of priorityEvents) {
+            const eventIndex = this.dataLayer.findIndex((event) => event.eventName === priorityEvent);
+            if (eventIndex !== -1) {
+                const event = this.dataLayer.splice(eventIndex, 1)[0];
+                this.trackEvent(event.eventName, event.eventParams);
+            }
+        }
         while (this.dataLayer.length > 0) {
             const event = this.dataLayer.shift();
             this.trackEvent(event?.eventName, event?.eventParams);
@@ -12618,6 +12650,24 @@ class Analytics {
             }
         }
     }
+    setConfig({ userId, email, locale, } = {}) {
+        const user_id = userId || getProfileId();
+        const user_email = email || getProfileEmail();
+        this.trackEvent("g_config", {
+            user_id,
+            is_logged: user_id ? "yes" : "no",
+            locale: locale || this.locale,
+            platform: this.platform,
+            user_type: getUserType(user_email),
+        });
+    }
+    trackPageView() {
+        this.trackEvent("page_view", {
+            page_title: document.title,
+            page_location: window.location.href,
+            page_referrer: document.referrer,
+        });
+    }
     setUser(userId, userParams) {
         if (!this.initialized) {
             console.warn("Analytics is not initialized.");
@@ -12637,6 +12687,8 @@ class Analytics {
         window.analytics.identify(userId, userParams);
         // store user id in cookies
         setProfileId(userId);
+        // store user email in cookies
+        setProfileEmail(email);
         // login event
         this.trackEvent("login", { logged: "yes", uid: userId });
     }
@@ -12673,6 +12725,7 @@ class Analytics {
         mixpanel.reset();
         window.analytics.reset();
         resetProfileId();
+        resetProfileEmail();
         this.trackEvent("login", { logged: "no" });
         generateUserId();
         this.init();

package/dist/index.js

@@ -12005,6 +12005,7 @@ const GA_ECOMMERCE_EVENTS = [
     "begin_checkout",
     "add_payment_info",
 ];
+const INTERNAL_USER_EMAILS = ["rozmova.me", "uptech.team"];
 
 const setQueryParam = (name, value) => {
     const url = new URL(window.location.href);
@@ -12185,6 +12186,12 @@ const getLocaleFromURL = (isClearly) => {
     else
         return isClearly ? "en" : "uk";
 };
+const getUserType = (email) => {
+    if (!email)
+        return "external";
+    const isInternal = INTERNAL_USER_EMAILS.some((internalEmail) => email.includes(internalEmail));
+    return isInternal ? "internal" : "external";
+};
 
 function insertCustomerIOScript() {
     const scriptContent = `
@@ -12300,6 +12307,18 @@ const resetProfileId = () => {
     const domain = getDomain();
     api.remove(PROFILE_ID_KEY, { domain });
 };
+const PROFILE_EMAIL_KEY = "my_profile_email";
+const setProfileEmail = (email) => {
+    const domain = getDomain();
+    api.set(PROFILE_EMAIL_KEY, email, { domain });
+};
+const getProfileEmail = () => {
+    return api.get(PROFILE_EMAIL_KEY);
+};
+const resetProfileEmail = () => {
+    const domain = getDomain();
+    api.remove(PROFILE_EMAIL_KEY, { domain });
+};
 
 /*!
 * CookieConsent 3.0.1
@@ -12553,12 +12572,25 @@ class Analytics {
         Clarity.init(CLARITY_ID);
         const userProperties = this.getCommonParams();
         mixpanel.register(userProperties);
+        this.setConfig();
+        this.trackPageView();
         gtag("config", GOOGLE_ANALYTICS_ID, {
             user_properties: userProperties,
             server_container_url: GA_SERVER_CONTAINER_URL,
         });
         initialLoginEvent(this.trackEvent.bind(this));
         this.initialized = true;
+        this.processDataLayer();
+    }
+    processDataLayer() {
+        const priorityEvents = ["g_config", "page_view"];
+        for (const priorityEvent of priorityEvents) {
+            const eventIndex = this.dataLayer.findIndex((event) => event.eventName === priorityEvent);
+            if (eventIndex !== -1) {
+                const event = this.dataLayer.splice(eventIndex, 1)[0];
+                this.trackEvent(event.eventName, event.eventParams);
+            }
+        }
         while (this.dataLayer.length > 0) {
             const event = this.dataLayer.shift();
             this.trackEvent(event?.eventName, event?.eventParams);
@@ -12620,6 +12652,24 @@ class Analytics {
             }
         }
     }
+    setConfig({ userId, email, locale, } = {}) {
+        const user_id = userId || getProfileId();
+        const user_email = email || getProfileEmail();
+        this.trackEvent("g_config", {
+            user_id,
+            is_logged: user_id ? "yes" : "no",
+            locale: locale || this.locale,
+            platform: this.platform,
+            user_type: getUserType(user_email),
+        });
+    }
+    trackPageView() {
+        this.trackEvent("page_view", {
+            page_title: document.title,
+            page_location: window.location.href,
+            page_referrer: document.referrer,
+        });
+    }
     setUser(userId, userParams) {
         if (!this.initialized) {
             console.warn("Analytics is not initialized.");
@@ -12639,6 +12689,8 @@ class Analytics {
         window.analytics.identify(userId, userParams);
         // store user id in cookies
         setProfileId(userId);
+        // store user email in cookies
+        setProfileEmail(email);
         // login event
         this.trackEvent("login", { logged: "yes", uid: userId });
     }
@@ -12675,6 +12727,7 @@ class Analytics {
         mixpanel.reset();
         window.analytics.reset();
         resetProfileId();
+        resetProfileEmail();
         this.trackEvent("login", { logged: "no" });
         generateUserId();
         this.init();