@callforge/tracking-client 0.4.0 → 0.4.2

package/README.md

@@ -2,7 +2,7 @@
 
 Lightweight client library for the CallForge tracking API. Handles location-aware phone number assignment with aggressive caching and preload optimization.
 
-**v0.4.0** - Added `ga4MeasurementId` config option for cleaner gtag callback instead of cookie polling.
+**v0.4.1** - Simplified GA4 capture: uses gtag callback when `ga4MeasurementId` configured, no polling fallback.
 
 ## Installation
 
@@ -53,33 +53,26 @@ client.onReady((session) => {
 });
 ```
 
-### 3. GA4 Integration (automatic)
+### 3. GA4 Integration
 
-The client automatically captures the GA4 client ID and associates it with the tracking session. This enables CallForge to send call events (phone call, conversion, billable conversion) to your Google Analytics 4 property.
-
-**Requirements:**
-1. Google Analytics 4 must be installed on your site
-2. Configure GA4 credentials in CallForge dashboard (Categories → Edit → GA4 tab)
-
-**Recommended: Provide Measurement ID for callback-based capture:**
+To enable GA4 call event tracking, provide your GA4 Measurement ID:
 
 ```typescript
 const client = CallForge.init({
   categoryId: 'your-category-id',
-  ga4MeasurementId: 'G-XXXXXXXXXX',  // Enables gtag('get') callback
+  ga4MeasurementId: 'G-XXXXXXXXXX',  // Required for GA4 integration
 });
 ```
 
-When `ga4MeasurementId` is provided, the client uses the official `gtag('get')` API callback to retrieve the client ID. This is cleaner and more reliable than cookie polling.
+**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 (Categories → Edit → GA4 tab)
 
 **How it works:**
-1. **If `ga4MeasurementId` is provided AND `window.gtag` exists:**
-   - Uses `gtag('get', measurementId, 'client_id', callback)` to get the client ID
-   - No polling needed - callback fires when GA4 is ready
-2. **Otherwise (fallback):**
-   - Checks for the `_ga` cookie immediately
-   - If not found, polls every 500ms for up to 10 seconds
-   - Handles async GA4 script loading
+- Uses `gtag('get', measurementId, 'client_id', callback)` to capture the GA4 client ID
+- Callback fires when GA4 is ready - no polling needed
+- Client ID is automatically sent to CallForge for call event attribution
 
 **Manual override:** If you need to pass a custom GA4 client ID:
 
@@ -89,14 +82,6 @@ client.setParams({
 });
 ```
 
-**Extract GA4 client ID yourself:**
-
-```typescript
-import { getGA4ClientId } from '@callforge/tracking-client';
-
-const clientId = getGA4ClientId();  // "1234567890.1234567890" or null
-```
-
 ### 4. Track conversion parameters (optional)
 
 The client automatically captures ad platform click IDs from the URL:
@@ -198,35 +183,21 @@ const html = getPreloadSnippet({
 });
 ```
 
-### `getGA4ClientId()`
-
-Extract the GA4 client ID from the `_ga` cookie.
-
-```typescript
-import { getGA4ClientId } from '@callforge/tracking-client';
-
-const clientId = getGA4ClientId();
-// Returns: "1234567890.1234567890" or null if cookie not found
-```
-
-**Cookie format:** `GA1.1.1234567890.1234567890`
-
-The client ID is the last two dot-separated segments (timestamp.random).
-
 ## Tracking Parameters
 
 ### Auto-Capture
 
-The client automatically extracts these parameters:
+The client automatically extracts these parameters from the URL:
 
-| Parameter | Source | Capture Method |
-|-----------|--------|----------------|
-| `gclid` | Google Ads Click ID | URL query param |
-| `gbraid` | Google app-to-web (iOS 14+) | URL query param |
-| `wbraid` | Google web-to-app | URL query param |
-| `msclkid` | Microsoft/Bing Ads | URL query param |
-| `fbclid` | Facebook/Meta Ads | URL query param |
-| `ga4ClientId` | Google Analytics 4 | `_ga` cookie (polled) |
+| Parameter | Source |
+|-----------|--------|
+| `gclid` | Google Ads Click ID |
+| `gbraid` | Google app-to-web (iOS 14+) |
+| `wbraid` | Google web-to-app |
+| `msclkid` | Microsoft/Bing Ads |
+| `fbclid` | Facebook/Meta Ads |
+
+**Note:** `ga4ClientId` is captured via `gtag('get')` callback when `ga4MeasurementId` is configured.
 
 ### Persistence
 
@@ -278,8 +249,6 @@ import type {
   TrackingParams,
   ReadyCallback,
 } from '@callforge/tracking-client';
-
-import { getGA4ClientId } from '@callforge/tracking-client';
 ```
 
 ### TrackingParams
@@ -291,7 +260,7 @@ interface TrackingParams {
   wbraid?: string;      // Google web-to-app
   msclkid?: string;     // Microsoft/Bing Ads
   fbclid?: string;      // Facebook/Meta Ads
-  ga4ClientId?: string; // Google Analytics 4 Client ID (auto-captured from _ga cookie)
+  ga4ClientId?: string; // Google Analytics 4 Client ID (auto-captured via gtag callback)
   [key: string]: string | undefined;  // Custom params
 }
 ```

package/dist/index.d.mts

@@ -75,19 +75,11 @@ declare global {
     }
 }
 
-/**
- * Extract GA4 client_id from the _ga cookie.
- * Cookie format: GA1.1.1234567890.1234567890
- * Client ID is the last two segments: 1234567890.1234567890
- */
-declare function getGA4ClientId(): string | null;
 declare class CallForge {
     private readonly config;
     private readonly cache;
     private sessionPromise;
     private customParams;
-    private ga4PollInterval;
-    private ga4PollTimeout;
     private sessionId;
     private sessionCreated;
     private constructor();
@@ -117,18 +109,10 @@ declare class CallForge {
     getQueuedParams(): TrackingParams;
     private patchSession;
     /**
-     * Start capturing the GA4 client ID.
-     * If ga4MeasurementId is configured, uses gtag('get') callback.
-     * Otherwise falls back to polling the _ga cookie.
-     */
-    startGA4ClientIdCapture(): void;
-    /**
-     * Start polling for the GA4 _ga cookie.
-     * If found immediately, calls setParams right away.
-     * Otherwise polls every 500ms for up to 10 seconds.
+     * Capture the GA4 client ID using gtag callback.
+     * Only runs if ga4MeasurementId is configured.
      */
-    private startGA4CookiePolling;
-    private stopGA4CookiePolling;
+    private captureGA4ClientId;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -156,4 +140,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getGA4ClientId, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.d.ts

@@ -75,19 +75,11 @@ declare global {
     }
 }
 
-/**
- * Extract GA4 client_id from the _ga cookie.
- * Cookie format: GA1.1.1234567890.1234567890
- * Client ID is the last two segments: 1234567890.1234567890
- */
-declare function getGA4ClientId(): string | null;
 declare class CallForge {
     private readonly config;
     private readonly cache;
     private sessionPromise;
     private customParams;
-    private ga4PollInterval;
-    private ga4PollTimeout;
     private sessionId;
     private sessionCreated;
     private constructor();
@@ -117,18 +109,10 @@ declare class CallForge {
     getQueuedParams(): TrackingParams;
     private patchSession;
     /**
-     * Start capturing the GA4 client ID.
-     * If ga4MeasurementId is configured, uses gtag('get') callback.
-     * Otherwise falls back to polling the _ga cookie.
-     */
-    startGA4ClientIdCapture(): void;
-    /**
-     * Start polling for the GA4 _ga cookie.
-     * If found immediately, calls setParams right away.
-     * Otherwise polls every 500ms for up to 10 seconds.
+     * Capture the GA4 client ID using gtag callback.
+     * Only runs if ga4MeasurementId is configured.
      */
-    private startGA4CookiePolling;
-    private stopGA4CookiePolling;
+    private captureGA4ClientId;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -156,4 +140,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getGA4ClientId, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.js

@@ -35,7 +35,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CallForge: () => CallForge,
-  getGA4ClientId: () => getGA4ClientId,
   getPreloadSnippet: () => getPreloadSnippet
 });
 module.exports = __toCommonJS(index_exports);
@@ -130,19 +129,12 @@ var TrackingCache = class {
 
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
-function getGA4ClientId() {
-  if (typeof document === "undefined") return null;
-  const match = document.cookie.match(/_ga=GA\d+\.\d+\.(.+?)(?:;|$)/);
-  return match ? match[1] : null;
-}
 var FETCH_TIMEOUT_MS = 1e4;
-var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid"];
+var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
 var CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
     this.customParams = {};
-    this.ga4PollInterval = null;
-    this.ga4PollTimeout = null;
     this.sessionId = null;
     this.sessionCreated = false;
     this.config = {
@@ -151,7 +143,7 @@ var CallForge = class _CallForge {
       ga4MeasurementId: config.ga4MeasurementId
     };
     this.cache = new TrackingCache(config.categoryId);
-    this.startGA4ClientIdCapture();
+    this.captureGA4ClientId();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -213,55 +205,21 @@ var CallForge = class _CallForge {
     }
   }
   /**
-   * Start capturing the GA4 client ID.
-   * If ga4MeasurementId is configured, uses gtag('get') callback.
-   * Otherwise falls back to polling the _ga cookie.
+   * Capture the GA4 client ID using gtag callback.
+   * Only runs if ga4MeasurementId is configured.
    */
-  startGA4ClientIdCapture() {
-    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
-      return;
-    }
-    if (this.config.ga4MeasurementId && typeof window !== "undefined" && window.gtag) {
-      window.gtag("get", this.config.ga4MeasurementId, "client_id", (clientId) => {
-        if (clientId) {
-          this.setParams({ ga4ClientId: clientId });
-        }
-      });
+  captureGA4ClientId() {
+    if (!this.config.ga4MeasurementId) {
       return;
     }
-    this.startGA4CookiePolling();
-  }
-  /**
-   * Start polling for the GA4 _ga cookie.
-   * If found immediately, calls setParams right away.
-   * Otherwise polls every 500ms for up to 10 seconds.
-   */
-  startGA4CookiePolling() {
-    const clientId = getGA4ClientId();
-    if (clientId) {
-      this.setParams({ ga4ClientId: clientId });
+    if (typeof window === "undefined" || !window.gtag) {
       return;
     }
-    this.ga4PollInterval = setInterval(() => {
-      const clientId2 = getGA4ClientId();
-      if (clientId2) {
-        this.setParams({ ga4ClientId: clientId2 });
-        this.stopGA4CookiePolling();
+    window.gtag("get", this.config.ga4MeasurementId, "client_id", (clientId) => {
+      if (clientId) {
+        this.setParams({ ga4ClientId: clientId });
       }
-    }, 500);
-    this.ga4PollTimeout = setTimeout(() => {
-      this.stopGA4CookiePolling();
-    }, 1e4);
-  }
-  stopGA4CookiePolling() {
-    if (this.ga4PollInterval) {
-      clearInterval(this.ga4PollInterval);
-      this.ga4PollInterval = null;
-    }
-    if (this.ga4PollTimeout) {
-      clearTimeout(this.ga4PollTimeout);
-      this.ga4PollTimeout = null;
-    }
+    });
   }
   async fetchSession() {
     const locationId = this.getLocationId();
@@ -397,7 +355,7 @@ function getPreloadSnippet(config) {
   const script = `(function(){
 var u=new URLSearchParams(location.search);
 var loc=u.get('loc_physical_ms');
-var ap=['gclid','gbraid','wbraid','msclkid','fbclid'];
+var ap=['gclid','gbraid','wbraid','msclkid','fbclid','gad_campaignid','gad_source'];
 var p={};
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var key='${cacheKey}';
@@ -422,6 +380,5 @@ window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){return r.js
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CallForge,
-  getGA4ClientId,
   getPreloadSnippet
 });

package/dist/index.mjs

@@ -105,19 +105,12 @@ var TrackingCache = class {
 
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
-function getGA4ClientId() {
-  if (typeof document === "undefined") return null;
-  const match = document.cookie.match(/_ga=GA\d+\.\d+\.(.+?)(?:;|$)/);
-  return match ? match[1] : null;
-}
 var FETCH_TIMEOUT_MS = 1e4;
-var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid"];
+var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
 var CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
     this.customParams = {};
-    this.ga4PollInterval = null;
-    this.ga4PollTimeout = null;
     this.sessionId = null;
     this.sessionCreated = false;
     this.config = {
@@ -126,7 +119,7 @@ var CallForge = class _CallForge {
       ga4MeasurementId: config.ga4MeasurementId
     };
     this.cache = new TrackingCache(config.categoryId);
-    this.startGA4ClientIdCapture();
+    this.captureGA4ClientId();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -188,55 +181,21 @@ var CallForge = class _CallForge {
     }
   }
   /**
-   * Start capturing the GA4 client ID.
-   * If ga4MeasurementId is configured, uses gtag('get') callback.
-   * Otherwise falls back to polling the _ga cookie.
+   * Capture the GA4 client ID using gtag callback.
+   * Only runs if ga4MeasurementId is configured.
    */
-  startGA4ClientIdCapture() {
-    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
-      return;
-    }
-    if (this.config.ga4MeasurementId && typeof window !== "undefined" && window.gtag) {
-      window.gtag("get", this.config.ga4MeasurementId, "client_id", (clientId) => {
-        if (clientId) {
-          this.setParams({ ga4ClientId: clientId });
-        }
-      });
+  captureGA4ClientId() {
+    if (!this.config.ga4MeasurementId) {
       return;
     }
-    this.startGA4CookiePolling();
-  }
-  /**
-   * Start polling for the GA4 _ga cookie.
-   * If found immediately, calls setParams right away.
-   * Otherwise polls every 500ms for up to 10 seconds.
-   */
-  startGA4CookiePolling() {
-    const clientId = getGA4ClientId();
-    if (clientId) {
-      this.setParams({ ga4ClientId: clientId });
+    if (typeof window === "undefined" || !window.gtag) {
       return;
     }
-    this.ga4PollInterval = setInterval(() => {
-      const clientId2 = getGA4ClientId();
-      if (clientId2) {
-        this.setParams({ ga4ClientId: clientId2 });
-        this.stopGA4CookiePolling();
+    window.gtag("get", this.config.ga4MeasurementId, "client_id", (clientId) => {
+      if (clientId) {
+        this.setParams({ ga4ClientId: clientId });
       }
-    }, 500);
-    this.ga4PollTimeout = setTimeout(() => {
-      this.stopGA4CookiePolling();
-    }, 1e4);
-  }
-  stopGA4CookiePolling() {
-    if (this.ga4PollInterval) {
-      clearInterval(this.ga4PollInterval);
-      this.ga4PollInterval = null;
-    }
-    if (this.ga4PollTimeout) {
-      clearTimeout(this.ga4PollTimeout);
-      this.ga4PollTimeout = null;
-    }
+    });
   }
   async fetchSession() {
     const locationId = this.getLocationId();
@@ -372,7 +331,7 @@ function getPreloadSnippet(config) {
   const script = `(function(){
 var u=new URLSearchParams(location.search);
 var loc=u.get('loc_physical_ms');
-var ap=['gclid','gbraid','wbraid','msclkid','fbclid'];
+var ap=['gclid','gbraid','wbraid','msclkid','fbclid','gad_campaignid','gad_source'];
 var p={};
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var key='${cacheKey}';
@@ -396,6 +355,5 @@ window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){return r.js
 }
 export {
   CallForge,
-  getGA4ClientId,
   getPreloadSnippet
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callforge/tracking-client",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",