@callforge/tracking-client 0.3.1 → 0.4.0

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.3.0** - Added automatic GA4 integration for sending call events to Google Analytics 4.
+**v0.4.0** - Added `ga4MeasurementId` config option for cleaner gtag callback instead of cookie polling.
 
 ## Installation
 
@@ -55,17 +55,31 @@ client.onReady((session) => {
 
 ### 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.
+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:**
-- 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
+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:
 
@@ -114,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
 }
 ```
 

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,11 +66,12 @@ 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;
     }
 }
 
@@ -113,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;

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,11 +66,12 @@ 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;
     }
 }
 
@@ -113,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;

package/dist/index.js

@@ -147,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.
@@ -211,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 });

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 });

package/package.json

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