@callforge/tracking-client 0.3.0 → 0.4.0

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.4.0** - Added `ga4MeasurementId` config option for cleaner gtag callback instead of cookie polling.
+
 ## Installation
 
 ```bash
@@ -51,7 +53,51 @@ client.onReady((session) => {
 });
 ```
 
-### 3. Track conversion parameters (optional)
+### 3. GA4 Integration (automatic)
+
+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:**
+
+```typescript
+const client = CallForge.init({
+  categoryId: 'your-category-id',
+  ga4MeasurementId: 'G-XXXXXXXXXX',  // Enables gtag('get') callback
+});
+```
+
+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.
+
+**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
+
+**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:
 
@@ -82,8 +128,10 @@ Initialize the tracking client.
 
 ```typescript
 interface CallForgeConfig {
-  categoryId: string;    // Required - which number pool to use
-  endpoint?: string;     // Optional - defaults to 'https://tracking.callforge.io'
+  categoryId: string;        // Required - which number pool to use
+  endpoint?: string;         // Optional - defaults to 'https://tracking.callforge.io'
+  ga4MeasurementId?: string; // Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX")
+                             // Enables gtag callback instead of cookie polling
 }
 ```
 
@@ -150,19 +198,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 +278,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

@@ -6,6 +6,8 @@ interface CallForgeConfig {
     categoryId: string;
     /** Optional - API endpoint. Defaults to 'https://tracking.callforge.io' */
     endpoint?: string;
+    /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag callback instead of cookie polling. */
+    ga4MeasurementId?: string;
 }
 /**
  * Location data returned by the tracking API.
@@ -64,14 +66,21 @@ interface ApiResponse {
  */
 type ReadyCallback = (session: TrackingSession) => void;
 /**
- * Global window extension for preload promise.
+ * Global window extension for preload promise and gtag.
  */
 declare global {
     interface Window {
         __cfTracking?: Promise<ApiResponse>;
+        gtag?: (command: 'get', targetId: string, fieldName: string, callback: (value: string) => void) => void;
     }
 }
 
+/**
+ * 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;
@@ -107,12 +116,18 @@ 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.
      */
-    startGA4CookiePolling(): void;
+    private startGA4CookiePolling;
     private stopGA4CookiePolling;
     private fetchSession;
     private getLocationId;
@@ -141,4 +156,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

@@ -6,6 +6,8 @@ interface CallForgeConfig {
     categoryId: string;
     /** Optional - API endpoint. Defaults to 'https://tracking.callforge.io' */
     endpoint?: string;
+    /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag callback instead of cookie polling. */
+    ga4MeasurementId?: string;
 }
 /**
  * Location data returned by the tracking API.
@@ -64,14 +66,21 @@ interface ApiResponse {
  */
 type ReadyCallback = (session: TrackingSession) => void;
 /**
- * Global window extension for preload promise.
+ * Global window extension for preload promise and gtag.
  */
 declare global {
     interface Window {
         __cfTracking?: Promise<ApiResponse>;
+        gtag?: (command: 'get', targetId: string, fieldName: string, callback: (value: string) => void) => void;
     }
 }
 
+/**
+ * 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;
@@ -107,12 +116,18 @@ 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.
      */
-    startGA4CookiePolling(): void;
+    private startGA4CookiePolling;
     private stopGA4CookiePolling;
     private fetchSession;
     private getLocationId;
@@ -141,4 +156,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);
@@ -146,10 +147,11 @@ var CallForge = class _CallForge {
     this.sessionCreated = false;
     this.config = {
       categoryId: config.categoryId,
-      endpoint: config.endpoint || DEFAULT_ENDPOINT
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
+      ga4MeasurementId: config.ga4MeasurementId
     };
     this.cache = new TrackingCache(config.categoryId);
-    this.startGA4CookiePolling();
+    this.startGA4ClientIdCapture();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -210,15 +212,31 @@ var CallForge = class _CallForge {
       console.warn("[CallForge] Failed to patch session:", error);
     }
   }
+  /**
+   * Start capturing the GA4 client ID.
+   * If ga4MeasurementId is configured, uses gtag('get') callback.
+   * Otherwise falls back to polling the _ga cookie.
+   */
+  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 });
+        }
+      });
+      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() {
-    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
-      return;
-    }
     const clientId = getGA4ClientId();
     if (clientId) {
       this.setParams({ ga4ClientId: clientId });
@@ -404,5 +422,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

@@ -122,10 +122,11 @@ var CallForge = class _CallForge {
     this.sessionCreated = false;
     this.config = {
       categoryId: config.categoryId,
-      endpoint: config.endpoint || DEFAULT_ENDPOINT
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
+      ga4MeasurementId: config.ga4MeasurementId
     };
     this.cache = new TrackingCache(config.categoryId);
-    this.startGA4CookiePolling();
+    this.startGA4ClientIdCapture();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -186,15 +187,31 @@ var CallForge = class _CallForge {
       console.warn("[CallForge] Failed to patch session:", error);
     }
   }
+  /**
+   * Start capturing the GA4 client ID.
+   * If ga4MeasurementId is configured, uses gtag('get') callback.
+   * Otherwise falls back to polling the _ga cookie.
+   */
+  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 });
+        }
+      });
+      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() {
-    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
-      return;
-    }
     const clientId = getGA4ClientId();
     if (clientId) {
       this.setParams({ ga4ClientId: clientId });
@@ -379,5 +396,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.3.0",
+  "version": "0.4.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",