@callforge/tracking-client 0.0.1 → 0.1.0

package/README.md

@@ -51,6 +51,29 @@ client.onReady((session) => {
 });
 ```
 
+### 3. Track conversion parameters (optional)
+
+The client automatically captures ad platform click IDs from the URL:
+
+- `gclid` - Google Ads
+- `gbraid` - Google app-to-web (iOS 14+)
+- `wbraid` - Google web-to-app
+- `msclkid` - Microsoft/Bing Ads
+- `fbclid` - Facebook/Meta Ads
+
+You can also add custom parameters:
+
+```typescript
+// Add custom tracking parameters
+client.setParams({
+  customerId: '456',
+  landingPage: 'pricing',
+});
+
+// Parameters are automatically sent with every API request
+const session = await client.getSession();
+```
+
 ## API Reference
 
 ### `CallForge.init(config)`
@@ -96,6 +119,24 @@ client.onReady((session) => {
 });
 ```
 
+### `client.setParams(params)`
+
+Set custom tracking parameters for conversion attribution.
+
+```typescript
+client.setParams({
+  customerId: '456',
+  landingPage: 'pricing',
+  campaign: 'summer-sale',
+});
+```
+
+**Behavior:**
+- Merges with existing params (later calls override earlier values)
+- Parameters are sent with every `getSession()` API request
+- Persisted in localStorage alongside session data
+- Auto-captured params (gclid, etc.) are included automatically
+
 ### `getPreloadSnippet(config)`
 
 Generate HTML snippet for preloading tracking data.
@@ -109,6 +150,35 @@ const html = getPreloadSnippet({
 });
 ```
 
+## Tracking Parameters
+
+### Auto-Capture
+
+The client automatically extracts these parameters from the URL on first visit:
+
+| 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 |
+
+### Persistence
+
+- Parameters are stored in localStorage alongside the session
+- On subsequent visits, cached params are used (URL may no longer have them)
+- Custom params via `setParams()` merge with auto-captured params
+- Later values override earlier ones (custom > cached > auto-captured)
+
+### API Request Format
+
+Parameters are sent as sorted query string for cache consistency:
+
+```
+/v1/tracking/session?categoryId=cat-123&fbclid=456&gclid=abc&loc_physical_ms=1014221
+```
+
 ## Caching Behavior
 
 - **Cache key:** `loc_physical_ms` parameter from URL
@@ -141,10 +211,24 @@ import type {
   CallForgeConfig,
   TrackingSession,
   TrackingLocation,
+  TrackingParams,
   ReadyCallback,
 } 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
+  [key: string]: string | undefined;  // Custom params
+}
+```
+
 ## Environment URLs
 
 | Environment | Endpoint |

package/dist/index.d.mts

@@ -18,6 +18,23 @@ interface TrackingLocation {
     /** State abbreviation (e.g., "GA") */
     stateCode: string;
 }
+/**
+ * Tracking parameters for attribution (auto-captured + custom).
+ */
+interface TrackingParams {
+    /** Google Ads Click ID */
+    gclid?: string;
+    /** Google app-to-web (iOS 14+) */
+    gbraid?: string;
+    /** Google web-to-app */
+    wbraid?: string;
+    /** Microsoft/Bing Ads Click ID */
+    msclkid?: string;
+    /** Facebook/Meta Ads Click ID */
+    fbclid?: string;
+    /** Custom parameters */
+    [key: string]: string | undefined;
+}
 /**
  * Session data returned by getSession().
  */
@@ -59,6 +76,7 @@ declare class CallForge {
     private readonly config;
     private readonly cache;
     private sessionPromise;
+    private customParams;
     private constructor();
     /**
      * Initialize the CallForge tracking client.
@@ -74,12 +92,19 @@ declare class CallForge {
      * Callback is called once session data is available.
      */
     onReady(callback: ReadyCallback): void;
+    /**
+     * Set custom tracking parameters.
+     * Merges with existing params (new values override).
+     */
+    setParams(params: Record<string, string>): void;
     private fetchSession;
     private getLocationId;
+    private getAutoParams;
     private fetchFromApi;
     private saveToCache;
     private formatSession;
     private formatApiResponse;
+    private buildUrl;
 }
 
 /**
@@ -99,4 +124,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.d.ts

@@ -18,6 +18,23 @@ interface TrackingLocation {
     /** State abbreviation (e.g., "GA") */
     stateCode: string;
 }
+/**
+ * Tracking parameters for attribution (auto-captured + custom).
+ */
+interface TrackingParams {
+    /** Google Ads Click ID */
+    gclid?: string;
+    /** Google app-to-web (iOS 14+) */
+    gbraid?: string;
+    /** Google web-to-app */
+    wbraid?: string;
+    /** Microsoft/Bing Ads Click ID */
+    msclkid?: string;
+    /** Facebook/Meta Ads Click ID */
+    fbclid?: string;
+    /** Custom parameters */
+    [key: string]: string | undefined;
+}
 /**
  * Session data returned by getSession().
  */
@@ -59,6 +76,7 @@ declare class CallForge {
     private readonly config;
     private readonly cache;
     private sessionPromise;
+    private customParams;
     private constructor();
     /**
      * Initialize the CallForge tracking client.
@@ -74,12 +92,19 @@ declare class CallForge {
      * Callback is called once session data is available.
      */
     onReady(callback: ReadyCallback): void;
+    /**
+     * Set custom tracking parameters.
+     * Merges with existing params (new values override).
+     */
+    setParams(params: Record<string, string>): void;
     private fetchSession;
     private getLocationId;
+    private getAutoParams;
     private fetchFromApi;
     private saveToCache;
     private formatSession;
     private formatApiResponse;
+    private buildUrl;
 }
 
 /**
@@ -99,4 +124,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.js

@@ -2,7 +2,21 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -64,6 +78,15 @@ var TrackingCache = class {
     if (cached.locId !== locationId) return null;
     return cached.sessionId;
   }
+  /**
+   * Get cached params (for merging with new params).
+   * Returns empty object if no cache or no params.
+   */
+  getParams() {
+    var _a;
+    const cached = this.read();
+    return (_a = cached == null ? void 0 : cached.params) != null ? _a : {};
+  }
   /**
    * Store session data in cache.
    */
@@ -107,9 +130,11 @@ var TrackingCache = class {
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 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.config = {
       categoryId: config.categoryId,
       endpoint: config.endpoint || DEFAULT_ENDPOINT
@@ -141,6 +166,13 @@ var CallForge = class _CallForge {
     this.getSession().then(callback).catch(() => {
     });
   }
+  /**
+   * Set custom tracking parameters.
+   * Merges with existing params (new values override).
+   */
+  setParams(params) {
+    this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
+  }
   async fetchSession() {
     const locationId = this.getLocationId();
     if (!locationId) {
@@ -150,17 +182,20 @@ var CallForge = class _CallForge {
     if (cached) {
       return this.formatSession(cached);
     }
+    const autoParams = this.getAutoParams();
+    const cachedParams = this.cache.getParams();
+    const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
     if (typeof window !== "undefined" && window.__cfTracking) {
       try {
         const data2 = await window.__cfTracking;
-        this.saveToCache(locationId, data2);
+        this.saveToCache(locationId, data2, params);
         return this.formatApiResponse(data2);
       } catch (e) {
       }
     }
     const sessionId = this.cache.getSessionId(locationId);
-    const data = await this.fetchFromApi(locationId, sessionId);
-    this.saveToCache(locationId, data);
+    const data = await this.fetchFromApi(locationId, sessionId, params);
+    this.saveToCache(locationId, data, params);
     return this.formatApiResponse(data);
   }
   getLocationId() {
@@ -168,12 +203,20 @@ var CallForge = class _CallForge {
     const params = new URLSearchParams(window.location.search);
     return params.get("loc_physical_ms");
   }
-  async fetchFromApi(locationId, sessionId) {
-    const { categoryId, endpoint } = this.config;
-    let url = `${endpoint}/v1/tracking/session?categoryId=${categoryId}&loc_physical_ms=${locationId}`;
-    if (sessionId) {
-      url += `&sessionId=${sessionId}`;
+  getAutoParams() {
+    if (typeof window === "undefined") return {};
+    const urlParams = new URLSearchParams(window.location.search);
+    const params = {};
+    for (const key of AUTO_PARAMS) {
+      const value = urlParams.get(key);
+      if (value) {
+        params[key] = value;
+      }
     }
+    return params;
+  }
+  async fetchFromApi(locationId, sessionId, params) {
+    const url = this.buildUrl(locationId, sessionId, params);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
@@ -189,13 +232,14 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
-  saveToCache(locationId, data) {
+  saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId,
       sessionId: data.sessionId,
       phoneNumber: data.phoneNumber,
       location: data.location,
-      expiresAt: data.expiresAt
+      expiresAt: data.expiresAt,
+      params
     };
     this.cache.set(cached);
   }
@@ -213,6 +257,24 @@ var CallForge = class _CallForge {
       location: data.location
     };
   }
+  buildUrl(locationId, sessionId, params) {
+    const { categoryId, endpoint } = this.config;
+    const queryParams = {
+      categoryId,
+      loc_physical_ms: locationId
+    };
+    if (sessionId) {
+      queryParams.sessionId = sessionId;
+    }
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) {
+        queryParams[key] = value;
+      }
+    }
+    const sorted = Object.keys(queryParams).sort();
+    const qs = sorted.map((k) => `${k}=${encodeURIComponent(queryParams[k])}`).join("&");
+    return `${endpoint}/v1/tracking/session?${qs}`;
+  }
 };
 
 // src/preload.ts
@@ -234,17 +296,25 @@ function getPreloadSnippet(config) {
   }
   const cacheKey = `cf_tracking_${categoryId}`;
   const script = `(function(){
-var loc=new URLSearchParams(location.search).get('loc_physical_ms');
+var u=new URLSearchParams(location.search);
+var loc=u.get('loc_physical_ms');
 if(!loc)return;
+var ap=['gclid','gbraid','wbraid','msclkid','fbclid'];
+var p={};
+for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var key='${cacheKey}';
 try{
 var c=JSON.parse(localStorage.getItem(key));
-if(c&&c.locId===loc&&c.expiresAt>Date.now()+30000){window.__cfTracking=Promise.resolve(c);return}
+if(c&&c.locId===loc&&c.expiresAt>Date.now()+30000){c.params=Object.assign({},c.params,p);window.__cfTracking=Promise.resolve(c);return}
 var sid=(c&&c.locId===loc)?c.sessionId:null;
+var cp=c&&c.params||{};
+p=Object.assign({},p,cp);
 }catch(e){}
 var url='${endpoint}/v1/tracking/session?categoryId=${categoryId}&loc_physical_ms='+loc;
 if(sid)url+='&sessionId='+sid;
-window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){return r.json()});
+var ks=Object.keys(p).sort();
+for(var j=0;j<ks.length;j++)url+='&'+ks[j]+'='+encodeURIComponent(p[ks[j]]);
+window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){return r.json()}).then(function(d){d.params=p;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionId:d.sessionId,phoneNumber:d.phoneNumber,location:d.location,expiresAt:d.expiresAt,params:p}))}catch(e){}return d});
 })();`.replace(/\n/g, "");
   return `<link rel="preconnect" href="${endpoint}">
 <script>${script}</script>`;

package/dist/index.mjs

@@ -1,3 +1,20 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+
 // src/cache.ts
 var EXPIRY_BUFFER_MS = 3e4;
 var TrackingCache = class {
@@ -37,6 +54,15 @@ var TrackingCache = class {
     if (cached.locId !== locationId) return null;
     return cached.sessionId;
   }
+  /**
+   * Get cached params (for merging with new params).
+   * Returns empty object if no cache or no params.
+   */
+  getParams() {
+    var _a;
+    const cached = this.read();
+    return (_a = cached == null ? void 0 : cached.params) != null ? _a : {};
+  }
   /**
    * Store session data in cache.
    */
@@ -80,9 +106,11 @@ var TrackingCache = class {
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 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.config = {
       categoryId: config.categoryId,
       endpoint: config.endpoint || DEFAULT_ENDPOINT
@@ -114,6 +142,13 @@ var CallForge = class _CallForge {
     this.getSession().then(callback).catch(() => {
     });
   }
+  /**
+   * Set custom tracking parameters.
+   * Merges with existing params (new values override).
+   */
+  setParams(params) {
+    this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
+  }
   async fetchSession() {
     const locationId = this.getLocationId();
     if (!locationId) {
@@ -123,17 +158,20 @@ var CallForge = class _CallForge {
     if (cached) {
       return this.formatSession(cached);
     }
+    const autoParams = this.getAutoParams();
+    const cachedParams = this.cache.getParams();
+    const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
     if (typeof window !== "undefined" && window.__cfTracking) {
       try {
         const data2 = await window.__cfTracking;
-        this.saveToCache(locationId, data2);
+        this.saveToCache(locationId, data2, params);
         return this.formatApiResponse(data2);
       } catch (e) {
       }
     }
     const sessionId = this.cache.getSessionId(locationId);
-    const data = await this.fetchFromApi(locationId, sessionId);
-    this.saveToCache(locationId, data);
+    const data = await this.fetchFromApi(locationId, sessionId, params);
+    this.saveToCache(locationId, data, params);
     return this.formatApiResponse(data);
   }
   getLocationId() {
@@ -141,12 +179,20 @@ var CallForge = class _CallForge {
     const params = new URLSearchParams(window.location.search);
     return params.get("loc_physical_ms");
   }
-  async fetchFromApi(locationId, sessionId) {
-    const { categoryId, endpoint } = this.config;
-    let url = `${endpoint}/v1/tracking/session?categoryId=${categoryId}&loc_physical_ms=${locationId}`;
-    if (sessionId) {
-      url += `&sessionId=${sessionId}`;
+  getAutoParams() {
+    if (typeof window === "undefined") return {};
+    const urlParams = new URLSearchParams(window.location.search);
+    const params = {};
+    for (const key of AUTO_PARAMS) {
+      const value = urlParams.get(key);
+      if (value) {
+        params[key] = value;
+      }
     }
+    return params;
+  }
+  async fetchFromApi(locationId, sessionId, params) {
+    const url = this.buildUrl(locationId, sessionId, params);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
@@ -162,13 +208,14 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
-  saveToCache(locationId, data) {
+  saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId,
       sessionId: data.sessionId,
       phoneNumber: data.phoneNumber,
       location: data.location,
-      expiresAt: data.expiresAt
+      expiresAt: data.expiresAt,
+      params
     };
     this.cache.set(cached);
   }
@@ -186,6 +233,24 @@ var CallForge = class _CallForge {
       location: data.location
     };
   }
+  buildUrl(locationId, sessionId, params) {
+    const { categoryId, endpoint } = this.config;
+    const queryParams = {
+      categoryId,
+      loc_physical_ms: locationId
+    };
+    if (sessionId) {
+      queryParams.sessionId = sessionId;
+    }
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) {
+        queryParams[key] = value;
+      }
+    }
+    const sorted = Object.keys(queryParams).sort();
+    const qs = sorted.map((k) => `${k}=${encodeURIComponent(queryParams[k])}`).join("&");
+    return `${endpoint}/v1/tracking/session?${qs}`;
+  }
 };
 
 // src/preload.ts
@@ -207,17 +272,25 @@ function getPreloadSnippet(config) {
   }
   const cacheKey = `cf_tracking_${categoryId}`;
   const script = `(function(){
-var loc=new URLSearchParams(location.search).get('loc_physical_ms');
+var u=new URLSearchParams(location.search);
+var loc=u.get('loc_physical_ms');
 if(!loc)return;
+var ap=['gclid','gbraid','wbraid','msclkid','fbclid'];
+var p={};
+for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var key='${cacheKey}';
 try{
 var c=JSON.parse(localStorage.getItem(key));
-if(c&&c.locId===loc&&c.expiresAt>Date.now()+30000){window.__cfTracking=Promise.resolve(c);return}
+if(c&&c.locId===loc&&c.expiresAt>Date.now()+30000){c.params=Object.assign({},c.params,p);window.__cfTracking=Promise.resolve(c);return}
 var sid=(c&&c.locId===loc)?c.sessionId:null;
+var cp=c&&c.params||{};
+p=Object.assign({},p,cp);
 }catch(e){}
 var url='${endpoint}/v1/tracking/session?categoryId=${categoryId}&loc_physical_ms='+loc;
 if(sid)url+='&sessionId='+sid;
-window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){return r.json()});
+var ks=Object.keys(p).sort();
+for(var j=0;j<ks.length;j++)url+='&'+ks[j]+'='+encodeURIComponent(p[ks[j]]);
+window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){return r.json()}).then(function(d){d.params=p;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionId:d.sessionId,phoneNumber:d.phoneNumber,location:d.location,expiresAt:d.expiresAt,params:p}))}catch(e){}return d});
 })();`.replace(/\n/g, "");
   return `<link rel="preconnect" href="${endpoint}">
 <script>${script}</script>`;

package/package.json

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