@callforge/tracking-client 0.6.1 → 0.6.3

package/README.md

@@ -67,23 +67,25 @@ Notes:
 
 ### 4. GA4 Integration
 
-To enable GA4 call event tracking, provide your GA4 Measurement ID:
+To enable GA4 call event tracking, CallForge needs the GA4 `client_id` for the visitor (from the `_ga` cookie).
+Optionally provide your GA4 Measurement ID to improve client ID capture reliability when Google Analytics loads late.
 
 ```typescript
 const client = CallForge.init({
   categoryId: 'your-category-id',
-  ga4MeasurementId: 'G-XXXXXXXXXX',
+  ga4MeasurementId: 'G-XXXXXXXXXX', // Recommended
 });
 ```
 
 Requirements:
-1. Google Analytics 4 must be installed on your site (`gtag.js`).
-2. Provide `ga4MeasurementId` in client config.
-3. Configure GA4 credentials in CallForge dashboard.
+1. Google Analytics 4 must be installed on your site and allowed to set the `_ga` cookie (gtag.js or GTM).
+2. Configure GA4 credentials in CallForge dashboard (Measurement ID + API secret).
 
 How it works:
-- Uses `gtag('get', measurementId, 'client_id', callback)` to capture the GA4 client ID.
-- Client ID is sent to CallForge for call event attribution.
+- Extracts the GA4 `client_id` from the `_ga` cookie and sends it to CallForge as `ga4ClientId`.
+- Polls briefly after init to capture the cookie if Google Analytics sets it slightly later.
+- If `ga4MeasurementId` is configured and `gtag` is available, also uses `gtag('get', measurementId, 'client_id', ...)` (with a short retry window).
+- If `ga4ClientId` becomes available after a session is created, the client will refresh once to sync it to CallForge.
 
 Manual override:
 
@@ -186,6 +188,7 @@ client.setParams({
 
 Behavior:
 - Merges with existing params (later calls override earlier values).
+- If a session already exists (cached `sessionToken`), the client will refresh once to sync updated params server-side (best-effort).
 - Parameters are sent with every `getSession()` API request.
 - Persisted in localStorage alongside session data.
 

package/dist/index.d.mts

@@ -8,7 +8,7 @@ interface CallForgeConfig {
     endpoint?: string;
     /** Optional - explicit site key for cache partitioning. Defaults to window.location.hostname */
     siteKey?: string;
-    /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag callback instead of cookie polling. */
+    /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag-based client_id capture for late-loading GA. */
     ga4MeasurementId?: string;
 }
 /**
@@ -113,7 +113,10 @@ declare class CallForge {
      */
     onReady(callback: ReadyCallback): void;
     /**
-     * Set custom tracking parameters for the next session fetch.
+     * Set custom tracking parameters for attribution.
+     *
+     * When possible, the client will also refresh the session once to sync
+     * the updated params to CallForge (so server-side events can use them).
      */
     setParams(params: Record<string, string>): Promise<void>;
     /**
@@ -121,10 +124,20 @@ declare class CallForge {
      */
     getQueuedParams(): TrackingParams;
     /**
-     * Capture the GA4 client ID using gtag callback.
-     * Only runs if ga4MeasurementId is configured.
+     * Capture the GA4 client ID.
+     *
+     * Prefer `_ga` cookie parsing (works even when gtag is not loaded yet).
+     * If ga4MeasurementId is configured and gtag is available, use gtag as a fallback.
      */
     private captureGA4ClientId;
+    private startGA4ClientIdPolling;
+    /**
+     * Extract GA4 client_id from the `_ga` cookie.
+     *
+     * Example cookie value: `GA1.1.1234567890.1234567890`
+     * Returns: `1234567890.1234567890`
+     */
+    private getGA4ClientIdFromCookie;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -132,6 +145,7 @@ declare class CallForge {
     private saveToCache;
     private formatSession;
     private formatApiResponse;
+    private syncParamsToCallForgeIfPossible;
     private buildUrl;
 }
 

package/dist/index.d.ts

@@ -8,7 +8,7 @@ interface CallForgeConfig {
     endpoint?: string;
     /** Optional - explicit site key for cache partitioning. Defaults to window.location.hostname */
     siteKey?: string;
-    /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag callback instead of cookie polling. */
+    /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag-based client_id capture for late-loading GA. */
     ga4MeasurementId?: string;
 }
 /**
@@ -113,7 +113,10 @@ declare class CallForge {
      */
     onReady(callback: ReadyCallback): void;
     /**
-     * Set custom tracking parameters for the next session fetch.
+     * Set custom tracking parameters for attribution.
+     *
+     * When possible, the client will also refresh the session once to sync
+     * the updated params to CallForge (so server-side events can use them).
      */
     setParams(params: Record<string, string>): Promise<void>;
     /**
@@ -121,10 +124,20 @@ declare class CallForge {
      */
     getQueuedParams(): TrackingParams;
     /**
-     * Capture the GA4 client ID using gtag callback.
-     * Only runs if ga4MeasurementId is configured.
+     * Capture the GA4 client ID.
+     *
+     * Prefer `_ga` cookie parsing (works even when gtag is not loaded yet).
+     * If ga4MeasurementId is configured and gtag is available, use gtag as a fallback.
      */
     private captureGA4ClientId;
+    private startGA4ClientIdPolling;
+    /**
+     * Extract GA4 client_id from the `_ga` cookie.
+     *
+     * Example cookie value: `GA1.1.1234567890.1234567890`
+     * Returns: `1234567890.1234567890`
+     */
+    private getGA4ClientIdFromCookie;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -132,6 +145,7 @@ declare class CallForge {
     private saveToCache;
     private formatSession;
     private formatApiResponse;
+    private syncParamsToCallForgeIfPossible;
     private buildUrl;
 }
 

package/dist/index.js

@@ -155,6 +155,7 @@ var CallForge = class _CallForge {
     };
     this.cache = new TrackingCache(config.categoryId, config.siteKey);
     this.captureGA4ClientId();
+    this.startGA4ClientIdPolling();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -209,10 +210,28 @@ var CallForge = class _CallForge {
     });
   }
   /**
-   * Set custom tracking parameters for the next session fetch.
+   * Set custom tracking parameters for attribution.
+   *
+   * When possible, the client will also refresh the session once to sync
+   * the updated params to CallForge (so server-side events can use them).
    */
   async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
+    const sync = async () => {
+      try {
+        await this.syncParamsToCallForgeIfPossible();
+      } catch (e) {
+      }
+    };
+    if (this.sessionPromise) {
+      try {
+        await this.sessionPromise;
+      } catch (e) {
+      }
+      await sync();
+    } else {
+      await sync();
+    }
   }
   /**
    * Get the currently queued custom params.
@@ -221,25 +240,66 @@ var CallForge = class _CallForge {
     return __spreadValues({}, this.customParams);
   }
   /**
-   * Capture the GA4 client ID using gtag callback.
-   * Only runs if ga4MeasurementId is configured.
+   * Capture the GA4 client ID.
+   *
+   * Prefer `_ga` cookie parsing (works even when gtag is not loaded yet).
+   * If ga4MeasurementId is configured and gtag is available, use gtag as a fallback.
    */
   captureGA4ClientId() {
-    if (!this.config.ga4MeasurementId) {
+    if (this.customParams.ga4ClientId) {
       return;
     }
-    if (typeof window === "undefined" || !window.gtag) {
+    const fromCookie = this.getGA4ClientIdFromCookie();
+    if (fromCookie) {
+      this.setParams({ ga4ClientId: fromCookie });
       return;
     }
+    if (!this.config.ga4MeasurementId) return;
+    if (typeof window === "undefined" || !window.gtag) return;
     window.gtag("get", this.config.ga4MeasurementId, "client_id", (clientId) => {
       if (clientId) {
         this.setParams({ ga4ClientId: clientId });
       }
     });
   }
+  startGA4ClientIdPolling() {
+    if (typeof window === "undefined") return;
+    if (this.customParams.ga4ClientId) return;
+    const MAX_ATTEMPTS = 20;
+    const INTERVAL_MS = 250;
+    let attempts = 0;
+    const poll = () => {
+      if (this.customParams.ga4ClientId) return;
+      this.captureGA4ClientId();
+      attempts += 1;
+      if (this.customParams.ga4ClientId) return;
+      if (attempts >= MAX_ATTEMPTS) return;
+      window.setTimeout(poll, INTERVAL_MS);
+    };
+    window.setTimeout(poll, INTERVAL_MS);
+  }
+  /**
+   * Extract GA4 client_id from the `_ga` cookie.
+   *
+   * Example cookie value: `GA1.1.1234567890.1234567890`
+   * Returns: `1234567890.1234567890`
+   */
+  getGA4ClientIdFromCookie() {
+    if (typeof document === "undefined") return null;
+    const match = document.cookie.match(/(?:^|;\s*)_ga=([^;]+)/);
+    if (!match) return null;
+    const cookieValue = decodeURIComponent(match[1] || "");
+    const parts = cookieValue.split(".");
+    if (parts.length < 2) return null;
+    const partA = parts[parts.length - 2];
+    const partB = parts[parts.length - 1];
+    if (!/^\d+$/.test(partA) || !/^\d+$/.test(partB)) return null;
+    return `${partA}.${partB}`;
+  }
   async fetchSession() {
     var _a;
     const locationId = this.getLocationId();
+    this.captureGA4ClientId();
     if (typeof window !== "undefined" && window.__cfTracking) {
       try {
         const data2 = await window.__cfTracking;
@@ -254,6 +314,13 @@ var CallForge = class _CallForge {
     }
     const cached = this.cache.get(locationId);
     if (cached) {
+      const autoParams2 = this.getAutoParams();
+      const params2 = __spreadValues(__spreadValues(__spreadValues({}, autoParams2), cached.params), this.customParams);
+      if (params2.ga4ClientId && cached.params.ga4ClientId !== params2.ga4ClientId) {
+        const data2 = await this.fetchFromApi(locationId, cached.sessionToken, params2);
+        this.saveToCache(locationId, data2, params2);
+        return this.formatApiResponse(data2);
+      }
       return this.formatSession(cached);
     }
     const autoParams = this.getAutoParams();
@@ -327,6 +394,16 @@ var CallForge = class _CallForge {
       location: data.location
     };
   }
+  async syncParamsToCallForgeIfPossible() {
+    const locationId = this.getLocationId();
+    const sessionToken = this.cache.getSessionToken(locationId);
+    if (!sessionToken) return;
+    const autoParams = this.getAutoParams();
+    const cachedParams = this.cache.getParams();
+    const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
+    const data = await this.fetchFromApi(locationId, sessionToken, params);
+    this.saveToCache(locationId, data, params);
+  }
   buildUrl(locationId, sessionToken, params) {
     const { categoryId, endpoint } = this.config;
     const queryParams = {
@@ -371,6 +448,8 @@ var u=new URLSearchParams(location.search);
 var loc=u.get('loc_physical_ms');
 var ap=['gclid','gbraid','wbraid','msclkid','fbclid','gad_campaignid','gad_source'];
 var p={};
+var m=document.cookie.match(/(?:^|;\\s*)_ga=([^;]+)/);
+if(m){try{var g=decodeURIComponent(m[1]||'');var s=g.split('.');if(s.length>=2){var a=s[s.length-2],b=s[s.length-1];if(/^\\d+$/.test(a)&&/^\\d+$/.test(b))p.ga4ClientId=a+'.'+b}}catch(e){}}
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var site='${config.siteKey || ""}'||location.hostname||'unknown-site';
 var key='cf_tracking_v1_'+site+'_${categoryId}';

package/dist/index.mjs

@@ -131,6 +131,7 @@ var CallForge = class _CallForge {
     };
     this.cache = new TrackingCache(config.categoryId, config.siteKey);
     this.captureGA4ClientId();
+    this.startGA4ClientIdPolling();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -185,10 +186,28 @@ var CallForge = class _CallForge {
     });
   }
   /**
-   * Set custom tracking parameters for the next session fetch.
+   * Set custom tracking parameters for attribution.
+   *
+   * When possible, the client will also refresh the session once to sync
+   * the updated params to CallForge (so server-side events can use them).
    */
   async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
+    const sync = async () => {
+      try {
+        await this.syncParamsToCallForgeIfPossible();
+      } catch (e) {
+      }
+    };
+    if (this.sessionPromise) {
+      try {
+        await this.sessionPromise;
+      } catch (e) {
+      }
+      await sync();
+    } else {
+      await sync();
+    }
   }
   /**
    * Get the currently queued custom params.
@@ -197,25 +216,66 @@ var CallForge = class _CallForge {
     return __spreadValues({}, this.customParams);
   }
   /**
-   * Capture the GA4 client ID using gtag callback.
-   * Only runs if ga4MeasurementId is configured.
+   * Capture the GA4 client ID.
+   *
+   * Prefer `_ga` cookie parsing (works even when gtag is not loaded yet).
+   * If ga4MeasurementId is configured and gtag is available, use gtag as a fallback.
    */
   captureGA4ClientId() {
-    if (!this.config.ga4MeasurementId) {
+    if (this.customParams.ga4ClientId) {
       return;
     }
-    if (typeof window === "undefined" || !window.gtag) {
+    const fromCookie = this.getGA4ClientIdFromCookie();
+    if (fromCookie) {
+      this.setParams({ ga4ClientId: fromCookie });
       return;
     }
+    if (!this.config.ga4MeasurementId) return;
+    if (typeof window === "undefined" || !window.gtag) return;
     window.gtag("get", this.config.ga4MeasurementId, "client_id", (clientId) => {
       if (clientId) {
         this.setParams({ ga4ClientId: clientId });
       }
     });
   }
+  startGA4ClientIdPolling() {
+    if (typeof window === "undefined") return;
+    if (this.customParams.ga4ClientId) return;
+    const MAX_ATTEMPTS = 20;
+    const INTERVAL_MS = 250;
+    let attempts = 0;
+    const poll = () => {
+      if (this.customParams.ga4ClientId) return;
+      this.captureGA4ClientId();
+      attempts += 1;
+      if (this.customParams.ga4ClientId) return;
+      if (attempts >= MAX_ATTEMPTS) return;
+      window.setTimeout(poll, INTERVAL_MS);
+    };
+    window.setTimeout(poll, INTERVAL_MS);
+  }
+  /**
+   * Extract GA4 client_id from the `_ga` cookie.
+   *
+   * Example cookie value: `GA1.1.1234567890.1234567890`
+   * Returns: `1234567890.1234567890`
+   */
+  getGA4ClientIdFromCookie() {
+    if (typeof document === "undefined") return null;
+    const match = document.cookie.match(/(?:^|;\s*)_ga=([^;]+)/);
+    if (!match) return null;
+    const cookieValue = decodeURIComponent(match[1] || "");
+    const parts = cookieValue.split(".");
+    if (parts.length < 2) return null;
+    const partA = parts[parts.length - 2];
+    const partB = parts[parts.length - 1];
+    if (!/^\d+$/.test(partA) || !/^\d+$/.test(partB)) return null;
+    return `${partA}.${partB}`;
+  }
   async fetchSession() {
     var _a;
     const locationId = this.getLocationId();
+    this.captureGA4ClientId();
     if (typeof window !== "undefined" && window.__cfTracking) {
       try {
         const data2 = await window.__cfTracking;
@@ -230,6 +290,13 @@ var CallForge = class _CallForge {
     }
     const cached = this.cache.get(locationId);
     if (cached) {
+      const autoParams2 = this.getAutoParams();
+      const params2 = __spreadValues(__spreadValues(__spreadValues({}, autoParams2), cached.params), this.customParams);
+      if (params2.ga4ClientId && cached.params.ga4ClientId !== params2.ga4ClientId) {
+        const data2 = await this.fetchFromApi(locationId, cached.sessionToken, params2);
+        this.saveToCache(locationId, data2, params2);
+        return this.formatApiResponse(data2);
+      }
       return this.formatSession(cached);
     }
     const autoParams = this.getAutoParams();
@@ -303,6 +370,16 @@ var CallForge = class _CallForge {
       location: data.location
     };
   }
+  async syncParamsToCallForgeIfPossible() {
+    const locationId = this.getLocationId();
+    const sessionToken = this.cache.getSessionToken(locationId);
+    if (!sessionToken) return;
+    const autoParams = this.getAutoParams();
+    const cachedParams = this.cache.getParams();
+    const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
+    const data = await this.fetchFromApi(locationId, sessionToken, params);
+    this.saveToCache(locationId, data, params);
+  }
   buildUrl(locationId, sessionToken, params) {
     const { categoryId, endpoint } = this.config;
     const queryParams = {
@@ -347,6 +424,8 @@ var u=new URLSearchParams(location.search);
 var loc=u.get('loc_physical_ms');
 var ap=['gclid','gbraid','wbraid','msclkid','fbclid','gad_campaignid','gad_source'];
 var p={};
+var m=document.cookie.match(/(?:^|;\\s*)_ga=([^;]+)/);
+if(m){try{var g=decodeURIComponent(m[1]||'');var s=g.split('.');if(s.length>=2){var a=s[s.length-2],b=s[s.length-1];if(/^\\d+$/.test(a)&&/^\\d+$/.test(b))p.ga4ClientId=a+'.'+b}}catch(e){}}
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var site='${config.siteKey || ""}'||location.hostname||'unknown-site';
 var key='cf_tracking_v1_'+site+'_${categoryId}';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callforge/tracking-client",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -17,17 +17,17 @@
   "files": [
     "dist"
   ],
+  "devDependencies": {
+    "jsdom": "^27.4.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.0",
+    "@callforge/tsconfig": "0.0.0"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "clean": "rm -rf dist",
     "test": "vitest run",
     "test:watch": "vitest"
-  },
-  "devDependencies": {
-    "@callforge/tsconfig": "workspace:*",
-    "jsdom": "^27.4.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^1.6.0"
   }
-}
+}