rozmova-analytics 1.1.39 → 1.1.41

package/README.md

@@ -68,16 +68,25 @@ window.Analytics.trackEvent("button_click", { button_name: "Sign Up" });
 Initializes the analytics library, setting up Mixpanel, Google Analytics, Customer.io, and Microsoft Clarity integrations.
 
 **Parameters:**
+- `config.isProd?: boolean` - Whether the environment is production (default: true)
 - `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
+- `config.config?: object` - Initial configuration object with userId and email
+  - `config.config.userId?: string` - Initial user ID
+  - `config.config.email?: string` - Initial user email
 
 **Example:**
 ```javascript
 Analytics.init({
+  isProd: true,
   locale: "en",
   platform: "web",
-  isClearly: true
+  isClearly: true,
+  config: {
+    userId: "user-123",
+    email: "user@example.com"
+  }
 });
 ```
 
@@ -126,6 +135,8 @@ Associates a user with the provided user ID and sets user properties across all
     - `locale: string` - User's locale
     - `phone?: string` - User's phone number (optional)
     - `isB2B?: boolean` - Whether the user is a business user (optional)
+    - `CIOParams?: EventParams` - Additional properties for Customer.io (optional)
+    - `mixpanelParams?: Dict` - Additional properties for Mixpanel (optional)
 
 **Example:**
 ```javascript
@@ -135,13 +146,19 @@ Analytics.setUser("user-456", {
   numberOfSessions: 3,
   locale: "en",
   phone: "+1234567890",
-  isB2B: true
+  isB2B: true,
+  CIOParams: {
+    custom_field: "value"
+  },
+  mixpanelParams: {
+    $created: "2024-01-01"
+  }
 });
 ```
 
 ### `resetUser()`
 
-Resets the current user across all analytics providers, clears stored user data, generates a new user ID, and reinitializes the library.
+Resets the current user across all analytics providers, clears stored user data, generates a new user ID, and reinitializes the library. Automatically calls `init()` after reset.
 
 **Example:**
 ```javascript
@@ -164,20 +181,13 @@ Analytics.setUserTag("subscription_plan", "pro");
 
 ### `setConfig(params?)`
 
-Updates the analytics configuration with new parameters.
+Updates the analytics configuration with new parameters. This is a private method but can be called indirectly through `setUser()` or `resetUser()`.
 
 **Parameters:**
-- `params.userId?: string` - User ID to set
-- `params.email?: string` - User email to set
-- `params.locale?: string` - Locale to set
+- `params.userId?: string` - User ID to set (default: from profile)
+- `params.email?: string` - User email to set (default: from profile)
 
-**Example:**
-```javascript
-Analytics.setConfig({
-  userId: "new-user-id",
-  locale: "fr"
-});
-```
+**Note:** This method is called automatically when setting or resetting users. Direct usage is not recommended.
 
 ### `setLocale(newLocale)`
 
@@ -191,13 +201,20 @@ Updates the locale for analytics data.
 Analytics.setLocale("es");
 ```
 
-### `trackPageView()`
+### `trackPageView(options?)`
 
 Tracks a page view event with current page information including title, location, and referrer.
 
+**Parameters:**
+- `options.referrer?: string` - Custom referrer URL (optional, defaults to document.referrer)
+
 **Example:**
 ```javascript
+// Track with default referrer
 Analytics.trackPageView();
+
+// Track with custom referrer
+Analytics.trackPageView({ referrer: "https://example.com" });
 ```
 
 ### `getCommonParams()`
@@ -223,6 +240,77 @@ Retrieves the current user ID from cookies, localStorage, or URL query parameter
 const userId = Analytics.getUserId();
 ```
 
+### `getGAClientId()`
+
+Retrieves the Google Analytics client ID asynchronously.
+
+**Returns:** `Promise<string | null>`
+
+**Example:**
+```javascript
+const gaClientId = await Analytics.getGAClientId();
+```
+
+### `setGAClientId(clientId)`
+
+Sets the Google Analytics client ID.
+
+**Parameters:**
+- `clientId: string` - The GA client ID to set
+
+**Example:**
+```javascript
+Analytics.setGAClientId("1234567890.1234567890");
+```
+
+### `getAttributionProperties(forcedAttributionProperties?)`
+
+Retrieves comprehensive attribution properties including funnel info, tracking parameters, and external analytics user information.
+
+**Parameters:**
+- `forcedAttributionProperties?: ForcedAttributionProperties` - Optional forced attribution properties
+  - `forcedAttributionProperties.funnelName?: string` - Override funnel name
+
+**Returns:** `Promise<UserAttributionProperties>`
+
+**Example:**
+```javascript
+const attribution = await Analytics.getAttributionProperties({
+  funnelName: "custom_funnel"
+});
+
+console.log(attribution.funnelInfo);
+console.log(attribution.trackingParams);
+console.log(attribution.externalAnalyticsUserInfo);
+```
+
+### `trackFirstPartyEvent(eventName, properties?, forcedAttributionProperties?)`
+
+Tracks an event to your first-party analytics endpoint with comprehensive attribution data encoded in headers.
+
+**Parameters:**
+- `eventName: string` - The name of the event to track
+- `properties?: EventParams` - Additional event properties (optional)
+- `forcedAttributionProperties?: ForcedAttributionProperties` - Optional forced attribution properties
+
+**Returns:** `Promise<Response>`
+
+**Example:**
+```javascript
+// Track first-party event
+await Analytics.trackFirstPartyEvent("purchase_completed", {
+  product_id: "123",
+  price: 29.99
+});
+
+// Track with forced attribution
+await Analytics.trackFirstPartyEvent("signup", {
+  source: "landing_page"
+}, {
+  funnelName: "marketing_campaign"
+});
+```
+
 ## Analytics Providers
 
 The library integrates with multiple analytics providers out of the box:
@@ -309,14 +397,25 @@ Analytics.trackEvent("feature_used", {
   user_tier: "premium"
 });
 
+// Track first-party event with attribution
+await Analytics.trackFirstPartyEvent("purchase", {
+  product_id: "123",
+  amount: 99.99
+});
+
+// Get attribution properties
+const attribution = await Analytics.getAttributionProperties();
+console.log(attribution.funnelInfo, attribution.trackingParams);
+
+// Get GA client ID
+const gaClientId = await Analytics.getGAClientId();
+
 // Set user tags for Clarity
 Analytics.setUserTag("subscription", "premium");
 Analytics.setUserTag("user_segment", "power_user");
 
-// Update configuration
-Analytics.setConfig({
-  locale: "fr"
-});
+// Update locale
+Analytics.setLocale("fr");
 
 // Reset user on logout
 Analytics.resetUser();
@@ -352,7 +451,11 @@ The library includes TypeScript definitions for better development experience:
 
 ```typescript
 import Analytics from "rozmova-analytics";
-import type { EventParams } from "rozmova-analytics";
+import type { 
+  EventParams, 
+  UserAttributionProperties,
+  ForcedAttributionProperties 
+} from "rozmova-analytics";
 
 // Type-safe event tracking
 const eventParams: EventParams = {
@@ -361,6 +464,16 @@ const eventParams: EventParams = {
 };
 
 Analytics.trackEvent("product_view", eventParams);
+
+// Type-safe attribution properties
+const attribution: UserAttributionProperties = await Analytics.getAttributionProperties();
+
+// Type-safe first-party event tracking
+const forcedAttribution: ForcedAttributionProperties = {
+  funnelName: "custom_funnel"
+};
+
+await Analytics.trackFirstPartyEvent("signup", eventParams, forcedAttribution);
 ```
 
 ## Contributing

package/dist/helpers.d.ts

@@ -8,8 +8,8 @@ export declare function detectOS(): "Windows" | "macOS" | "Linux" | "Android" |
 export declare const getDomain: () => string;
 export declare const getReferrer: () => string | null;
 export declare function getSearchQueryFromReferrer(): string | null;
-export declare const getClientIdFromCookies: () => string;
-export declare const getGAClientId: () => Promise<string>;
+export declare const getClientIdFromCookies: () => string | null;
+export declare const getGAClientId: () => Promise<string | null>;
 export declare function getGASessionId(): string | null;
 export declare const setGAClientId: (clientId: string) => void;
 export declare const getLocaleFromURL: (isClearly?: boolean) => string;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Dict } from "mixpanel-browser";
 import { AnalyticsCommonParams, EventParams, ForcedAttributionProperties, UserAttributionProperties } from "./types";
 type GConfig = {
     userId?: string;
@@ -20,7 +21,7 @@ declare class Analytics {
     }): Promise<void>;
     private processDataLayer;
     setUserTag(key: string, value: string): void;
-    getGAClientId(): Promise<string>;
+    getGAClientId(): Promise<string | null>;
     setGAClientId: (clientId: string) => void;
     trackEvent(eventName: string, properties?: EventParams, services?: {
         ga?: boolean;
@@ -38,6 +39,8 @@ declare class Analytics {
         locale: string;
         phone?: string;
         isB2B?: boolean;
+        CIOParams?: EventParams;
+        mixpanelParams?: Dict;
     }): void;
     getCommonParams(): AnalyticsCommonParams;
     setLocale(newLocale: string): void;

package/dist/index.esm.js

@@ -12129,35 +12129,39 @@ function getSearchQueryFromReferrer() {
     return null;
 }
 const getClientIdFromCookies = () => {
-    const clientId = api.get("_ga");
-    if (!clientId)
-        return "";
-    const splitedClientId = clientId.split(".");
-    return splitedClientId[2] + "." + splitedClientId[3];
+    const ga = api.get("_ga");
+    if (!ga)
+        return null;
+    const parts = ga.split(".");
+    if (parts.length < 4)
+        return null;
+    return `${parts[2]}.${parts[3]}`;
 };
 const getGAClientId = () => {
     return new Promise((resolve) => {
-        if (typeof gtag !== "undefined") {
+        let resolved = false;
+        const fallback = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(getClientIdFromCookies());
+        };
+        if (typeof window !== "undefined" && typeof gtag === "function") {
             try {
-                gtag("get", GOOGLE_ANALYTICS_ID, "client_id", function (clientId) {
-                    if (clientId) {
-                        resolve(clientId);
-                    }
-                    else {
-                        resolve(getClientIdFromCookies());
-                    }
+                gtag("get", GOOGLE_ANALYTICS_ID, "client_id", (clientId) => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    resolve(clientId || getClientIdFromCookies());
                 });
-                setTimeout(() => {
-                    resolve(getClientIdFromCookies());
-                }, 1000);
+                setTimeout(fallback, 1000);
             }
-            catch (error) {
-                console.warn("Error getting client ID from gtag:", error);
-                resolve(getClientIdFromCookies());
+            catch {
+                fallback();
             }
         }
         else {
-            resolve(getClientIdFromCookies());
+            fallback();
         }
     });
 };
@@ -12167,16 +12171,15 @@ function getGASessionId() {
         return null;
     const parts = cookieValue.split(".");
     const version = parts[0];
-    if (version === "GS1" && parts.length === 4) {
-        // GS1.1.1696433766.1696433857
-        return parts[2]; // session start timestamp
+    // GS1.x.<sid>
+    if (version === "GS1" && parts.length >= 3) {
+        return parts[2];
     }
-    if (version === "GS2" && parts.length >= 3) {
-        // GS2.1.s1746513327$o1$g1$t1746513329$j58$l0$h0
-        const match = parts[2].match(/s(\d+)/);
-        if (match) {
-            return match[1]; // session ID (session start)
-        }
+    // GS2.x.s<sid>$...
+    if (version === "GS2") {
+        const match = cookieValue.match(/s(\d+)/);
+        if (match)
+            return match[1];
     }
     return null;
 }
@@ -12816,12 +12819,18 @@ class Analytics {
         });
     }
     setUser(userId, userParams) {
-        const { email, name, phone, isB2B } = userParams;
+        const { email, name, phone, isB2B, CIOParams = {}, mixpanelParams = {}, } = userParams;
         // Update config
         this.setConfig({ userId, email });
         // Mixpanel user
         mixpanel.identify(userId);
-        mixpanel.people.set({ $email: email, name, phone, isB2B });
+        mixpanel.people.set({
+            $email: email,
+            name,
+            phone,
+            isB2B,
+            ...mixpanelParams,
+        });
         // GA user
         // gtag("config", GOOGLE_ANALYTICS_ID, {
         //   user_properties: this.getCommonParams(),
@@ -12829,7 +12838,7 @@ class Analytics {
         //   server_container_url: GA_SERVER_CONTAINER_URL,
         // });
         // Customer IO user
-        window.analytics.identify(userId, userParams);
+        window.analytics.identify(userId, { ...userParams, ...CIOParams });
         // store user id in cookies
         setProfileId(userId);
         // store user email in cookies
@@ -12873,10 +12882,10 @@ class Analytics {
     }
     getUserId = getUserId;
     async getAttributionProperties(forcedAttributionProperties) {
-        const paramsFromCookie = this.getCommonParams();
+        const gaClientId = await this.getGAClientId();
         const { listName, index } = getLastListNameAndIndex();
         const placement = localStorage.getItem(CREATE_THERAPY_PAGE_PLACEMENT_KEY);
-        const gaClientId = await this.getGAClientId();
+        const paramsFromCookie = this.getCommonParams();
         return {
             funnelInfo: {
                 funnelName: forcedAttributionProperties?.funnelName ||

package/dist/index.js

@@ -12131,35 +12131,39 @@ function getSearchQueryFromReferrer() {
     return null;
 }
 const getClientIdFromCookies = () => {
-    const clientId = api.get("_ga");
-    if (!clientId)
-        return "";
-    const splitedClientId = clientId.split(".");
-    return splitedClientId[2] + "." + splitedClientId[3];
+    const ga = api.get("_ga");
+    if (!ga)
+        return null;
+    const parts = ga.split(".");
+    if (parts.length < 4)
+        return null;
+    return `${parts[2]}.${parts[3]}`;
 };
 const getGAClientId = () => {
     return new Promise((resolve) => {
-        if (typeof gtag !== "undefined") {
+        let resolved = false;
+        const fallback = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolve(getClientIdFromCookies());
+        };
+        if (typeof window !== "undefined" && typeof gtag === "function") {
             try {
-                gtag("get", GOOGLE_ANALYTICS_ID, "client_id", function (clientId) {
-                    if (clientId) {
-                        resolve(clientId);
-                    }
-                    else {
-                        resolve(getClientIdFromCookies());
-                    }
+                gtag("get", GOOGLE_ANALYTICS_ID, "client_id", (clientId) => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    resolve(clientId || getClientIdFromCookies());
                 });
-                setTimeout(() => {
-                    resolve(getClientIdFromCookies());
-                }, 1000);
+                setTimeout(fallback, 1000);
             }
-            catch (error) {
-                console.warn("Error getting client ID from gtag:", error);
-                resolve(getClientIdFromCookies());
+            catch {
+                fallback();
             }
         }
         else {
-            resolve(getClientIdFromCookies());
+            fallback();
         }
     });
 };
@@ -12169,16 +12173,15 @@ function getGASessionId() {
         return null;
     const parts = cookieValue.split(".");
     const version = parts[0];
-    if (version === "GS1" && parts.length === 4) {
-        // GS1.1.1696433766.1696433857
-        return parts[2]; // session start timestamp
+    // GS1.x.<sid>
+    if (version === "GS1" && parts.length >= 3) {
+        return parts[2];
     }
-    if (version === "GS2" && parts.length >= 3) {
-        // GS2.1.s1746513327$o1$g1$t1746513329$j58$l0$h0
-        const match = parts[2].match(/s(\d+)/);
-        if (match) {
-            return match[1]; // session ID (session start)
-        }
+    // GS2.x.s<sid>$...
+    if (version === "GS2") {
+        const match = cookieValue.match(/s(\d+)/);
+        if (match)
+            return match[1];
     }
     return null;
 }
@@ -12818,12 +12821,18 @@ class Analytics {
         });
     }
     setUser(userId, userParams) {
-        const { email, name, phone, isB2B } = userParams;
+        const { email, name, phone, isB2B, CIOParams = {}, mixpanelParams = {}, } = userParams;
         // Update config
         this.setConfig({ userId, email });
         // Mixpanel user
         mixpanel.identify(userId);
-        mixpanel.people.set({ $email: email, name, phone, isB2B });
+        mixpanel.people.set({
+            $email: email,
+            name,
+            phone,
+            isB2B,
+            ...mixpanelParams,
+        });
         // GA user
         // gtag("config", GOOGLE_ANALYTICS_ID, {
         //   user_properties: this.getCommonParams(),
@@ -12831,7 +12840,7 @@ class Analytics {
         //   server_container_url: GA_SERVER_CONTAINER_URL,
         // });
         // Customer IO user
-        window.analytics.identify(userId, userParams);
+        window.analytics.identify(userId, { ...userParams, ...CIOParams });
         // store user id in cookies
         setProfileId(userId);
         // store user email in cookies
@@ -12875,10 +12884,10 @@ class Analytics {
     }
     getUserId = getUserId;
     async getAttributionProperties(forcedAttributionProperties) {
-        const paramsFromCookie = this.getCommonParams();
+        const gaClientId = await this.getGAClientId();
         const { listName, index } = getLastListNameAndIndex();
         const placement = localStorage.getItem(CREATE_THERAPY_PAGE_PLACEMENT_KEY);
-        const gaClientId = await this.getGAClientId();
+        const paramsFromCookie = this.getCommonParams();
         return {
             funnelInfo: {
                 funnelName: forcedAttributionProperties?.funnelName ||