@aranova/tracking-react 0.17.0 → 0.17.2

package/README.md

@@ -111,6 +111,33 @@ export function LeadForm() {
 
 `fields[].value` can be any JSON value: string, number, boolean, null, array, or object. Values must be JSON-serializable because events are stored as JSONB. Only send reviewed, allowlisted, non-sensitive values; do not send names, emails, phone numbers entered by the visitor, addresses, payment data, medical details, passwords, file contents, or free-text messages.
 
+### Phone clicks (`tel:` taps) — manual or auto-capture
+
+Opt into **auto-capture** and every `tel:` link is tracked with no per-link code. Add
+`autoCapture` to the `phone_click` registration — a single delegated click listener does the rest:
+
+```tsx
+manual: {
+  phone_click: { autoCapture: {} }, // default selector: a[href^="tel:"]
+  // or narrow it: { autoCapture: { selector: "a.call" } }
+},
+```
+
+```tsx
+<a href="tel:+14165550199" data-aranova-section="header">
+  (416) 555-0199
+</a>
+```
+
+The number is read from the `href` (normalized to E.164); `section` comes from an optional
+`data-aranova-section`. **Unlike `cta_click`, a `phone_click` also fires the Google Ads
+conversion** for a linked phone-call goal (a `CLICK_TO_CALL` action) — auto-fired the moment the
+tap is captured, so you never call `trackConversion` (firing needs the sales client wired with the
+same config; see below).
+
+Prefer to instrument links yourself? Fire it from a click handler — this fires the conversion the
+same way:
+
 ```tsx
 tracking.trackEvent("phone_click", {
   phone_number: "+14165550199",

package/dist/index.d.mts

@@ -483,9 +483,28 @@ type PhoneClickMetadata = z.infer<typeof phoneClickMetadataSchema>;
 /**
  * Registration config for `phone_click`.
  *
- * This event is manual-only and currently has no registration options.
+ * The event stays manually fireable; `autoCapture` additionally attaches a
+ * delegated click listener that fires it for any `tel:` link matching
+ * `selector` (default `a[href^="tel:"]`) — link your phone number, get the
+ * analytics event (and, for a linked phone-click goal, the conversion) for free.
  */
-declare const phoneClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+declare const phoneClickConfigSchema: z.ZodObject<{
+    autoCapture: z.ZodOptional<z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector?: string | undefined;
+    }, {
+        selector?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}>;
 type PhoneClickConfig = z.infer<typeof phoneClickConfigSchema>;
 
 /**
@@ -1041,7 +1060,23 @@ declare const EVENT_REGISTRY: {
             phone_number: string;
             section?: string | null | undefined;
         }>;
-        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+        readonly configSchema: z.ZodObject<{
+            autoCapture: z.ZodOptional<z.ZodObject<{
+                selector: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                selector?: string | undefined;
+            }, {
+                selector?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
+        }, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
+        }>;
     };
     readonly cta_click: {
         readonly kind: "manual";

package/dist/index.d.ts

@@ -483,9 +483,28 @@ type PhoneClickMetadata = z.infer<typeof phoneClickMetadataSchema>;
 /**
  * Registration config for `phone_click`.
  *
- * This event is manual-only and currently has no registration options.
+ * The event stays manually fireable; `autoCapture` additionally attaches a
+ * delegated click listener that fires it for any `tel:` link matching
+ * `selector` (default `a[href^="tel:"]`) — link your phone number, get the
+ * analytics event (and, for a linked phone-click goal, the conversion) for free.
  */
-declare const phoneClickConfigSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+declare const phoneClickConfigSchema: z.ZodObject<{
+    autoCapture: z.ZodOptional<z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector?: string | undefined;
+    }, {
+        selector?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}, {
+    autoCapture?: {
+        selector?: string | undefined;
+    } | undefined;
+}>;
 type PhoneClickConfig = z.infer<typeof phoneClickConfigSchema>;
 
 /**
@@ -1041,7 +1060,23 @@ declare const EVENT_REGISTRY: {
             phone_number: string;
             section?: string | null | undefined;
         }>;
-        readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+        readonly configSchema: z.ZodObject<{
+            autoCapture: z.ZodOptional<z.ZodObject<{
+                selector: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                selector?: string | undefined;
+            }, {
+                selector?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
+        }, {
+            autoCapture?: {
+                selector?: string | undefined;
+            } | undefined;
+        }>;
     };
     readonly cta_click: {
         readonly kind: "manual";

package/dist/index.js

@@ -830,8 +830,8 @@ function thresholdMet(goal, eventType, metadata) {
       return typeof metadata.page_name === "string" && metadata.page_name === t.page_name;
     case "page_view":
     case "form_start":
+    case "phone_click":
       return true;
-    // no threshold — fire whenever the detector emits
     default:
       return false;
   }
@@ -1206,6 +1206,27 @@ function getOrCreateTrackingClient(config) {
   globalClientKey = key;
   return globalClient;
 }
+var clientCaptureRegistry = /* @__PURE__ */ new WeakMap();
+function attachClientCapturesOnce(client, build) {
+  let entry = clientCaptureRegistry.get(client);
+  if (entry === void 0) {
+    entry = { detach: build(), refCount: 0 };
+    clientCaptureRegistry.set(client, entry);
+  }
+  entry.refCount += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const current = clientCaptureRegistry.get(client);
+    if (current === void 0) return;
+    current.refCount -= 1;
+    if (current.refCount <= 0) {
+      current.detach();
+      clientCaptureRegistry.delete(client);
+    }
+  };
+}
 function createTrackingClient(config) {
   const flushIntervalMs = config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
   const maxQueueSize = Math.min(config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE, HARD_MAX_BATCH);
@@ -1490,7 +1511,11 @@ var phoneClickMetadataSchema = import_zod8.z.object({
   }).strict(),
   section: import_zod8.z.string().nullable().optional()
 }).strict();
-var phoneClickConfigSchema = import_zod8.z.object({}).strict();
+var phoneClickConfigSchema = import_zod8.z.object({
+  autoCapture: import_zod8.z.object({
+    selector: import_zod8.z.string().optional()
+  }).strict().optional()
+}).strict();
 
 // ../tracking-core/src/events/scroll-depth.ts
 var import_zod9 = require("zod");
@@ -2126,6 +2151,99 @@ function attachCtaClickCapture(client, config) {
   };
 }
 
+// ../tracking-core/src/phone.ts
+var import_libphonenumber_js = require("libphonenumber-js");
+var DEFAULT_PHONE_COUNTRY = "CA";
+function parsePhone(raw, country) {
+  const region = country ?? DEFAULT_PHONE_COUNTRY;
+  const parsed = (0, import_libphonenumber_js.parsePhoneNumberFromString)(raw ?? "", region);
+  if (!parsed) {
+    return { e164: null, national: "", international: "", country: region, isValid: false };
+  }
+  const isValid = parsed.isValid();
+  return {
+    // E.164 is only surfaced for a *valid* number — a possible-but-invalid input
+    // (e.g. too few digits) still parses but must not be transmitted.
+    e164: isValid ? parsed.number : null,
+    national: parsed.formatNational(),
+    international: parsed.formatInternational(),
+    country: parsed.country ?? region,
+    isValid
+  };
+}
+function toE164(raw, country) {
+  return parsePhone(raw, country).e164;
+}
+function formatPhone(value, format = "national", country) {
+  const parsed = parsePhone(value, country);
+  if (typeof format === "function") return format(parsed);
+  switch (format) {
+    case "international":
+      return parsed.international || value;
+    case "e164":
+      return parsed.e164 ?? value;
+    case "national":
+    default:
+      return parsed.national || value;
+  }
+}
+function formatPhoneAsTyped(raw, country) {
+  return new import_libphonenumber_js.AsYouType(country ?? DEFAULT_PHONE_COUNTRY).input(raw ?? "");
+}
+
+// ../tracking-core/src/triggers/phone-click-capture.ts
+var DEFAULT_TEL_SELECTOR = 'a[href^="tel:"]';
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+function resolvePhoneNumber(el) {
+  const href = el instanceof HTMLAnchorElement ? el.href : el.getAttribute("href") ?? "";
+  const raw = safeDecodeURIComponent(href.replace(/^tel:/i, "").split(";")[0]).trim();
+  return toE164(raw) ?? raw;
+}
+function attachPhoneClickCapture(client, config) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {
+    };
+  }
+  const autoCapture = config.autoCapture;
+  if (!autoCapture) {
+    return () => {
+    };
+  }
+  const selector = autoCapture.selector ?? DEFAULT_TEL_SELECTOR;
+  function onClick(event) {
+    const target = event.target;
+    if (!(target instanceof Element)) return;
+    let matched = null;
+    try {
+      matched = target.closest(selector);
+    } catch {
+      return;
+    }
+    if (matched === null) return;
+    const metadata = {
+      phone_number: resolvePhoneNumber(matched),
+      page: { path: window.location.pathname },
+      section: matched.getAttribute("data-aranova-section")
+    };
+    client.trackEvent({
+      eventType: "phone_click",
+      metadata,
+      pageUrl: window.location.href,
+      occurredAt: null
+    });
+  }
+  document.addEventListener("click", onClick, true);
+  return () => {
+    document.removeEventListener("click", onClick, true);
+  };
+}
+
 // ../tracking-core/src/resources/sales/errors.ts
 var AranovaApiError = class extends Error {
   constructor(message, options) {
@@ -2453,46 +2571,6 @@ async function fetchServices(config) {
   return salesRequest(config, "GET", "/services");
 }
 
-// ../tracking-core/src/phone.ts
-var import_libphonenumber_js = require("libphonenumber-js");
-var DEFAULT_PHONE_COUNTRY = "CA";
-function parsePhone(raw, country) {
-  const region = country ?? DEFAULT_PHONE_COUNTRY;
-  const parsed = (0, import_libphonenumber_js.parsePhoneNumberFromString)(raw ?? "", region);
-  if (!parsed) {
-    return { e164: null, national: "", international: "", country: region, isValid: false };
-  }
-  const isValid = parsed.isValid();
-  return {
-    // E.164 is only surfaced for a *valid* number — a possible-but-invalid input
-    // (e.g. too few digits) still parses but must not be transmitted.
-    e164: isValid ? parsed.number : null,
-    national: parsed.formatNational(),
-    international: parsed.formatInternational(),
-    country: parsed.country ?? region,
-    isValid
-  };
-}
-function toE164(raw, country) {
-  return parsePhone(raw, country).e164;
-}
-function formatPhone(value, format = "national", country) {
-  const parsed = parsePhone(value, country);
-  if (typeof format === "function") return format(parsed);
-  switch (format) {
-    case "international":
-      return parsed.international || value;
-    case "e164":
-      return parsed.e164 ?? value;
-    case "national":
-    default:
-      return parsed.national || value;
-  }
-}
-function formatPhoneAsTyped(raw, country) {
-  return new import_libphonenumber_js.AsYouType(country ?? DEFAULT_PHONE_COUNTRY).input(raw ?? "");
-}
-
 // ../tracking-core/src/phone-field.ts
 function phoneField(name, raw, country) {
   return { name, type: "phone", value: toE164(raw, country) };
@@ -2815,7 +2893,7 @@ function GoogleAdsTracking(props) {
 var import_react6 = require("react");
 
 // package.json
-var version = "0.17.0";
+var version = "0.17.2";
 
 // ../tracking-core/src/phone-react.tsx
 var import_react5 = require("react");
@@ -2978,7 +3056,6 @@ function createTracking(options) {
       }
     }, [metaPixelId, metaPixelIdsKey]);
     (0, import_react6.useEffect)(() => {
-      const detachers = [];
       const rawClient = getOrCreateTrackingClient({
         apiKey,
         endpoint,
@@ -2989,43 +3066,50 @@ function createTracking(options) {
         activeGtagIds: resolvedGtagIds,
         debug
       });
-      const conversionStore = conversionConfig ? resolveConversionConfig({
-        cdnUrl: conversionConfig.cdnUrl,
-        baked: conversionConfig.baked
-      }) : null;
-      const detectorClient = conversionStore ? withConversionAutoFire(rawClient, createConversionAutoFire(conversionStore)) : rawClient;
-      detachers.push(attachAutoPageView(detectorClient));
-      detachers.push(attachBfcacheRestore(detectorClient));
-      detachers.push(attachPageExit(detectorClient));
-      const timeOnSite = triggers.automatic.time_on_site;
-      if (timeOnSite) {
-        detachers.push(attachTimeOnSite(detectorClient, timeOnSite));
-      }
-      const specificPageVisit = triggers.automatic.specific_page_visit;
-      if (specificPageVisit) {
-        detachers.push(attachSpecificPageVisit(detectorClient, specificPageVisit));
-      }
-      const scrollDepth = triggers.automatic.scroll_depth;
-      if (scrollDepth) {
-        detachers.push(attachScrollDepth(detectorClient, scrollDepth));
-      }
-      const multiPageSession = triggers.automatic.multi_page_session;
-      if (multiPageSession) {
-        detachers.push(attachMultiPageSession(detectorClient, multiPageSession));
-      }
-      const formStart = triggers.automatic.form_start;
-      if (formStart) {
-        detachers.push(attachFormStart(detectorClient, formStart));
-      }
-      const ctaClick = triggers.manual?.cta_click;
-      if (ctaClick) {
-        detachers.push(attachCtaClickCapture(detectorClient, ctaClick));
-      }
-      return () => {
-        for (let i = detachers.length - 1; i >= 0; i--) {
-          detachers[i]();
+      return attachClientCapturesOnce(rawClient, () => {
+        const detachers = [];
+        const conversionStore = conversionConfig ? resolveConversionConfig({
+          cdnUrl: conversionConfig.cdnUrl,
+          baked: conversionConfig.baked
+        }) : null;
+        const detectorClient = conversionStore ? withConversionAutoFire(rawClient, createConversionAutoFire(conversionStore)) : rawClient;
+        detachers.push(attachAutoPageView(detectorClient));
+        detachers.push(attachBfcacheRestore(detectorClient));
+        detachers.push(attachPageExit(detectorClient));
+        const timeOnSite = triggers.automatic.time_on_site;
+        if (timeOnSite) {
+          detachers.push(attachTimeOnSite(detectorClient, timeOnSite));
+        }
+        const specificPageVisit = triggers.automatic.specific_page_visit;
+        if (specificPageVisit) {
+          detachers.push(attachSpecificPageVisit(detectorClient, specificPageVisit));
         }
-      };
+        const scrollDepth = triggers.automatic.scroll_depth;
+        if (scrollDepth) {
+          detachers.push(attachScrollDepth(detectorClient, scrollDepth));
+        }
+        const multiPageSession = triggers.automatic.multi_page_session;
+        if (multiPageSession) {
+          detachers.push(attachMultiPageSession(detectorClient, multiPageSession));
+        }
+        const formStart = triggers.automatic.form_start;
+        if (formStart) {
+          detachers.push(attachFormStart(detectorClient, formStart));
+        }
+        const ctaClick = triggers.manual?.cta_click;
+        if (ctaClick) {
+          detachers.push(attachCtaClickCapture(detectorClient, ctaClick));
+        }
+        const phoneClick = triggers.manual?.phone_click;
+        if (phoneClick) {
+          detachers.push(attachPhoneClickCapture(detectorClient, phoneClick));
+        }
+        return () => {
+          for (let i = detachers.length - 1; i >= 0; i--) {
+            detachers[i]();
+          }
+        };
+      });
     }, []);
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(TrackingContext.Provider, { value: client, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(PhoneConfigProvider, { value: phone ?? null, children }) });
   }