@aranova/tracking-react 0.17.0 → 0.17.1

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;
   }
@@ -1490,7 +1490,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 +2130,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 +2550,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 +2872,7 @@ function GoogleAdsTracking(props) {
 var import_react6 = require("react");
 
 // package.json
-var version = "0.17.0";
+var version = "0.17.1";
 
 // ../tracking-core/src/phone-react.tsx
 var import_react5 = require("react");
@@ -3021,6 +3078,10 @@ function createTracking(options) {
       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]();