@callforge/tracking-client 0.3.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,6 +72,12 @@ 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;
@@ -141,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,6 +72,12 @@ 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;
@@ -141,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);
@@ -404,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

@@ -379,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.3.0",
+  "version": "0.3.1",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",