@callforge/tracking-client 0.2.0 → 0.3.1

package/README.md

@@ -2,6 +2,8 @@
 
 Lightweight client library for the CallForge tracking API. Handles location-aware phone number assignment with aggressive caching and preload optimization.
 
+**v0.3.0** - Added automatic GA4 integration for sending call events to Google Analytics 4.
+
 ## Installation
 
 ```bash
@@ -51,7 +53,37 @@ client.onReady((session) => {
 });
 ```
 
-### 3. Track conversion parameters (optional)
+### 3. GA4 Integration (automatic)
+
+The client automatically captures the GA4 client ID from the `_ga` cookie 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)
+
+**How it works:**
+- On initialization, the client checks for the `_ga` cookie
+- If not found immediately (GA4 script may load async), polls every 500ms for up to 10 seconds
+- Once found, extracts the client ID and sends it to CallForge via `setParams()`
+- If session already exists, uses PATCH to update with the GA4 client ID
+
+**Manual override:** If you need to pass a custom GA4 client ID:
+
+```typescript
+client.setParams({
+  ga4ClientId: '1234567890.1234567890',
+});
+```
+
+**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:
 
@@ -150,19 +182,35 @@ 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 from the URL on first visit:
+The client automatically extracts these parameters:
 
-| 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 |
+| 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) |
 
 ### Persistence
 
@@ -214,21 +262,53 @@ import type {
   TrackingParams,
   ReadyCallback,
 } from '@callforge/tracking-client';
+
+import { getGA4ClientId } from '@callforge/tracking-client';
 ```
 
 ### TrackingParams
 
 ```typescript
 interface TrackingParams {
-  gclid?: string;    // Google Ads Click ID
-  gbraid?: string;   // Google app-to-web (iOS 14+)
-  wbraid?: string;   // Google web-to-app
-  msclkid?: string;  // Microsoft/Bing Ads
-  fbclid?: string;   // Facebook/Meta Ads
+  gclid?: string;       // Google Ads Click ID
+  gbraid?: string;      // Google app-to-web (iOS 14+)
+  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)
   [key: string]: string | undefined;  // Custom params
 }
 ```
 
+## GA4 Events
+
+When GA4 is configured for a category, CallForge sends these events to Google Analytics 4 via the Measurement Protocol:
+
+| Event Name | When Sent | Description |
+|------------|-----------|-------------|
+| `phone_call` | Call initiated | A phone call was placed to the tracking number |
+| `call_conversion` | Call qualified | The call met conversion criteria (e.g., duration threshold) |
+| `call_conversion_billable` | Call billable | The call was both qualified AND billable |
+
+**Event Parameters:**
+
+All events include:
+- `session_id` - CallForge session ID
+- `phone_number` - Tracking number dialed
+- `category` - Category slug
+
+`call_conversion` and `call_conversion_billable` also include:
+- `call_duration` - Call duration in seconds
+- `buyer` - Buyer the call was routed to (if applicable)
+
+**Setup:**
+1. In Google Analytics 4, go to Admin → Data Streams → your web stream
+2. Copy the **Measurement ID** (e.g., `G-XXXXXXXXXX`)
+3. Go to Admin → Data Streams → Measurement Protocol API secrets → Create
+4. Copy the **API Secret**
+5. In CallForge dashboard: Categories → Edit category → GA4 tab
+6. Enable GA4, paste Measurement ID and API Secret, save
+
 ## Environment URLs
 
 | Environment | Endpoint |

package/dist/index.d.mts

@@ -72,11 +72,21 @@ 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();
     /**
      * Initialize the CallForge tracking client.
@@ -94,9 +104,22 @@ declare class CallForge {
     onReady(callback: ReadyCallback): void;
     /**
      * Set custom tracking parameters.
-     * Merges with existing params (new values override).
+     * If session already exists, sends PATCH to update.
+     * Otherwise queues params for next session request.
+     */
+    setParams(params: Record<string, string>): Promise<void>;
+    /**
+     * Get the currently queued custom params.
+     */
+    getQueuedParams(): TrackingParams;
+    private patchSession;
+    /**
+     * Start polling for the GA4 _ga cookie.
+     * If found immediately, calls setParams right away.
+     * Otherwise polls every 500ms for up to 10 seconds.
      */
-    setParams(params: Record<string, string>): void;
+    startGA4CookiePolling(): void;
+    private stopGA4CookiePolling;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -124,4 +147,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getGA4ClientId, getPreloadSnippet };

package/dist/index.d.ts

@@ -72,11 +72,21 @@ 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();
     /**
      * Initialize the CallForge tracking client.
@@ -94,9 +104,22 @@ declare class CallForge {
     onReady(callback: ReadyCallback): void;
     /**
      * Set custom tracking parameters.
-     * Merges with existing params (new values override).
+     * If session already exists, sends PATCH to update.
+     * Otherwise queues params for next session request.
+     */
+    setParams(params: Record<string, string>): Promise<void>;
+    /**
+     * Get the currently queued custom params.
+     */
+    getQueuedParams(): TrackingParams;
+    private patchSession;
+    /**
+     * Start polling for the GA4 _ga cookie.
+     * If found immediately, calls setParams right away.
+     * Otherwise polls every 500ms for up to 10 seconds.
      */
-    setParams(params: Record<string, string>): void;
+    startGA4CookiePolling(): void;
+    private stopGA4CookiePolling;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -124,4 +147,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getGA4ClientId, getPreloadSnippet };

package/dist/index.js

@@ -35,6 +35,7 @@ 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);
@@ -129,17 +130,27 @@ 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 CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
     this.customParams = {};
+    this.ga4PollInterval = null;
+    this.ga4PollTimeout = null;
+    this.sessionId = null;
+    this.sessionCreated = false;
     this.config = {
       categoryId: config.categoryId,
       endpoint: config.endpoint || DEFAULT_ENDPOINT
     };
     this.cache = new TrackingCache(config.categoryId);
+    this.startGA4CookiePolling();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -168,16 +179,80 @@ var CallForge = class _CallForge {
   }
   /**
    * Set custom tracking parameters.
-   * Merges with existing params (new values override).
+   * If session already exists, sends PATCH to update.
+   * Otherwise queues params for next session request.
    */
-  setParams(params) {
+  async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
+    if (this.sessionCreated && this.sessionId) {
+      await this.patchSession(params);
+    }
+  }
+  /**
+   * Get the currently queued custom params.
+   */
+  getQueuedParams() {
+    return __spreadValues({}, this.customParams);
+  }
+  async patchSession(params) {
+    try {
+      const response = await fetch(
+        `${this.config.endpoint}/v1/tracking/session/${this.sessionId}`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(params)
+        }
+      );
+      if (!response.ok) {
+        console.warn("[CallForge] Failed to patch session:", response.status);
+      }
+    } catch (error) {
+      console.warn("[CallForge] Failed to patch session:", error);
+    }
+  }
+  /**
+   * Start polling for the GA4 _ga cookie.
+   * If found immediately, calls setParams right away.
+   * Otherwise polls every 500ms for up to 10 seconds.
+   */
+  startGA4CookiePolling() {
+    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
+      return;
+    }
+    const clientId = getGA4ClientId();
+    if (clientId) {
+      this.setParams({ ga4ClientId: clientId });
+      return;
+    }
+    this.ga4PollInterval = setInterval(() => {
+      const clientId2 = getGA4ClientId();
+      if (clientId2) {
+        this.setParams({ ga4ClientId: clientId2 });
+        this.stopGA4CookiePolling();
+      }
+    }, 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();
     if (locationId) {
       const cached = this.cache.get(locationId);
       if (cached) {
+        this.sessionId = cached.sessionId;
+        this.sessionCreated = true;
         return this.formatSession(cached);
       }
     }
@@ -188,15 +263,19 @@ var CallForge = class _CallForge {
       try {
         const data2 = await window.__cfTracking;
         this.saveToCache(locationId, data2, params);
+        this.sessionId = data2.sessionId;
+        this.sessionCreated = true;
         return this.formatApiResponse(data2);
       } catch (e) {
       }
     }
-    const sessionId = locationId ? this.cache.getSessionId(locationId) : null;
-    const data = await this.fetchFromApi(locationId, sessionId, params);
+    const cachedSessionId = locationId ? this.cache.getSessionId(locationId) : null;
+    const data = await this.fetchFromApi(locationId, cachedSessionId, params);
     if (locationId) {
       this.saveToCache(locationId, data, params);
     }
+    this.sessionId = data.sessionId;
+    this.sessionCreated = true;
     return this.formatApiResponse(data);
   }
   getLocationId() {
@@ -326,5 +405,6 @@ 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,17 +105,27 @@ 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 CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
     this.customParams = {};
+    this.ga4PollInterval = null;
+    this.ga4PollTimeout = null;
+    this.sessionId = null;
+    this.sessionCreated = false;
     this.config = {
       categoryId: config.categoryId,
       endpoint: config.endpoint || DEFAULT_ENDPOINT
     };
     this.cache = new TrackingCache(config.categoryId);
+    this.startGA4CookiePolling();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -144,16 +154,80 @@ var CallForge = class _CallForge {
   }
   /**
    * Set custom tracking parameters.
-   * Merges with existing params (new values override).
+   * If session already exists, sends PATCH to update.
+   * Otherwise queues params for next session request.
    */
-  setParams(params) {
+  async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
+    if (this.sessionCreated && this.sessionId) {
+      await this.patchSession(params);
+    }
+  }
+  /**
+   * Get the currently queued custom params.
+   */
+  getQueuedParams() {
+    return __spreadValues({}, this.customParams);
+  }
+  async patchSession(params) {
+    try {
+      const response = await fetch(
+        `${this.config.endpoint}/v1/tracking/session/${this.sessionId}`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(params)
+        }
+      );
+      if (!response.ok) {
+        console.warn("[CallForge] Failed to patch session:", response.status);
+      }
+    } catch (error) {
+      console.warn("[CallForge] Failed to patch session:", error);
+    }
+  }
+  /**
+   * Start polling for the GA4 _ga cookie.
+   * If found immediately, calls setParams right away.
+   * Otherwise polls every 500ms for up to 10 seconds.
+   */
+  startGA4CookiePolling() {
+    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
+      return;
+    }
+    const clientId = getGA4ClientId();
+    if (clientId) {
+      this.setParams({ ga4ClientId: clientId });
+      return;
+    }
+    this.ga4PollInterval = setInterval(() => {
+      const clientId2 = getGA4ClientId();
+      if (clientId2) {
+        this.setParams({ ga4ClientId: clientId2 });
+        this.stopGA4CookiePolling();
+      }
+    }, 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();
     if (locationId) {
       const cached = this.cache.get(locationId);
       if (cached) {
+        this.sessionId = cached.sessionId;
+        this.sessionCreated = true;
         return this.formatSession(cached);
       }
     }
@@ -164,15 +238,19 @@ var CallForge = class _CallForge {
       try {
         const data2 = await window.__cfTracking;
         this.saveToCache(locationId, data2, params);
+        this.sessionId = data2.sessionId;
+        this.sessionCreated = true;
         return this.formatApiResponse(data2);
       } catch (e) {
       }
     }
-    const sessionId = locationId ? this.cache.getSessionId(locationId) : null;
-    const data = await this.fetchFromApi(locationId, sessionId, params);
+    const cachedSessionId = locationId ? this.cache.getSessionId(locationId) : null;
+    const data = await this.fetchFromApi(locationId, cachedSessionId, params);
     if (locationId) {
       this.saveToCache(locationId, data, params);
     }
+    this.sessionId = data.sessionId;
+    this.sessionCreated = true;
     return this.formatApiResponse(data);
   }
   getLocationId() {
@@ -301,5 +379,6 @@ 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.2.0",
+  "version": "0.3.1",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,17 +14,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"
   }
-}
+}