luchy 1.1.0 → 1.2.0

package/README.md

@@ -123,6 +123,15 @@ window.luchy.reset();
 `identify`/`reset` write through to the script tag's `data-identity` /
 `data-props`, so the tag stays the single source of truth.
 
+### UTM attribution
+
+Every pageview reads `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`
+and `utm_content` from `location.search` and adds the present ones to its
+payload (trimmed, at most 200 characters). Nothing else from the query string
+is sent, and a key in the pageview's own `payload` wins over the URL. Ingest
+keeps the first `utm_source` / `utm_medium` / `utm_campaign` of a session as
+its attribution.
+
 ## Identity
 
 Luchy ties hits to your users only when your server vouches for them. An
@@ -218,6 +227,9 @@ await luchy.pageview({ pathname: '/pricing', payload: { plan: 'pro' } });
   is the server.
 - Nothing ever rejects — analytics must not break the request it is
   describing. Pass `onError` if you want failures in your logs.
+- UTM attribution is not read from any URL here: pass the same keys
+  (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) in
+  `payload` and the session is attributed exactly as for the browser script.
 
 ## API client (`luchy/api`)
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,aAAa,CAAC,IAAI,CAAC,EAAE;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,UAAU,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,0DAA0D;IAC1D,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAChD,CAAC;AAgBF;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CA2Z7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,aAAa,CAAC,IAAI,CAAC,EAAE;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,UAAU,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,0DAA0D;IAC1D,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAChD,CAAC;AAgBF;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAka7D"}

package/dist/index.js

@@ -21,6 +21,24 @@ function collectBrowserData() {
     language: navigator.language || navigator.languages?.[0] || "en"
   };
 }
+const UTM_KEYS = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content"
+];
+const MAX_LENGTH = 200;
+function utmParams(search) {
+  const params = new URLSearchParams(search);
+  const utm = {};
+  for (const key of UTM_KEYS) {
+    const value = params.get(key)?.trim().slice(0, MAX_LENGTH);
+    if (!value) continue;
+    utm[key] = value;
+  }
+  return utm;
+}
 function parseProps(raw) {
   if (!raw) return void 0;
   try {
@@ -73,6 +91,11 @@ function luchy(options) {
     if (!global) return payload;
     return { ...global, ...payload };
   }
+  function withUtm(payload) {
+    const utm = utmParams(location.search || "");
+    if (Object.keys(utm).length === 0) return payload;
+    return { ...utm, ...payload };
+  }
   const shouldTrack = () => {
     if (trackLocalhost) return true;
     return location.hostname !== "localhost" && location.hostname !== "127.0.0.1";
@@ -88,7 +111,7 @@ function luchy(options) {
       data: {
         pathname,
         referrer,
-        payload: withProps(data?.payload),
+        payload: withProps(withUtm(data?.payload)),
         identity: currentIdentity(),
         ...browserData
       }

package/dist/script/luchy.js

@@ -62,6 +62,25 @@ var __async = (__this, __arguments, generator) => {
       language: navigator.language || ((_a = navigator.languages) == null ? void 0 : _a[0]) || "en"
     };
   }
+  const UTM_KEYS = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content"
+  ];
+  const MAX_LENGTH = 200;
+  function utmParams(search) {
+    var _a;
+    const params = new URLSearchParams(search);
+    const utm = {};
+    for (const key of UTM_KEYS) {
+      const value = (_a = params.get(key)) == null ? void 0 : _a.trim().slice(0, MAX_LENGTH);
+      if (!value) continue;
+      utm[key] = value;
+    }
+    return utm;
+  }
   function parseProps(raw) {
     if (!raw) return void 0;
     try {
@@ -114,6 +133,11 @@ var __async = (__this, __arguments, generator) => {
       if (!global) return payload;
       return __spreadValues(__spreadValues({}, global), payload);
     }
+    function withUtm(payload) {
+      const utm = utmParams(location.search || "");
+      if (Object.keys(utm).length === 0) return payload;
+      return __spreadValues(__spreadValues({}, utm), payload);
+    }
     const shouldTrack = () => {
       if (trackLocalhost) return true;
       return location.hostname !== "localhost" && location.hostname !== "127.0.0.1";
@@ -130,7 +154,7 @@ var __async = (__this, __arguments, generator) => {
           data: __spreadValues({
             pathname,
             referrer,
-            payload: withProps(data == null ? void 0 : data.payload),
+            payload: withProps(withUtm(data == null ? void 0 : data.payload)),
             identity: currentIdentity()
           }, browserData)
         });

package/dist/script/luchy.min.js

@@ -62,6 +62,25 @@ var __async = (__this, __arguments, generator) => {
       language: navigator.language || ((_a = navigator.languages) == null ? void 0 : _a[0]) || "en"
     };
   }
+  const UTM_KEYS = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content"
+  ];
+  const MAX_LENGTH = 200;
+  function utmParams(search) {
+    var _a;
+    const params = new URLSearchParams(search);
+    const utm = {};
+    for (const key of UTM_KEYS) {
+      const value = (_a = params.get(key)) == null ? void 0 : _a.trim().slice(0, MAX_LENGTH);
+      if (!value) continue;
+      utm[key] = value;
+    }
+    return utm;
+  }
   function parseProps(raw) {
     if (!raw) return void 0;
     try {
@@ -114,6 +133,11 @@ var __async = (__this, __arguments, generator) => {
       if (!global) return payload;
       return __spreadValues(__spreadValues({}, global), payload);
     }
+    function withUtm(payload) {
+      const utm = utmParams(location.search || "");
+      if (Object.keys(utm).length === 0) return payload;
+      return __spreadValues(__spreadValues({}, utm), payload);
+    }
     const shouldTrack = () => {
       if (trackLocalhost) return true;
       return location.hostname !== "localhost" && location.hostname !== "127.0.0.1";
@@ -130,7 +154,7 @@ var __async = (__this, __arguments, generator) => {
           data: __spreadValues({
             pathname,
             referrer,
-            payload: withProps(data == null ? void 0 : data.payload),
+            payload: withProps(withUtm(data == null ? void 0 : data.payload)),
             identity: currentIdentity()
           }, browserData)
         });

package/dist/utm.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The UTM parameters present in a query string, trimmed and capped at 200
+ * characters. Nothing else from the query string is kept.
+ */
+export declare function utmParams(search: string): Record<string, string>;
+//# sourceMappingURL=utm.d.ts.map

package/dist/utm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utm.d.ts","sourceRoot":"","sources":["../src/utm.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAShE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luchy",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Luchy tracking - browser script, server tracker and React Router middleware",
   "type": "module",
   "main": "./dist/index.js",