@callforge/tracking-client 0.3.1 → 0.4.1

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.1** - Simplified GA4 capture: uses gtag callback when `ga4MeasurementId` configured, no polling fallback.
 
 ## Installation
 
@@ -53,19 +53,26 @@ client.onReady((session) => {
 });
 ```
 
-### 3. GA4 Integration (automatic)
+### 3. GA4 Integration
 
-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.
+To enable GA4 call event tracking, provide your GA4 Measurement ID:
+
+```typescript
+const client = CallForge.init({
+  categoryId: 'your-category-id',
+  ga4MeasurementId: 'G-XXXXXXXXXX',  // Required for GA4 integration
+});
+```
 
 **Requirements:**
-1. Google Analytics 4 must be installed on your site
-2. Configure GA4 credentials in CallForge dashboard (Categories → Edit → GA4 tab)
+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:**
-- 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
+- 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:
 
@@ -75,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:
@@ -114,8 +113,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
 }
 ```
 
@@ -182,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
 
@@ -262,8 +249,6 @@ import type {
   TrackingParams,
   ReadyCallback,
 } from '@callforge/tracking-client';
-
-import { getGA4ClientId } from '@callforge/tracking-client';
 ```
 
 ### TrackingParams
@@ -275,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

@@ -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,27 +66,20 @@ 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;
     private sessionPromise;
     private customParams;
-    private ga4PollInterval;
-    private ga4PollTimeout;
     private sessionId;
     private sessionCreated;
     private constructor();
@@ -114,12 +109,10 @@ declare class CallForge {
     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.
+     * Capture the GA4 client ID using gtag callback.
+     * Only runs if ga4MeasurementId is configured.
      */
-    startGA4CookiePolling(): void;
-    private stopGA4CookiePolling;
+    private captureGA4ClientId;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -147,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

@@ -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,27 +66,20 @@ 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;
     private sessionPromise;
     private customParams;
-    private ga4PollInterval;
-    private ga4PollTimeout;
     private sessionId;
     private sessionCreated;
     private constructor();
@@ -114,12 +109,10 @@ declare class CallForge {
     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.
+     * Capture the GA4 client ID using gtag callback.
+     * Only runs if ga4MeasurementId is configured.
      */
-    startGA4CookiePolling(): void;
-    private stopGA4CookiePolling;
+    private captureGA4ClientId;
     private fetchSession;
     private getLocationId;
     private getAutoParams;
@@ -147,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,27 +129,21 @@ 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
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
+      ga4MeasurementId: config.ga4MeasurementId
     };
     this.cache = new TrackingCache(config.categoryId);
-    this.startGA4CookiePolling();
+    this.captureGA4ClientId();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -212,39 +205,21 @@ var CallForge = class _CallForge {
     }
   }
   /**
-   * 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.
    */
-  startGA4CookiePolling() {
-    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
+  captureGA4ClientId() {
+    if (!this.config.ga4MeasurementId) {
       return;
     }
-    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();
@@ -405,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,27 +105,21 @@ 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
+      endpoint: config.endpoint || DEFAULT_ENDPOINT,
+      ga4MeasurementId: config.ga4MeasurementId
     };
     this.cache = new TrackingCache(config.categoryId);
-    this.startGA4CookiePolling();
+    this.captureGA4ClientId();
   }
   /**
    * Initialize the CallForge tracking client.
@@ -187,39 +181,21 @@ var CallForge = class _CallForge {
     }
   }
   /**
-   * 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.
    */
-  startGA4CookiePolling() {
-    if (this.ga4PollInterval !== null || this.ga4PollTimeout !== null) {
+  captureGA4ClientId() {
+    if (!this.config.ga4MeasurementId) {
       return;
     }
-    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();
@@ -379,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.3.1",
+  "version": "0.4.1",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",