@rebilly/lead-source-tracker 8.28.4 → 8.30.0

package/README.md

@@ -29,6 +29,12 @@ You can provide additional cookie attribues using the second argument:
 
 See https://github.com/js-cookie/js-cookie#cookie-attributes for the full list of supported attributes.
 
+The second argument also accepts two non-cookie options, `classifyReferrer` and `visitorId`:
+
+`RebillyLeadSource.collect(window, { domain: 'rebilly.com', secure: true, classifyReferrer: true, visitorId: true })`
+
+See [Referrer classification](#referrer-classification-opt-in) and [Visitor id](#visitor-id-opt-in) below.
+
 4. Call `collect` again when submitting lead source information to the Rebilly API. The function returns all saved cookie data as an object.
 
 Example:
@@ -74,6 +80,44 @@ Some data is automatically inferred by `RebillyLeadSource` when data collection
 2. `document.location`
     - URL is parsed and saved to leadSource.path
 
+### Referrer classification (opt-in)
+
+Most visitors arrive without UTM parameters, so `source` and `medium` stay empty and reports show these leads as "direct / none".
+When you pass `classifyReferrer: true` to `collect`, the tracker maps well-known referrer hostnames to `source` and `medium` values.
+
+Rules:
+
+- Classification fills a field only when nothing else set it. UTM parameters, `#rls-token` attributes, and previously saved cookie values always win.
+- Classification uses the saved first-touch referrer, so a later visit does not change an existing attribution.
+- Unknown referrers stay unclassified. The tracker never guesses.
+- The option is off by default. Existing integrations see no behavior change.
+
+Recognized hostnames include search engines (`google`, `bing`, `duckduckgo` → `organic-search`), developer communities (`github`, `stack-overflow`, `reddit`, `hacker-news`, `dev-to` → `community`), social networks (`linkedin`, `x-twitter`, `youtube`, `bluesky`, `facebook`, `instagram`, `tiktok`, `snapchat`, `pinterest`, `threads` → `social`), webmail (`gmail`, `outlook`, `yahoo-mail` → `email`), and AI assistants (`chatgpt`, `perplexity`, `claude`, `gemini`, `copilot` → `ai-assistant`).
+For Google, only search hosts (`google.<tld>`, `www.google.<tld>`) classify as organic search — other Google properties such as `docs.google.com` or `accounts.google.com` stay unclassified.
+See `src/referrerClassification.ts` for the full table.
+
+### Visitor id (opt-in)
+
+The tracker does not store a browser identifier unless you ask for one.
+When you pass `visitorId: true` to `collect`, it writes a UUIDv7 ([RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7)) to `leadSource.clickId` and keeps that value for the cookie lifetime.
+
+Rules:
+
+- The id is generated only when `leadSource.clickId` is empty. A later visit, `utm_*` parameters, and ad click parameters such as `gclid` do not change it.
+- Incoming `clickId` / `clickid` query params and `#rls-token` `data-click-id` are ignored while the option is on. The cookie holds a generated visitor id, not an ad click id.
+- An existing non-empty `clickId` (including an old ad id) is left as-is.
+- The option is off by default. Existing integrations that use `clickId` for ad attribution see no behavior change.
+- Generation needs `crypto.getRandomValues`. There is no `Math.random()` fallback. If `crypto.getRandomValues` is missing, `clickId` stays unset and the rest of collect still runs.
+- Pass `visitorId: true` on **every** `collect` call. An option-off `collect` (including the package's `DOMContentLoaded` auto-collect) treats `clickId` as updatable again and can overwrite a generated id from `?clickId=` or `#rls-token` `data-click-id`.
+
+Read the id without parsing the cookie:
+
+```
+const visitorId = RebillyLeadSource.getVisitorId();
+```
+
+`getVisitorId()` only reads the cookie. It does not generate or write. Call `collect(..., { visitorId: true })` first if you need the id to exist.
+
 ### Query params
 
 | key                              | example                 | purpose                                                                                      |
@@ -86,7 +130,7 @@ Some data is automatically inferred by `RebillyLeadSource` when data collection
 | `content`                        | `?content=example`      | Change the leadSource `content` field                                                        |
 | `affiliate`                      | `?affiliate=example`    | Change the leadSource `affiliate` field                                                      |
 | `subAffiliate` or `subaffiliate` | `?subAffiliate=example` | Change the leadSource `subAffiliate` field                                                   |
-| `clickId` or `clickid`           | `?clickId=example`      | Change the leadSource `clickId` field                                                        |
+| `clickId` or `clickid`           | `?clickId=example`      | Change the leadSource `clickId` field. Ignored when `visitorId: true`                        |
 | `salesAgent` or `salesagent`     | `?salesAgent=example`   | Change the leadSource `salesAgent` field                                                     |
 | `path`                           | `?path=example`         | Change the leadSource `path` field. This cannot be updated once it is set the first time     |
 | `referrer`                       | `?referrer=example`     | Change the leadSource `referrer` field. This cannot be updated once it is set the first time |
@@ -127,6 +171,8 @@ The following fields will not be updated after the first time they are saved to
 - path
 - referrer
 
+When `visitorId: true`, `clickId` is also left unchanged after it is first saved (generated UUIDv7, or whatever value was already in the cookie).
+
 The only exception is if the cookie expires (after 45 days) or is cleared by the user.
 
 All other fields will update the saved cookie whenever `collect` is called.

package/dist/build.js

@@ -1 +1 @@
-(function(u,f){typeof exports=="object"&&typeof module<"u"?module.exports=f():typeof define=="function"&&define.amd?define(f):(u=typeof globalThis<"u"?globalThis:u||self,u.RebillyLeadSource=f())})(this,(function(){"use strict";/*! js-cookie v3.0.8 | MIT */function u(e){for(var r=1;r<arguments.length;r++){var n=arguments[r];for(var c in n)c!=="__proto__"&&(e[c]=n[c])}return e}var f={read:function(e){return e[0]==='"'&&(e=e.slice(1,-1)),e.replace(/(%[\dA-F]{2})+/gi,decodeURIComponent)},write:function(e){return encodeURIComponent(e).replace(/%(2[346BF]|3[AC-F]|40|5[BDE]|60|7[BCD])/g,decodeURIComponent)}};function p(e,r){function n(t,a,o){if(!(typeof document>"u")){o=u({},r,o),typeof o.expires=="number"&&(o.expires=new Date(Date.now()+o.expires*864e5)),o.expires&&(o.expires=o.expires.toUTCString()),t=encodeURIComponent(t).replace(/%(2[346B]|5E|60|7C)/g,decodeURIComponent).replace(/[()]/g,escape);var i="";for(var s in o)o[s]&&(i+="; "+s,o[s]!==!0&&(i+="="+o[s].split(";")[0]));return document.cookie=t+"="+e.write(a,t)+i}}function c(t){if(!(typeof document>"u"||arguments.length&&!t)){for(var a=document.cookie?document.cookie.split("; "):[],o={},i=0;i<a.length;i++){var s=a[i].split("="),I=s.slice(1).join("=");try{var l=decodeURIComponent(s[0]);if(l in o||(o[l]=e.read(I,l)),t===l)break}catch{}}return t?o[t]:o}}return Object.create({set:n,get:c,remove:function(t,a){n(t,"",u({},a,{expires:-1}))},withAttributes:function(t){return p(this.converter,u({},this.attributes,t))},withConverter:function(t){return p(u({},this.converter,t),this.attributes)}},{attributes:{value:Object.freeze(r)},converter:{value:Object.freeze(e)}})}var m=p(f,{path:"/"});const h="rls",g={expires:45},O=["source","medium","campaign","term","content","affiliate","subAffiliate","clickId","salesAgent"],C=["path","referrer"],k=[...C,...O];function S(e,r){const{document:n}=e;if(w(e))return d({dnt:!0}),{};const c={path:n.location.host+n.location.pathname,...U(n),...T(n),...y(e)},{leadSource:t}=R({leadSource:c},r);return t||{}}function d({dnt:e=!1}){const r={dnt:e};return e?x(r):m.remove(h,g),r}function R(e,r){const n=D();if(n.dnt||e.dnt)return d({dnt:!0});d({dnt:!1});const c=n.leadSource||{},t=C.reduce((o,i)=>{const s=c[i];return s&&(o[i]=s),o},{}),a={leadSource:{...c,...v(e.leadSource),...t}};return Object.assign(g,r||{}),x(a),a}function D(){const e=m.get(h);if(!e)return{};try{const r=JSON.parse(e);return r.dnt?{dnt:!0}:r}catch{return{}}}function x(e){m.set(h,JSON.stringify(e),g)}function U(e){const{dataset:r}=e.querySelector("#rls-token")||{};return v(r)}function y(e){const r=new URLSearchParams(e.location.search),n=k.reduce((c,t)=>(c[t]=r.get(`utm_${t}`)||r.get(t)||r.get(`utm_${t.toLowerCase()}`)||r.get(t.toLowerCase())||null,c),{});return v(n)}function T(e){try{return new URL(e.referrer).hostname!==e.location.hostname?{referrer:e.referrer}:{}}catch{return{}}}function w(e){const n=new URLSearchParams(e.location.search).has("dnt"),{dnt:c}=D(),t=F(e);return n||t||c}function F(e){const{navigator:r}=e;if(e.doNotTrack||r.doNotTrack||r.msDoNotTrack)return e.doNotTrack=="1"||r.doNotTrack=="yes"||r.doNotTrack=="1"||r.msDoNotTrack=="1"}function v(e={}){return k.reduce((r,n)=>{const c=(e[n]||"").trim();return c&&(r[n]=c),r},{})}return typeof window<"u"&&document.addEventListener("DOMContentLoaded",()=>{S(window)}),{collect:S,clear:d}}));
+(function(l,m){typeof exports=="object"&&typeof module<"u"?module.exports=m():typeof define=="function"&&define.amd?define(m):(l=typeof globalThis<"u"?globalThis:l||self,l.RebillyLeadSource=m())})(this,(function(){"use strict";/*! js-cookie v3.0.8 | MIT */function l(e){for(var o=1;o<arguments.length;o++){var r=arguments[o];for(var c in r)c!=="__proto__"&&(e[c]=r[c])}return e}var m={read:function(e){return e[0]==='"'&&(e=e.slice(1,-1)),e.replace(/(%[\dA-F]{2})+/gi,decodeURIComponent)},write:function(e){return encodeURIComponent(e).replace(/%(2[346BF]|3[AC-F]|40|5[BDE]|60|7[BCD])/g,decodeURIComponent)}};function h(e,o){function r(n,u,i){if(!(typeof document>"u")){i=l({},o,i),typeof i.expires=="number"&&(i.expires=new Date(Date.now()+i.expires*864e5)),i.expires&&(i.expires=i.expires.toUTCString()),n=encodeURIComponent(n).replace(/%(2[346B]|5E|60|7C)/g,decodeURIComponent).replace(/[()]/g,escape);var a="";for(var s in i)i[s]&&(a+="; "+s,i[s]!==!0&&(a+="="+i[s].split(";")[0]));return document.cookie=n+"="+e.write(u,n)+a}}function c(n){if(!(typeof document>"u"||arguments.length&&!n)){for(var u=document.cookie?document.cookie.split("; "):[],i={},a=0;a<u.length;a++){var s=u[a].split("="),f=s.slice(1).join("=");try{var d=decodeURIComponent(s[0]);if(d in i||(i[d]=e.read(f,d)),n===d)break}catch{}}return n?i[n]:i}}return Object.create({set:r,get:c,remove:function(n,u){r(n,"",l({},u,{expires:-1}))},withAttributes:function(n){return h(this.converter,l({},this.attributes,n))},withConverter:function(n){return h(l({},this.converter,n),this.attributes)}},{attributes:{value:Object.freeze(o)},converter:{value:Object.freeze(e)}})}var g=h(m,{path:"/"});function t(e,o,r){return{test:c=>c===e||c.endsWith(`.${e}`),source:o,medium:r}}const b=[t("chatgpt.com","chatgpt","ai-assistant"),t("chat.openai.com","chatgpt","ai-assistant"),t("perplexity.ai","perplexity","ai-assistant"),t("claude.ai","claude","ai-assistant"),t("gemini.google.com","gemini","ai-assistant"),t("copilot.microsoft.com","copilot","ai-assistant"),t("mail.google.com","gmail","email"),t("outlook.live.com","outlook","email"),t("outlook.office.com","outlook","email"),t("mail.yahoo.com","yahoo-mail","email"),{test:e=>/^(www\.)?google\.[a-z]{2,3}(\.[a-z]{2})?$/.test(e),source:"google",medium:"organic-search"},t("bing.com","bing","organic-search"),t("duckduckgo.com","duckduckgo","organic-search"),t("github.com","github","community"),t("stackoverflow.com","stack-overflow","community"),t("reddit.com","reddit","community"),t("news.ycombinator.com","hacker-news","community"),t("dev.to","dev-to","community"),t("linkedin.com","linkedin","social"),t("lnkd.in","linkedin","social"),t("twitter.com","x-twitter","social"),t("x.com","x-twitter","social"),t("t.co","x-twitter","social"),t("youtube.com","youtube","social"),t("youtu.be","youtube","social"),t("bsky.app","bluesky","social"),t("facebook.com","facebook","social"),t("fb.com","facebook","social"),t("fb.me","facebook","social"),t("instagram.com","instagram","social"),t("tiktok.com","tiktok","social"),t("snapchat.com","snapchat","social"),t("pinterest.com","pinterest","social"),t("pin.it","pinterest","social"),t("threads.net","threads","social"),t("threads.com","threads","social")];function D(e){if(!e)return null;let o;try{o=new URL(e).hostname.toLowerCase()}catch{return null}const r=b.find(c=>c.test(o));return r?{source:r.source,medium:r.medium}:null}function I(e){return[...e].map(o=>o.toString(16).padStart(2,"0")).join("")}function U(){if(typeof crypto>"u"||typeof crypto.getRandomValues!="function")return null;const e=new Uint8Array(16);crypto.getRandomValues(e);const o=Date.now();e[0]=Math.floor(o/1099511627776)&255,e[1]=Math.floor(o/4294967296)&255,e[2]=Math.floor(o/16777216)&255,e[3]=Math.floor(o/65536)&255,e[4]=Math.floor(o/256)&255,e[5]=o&255,e[6]=e[6]&15|112,e[8]=e[8]&63|128;const r=I(e);return`${r.slice(0,8)}-${r.slice(8,12)}-${r.slice(12,16)}-${r.slice(16,20)}-${r.slice(20)}`}const k="rls",y={expires:45},O=["source","medium","campaign","term","content","affiliate","subAffiliate","clickId","salesAgent"],C=["path","referrer"],S=[...C,...O];function x(e,o){const{classifyReferrer:r=!1,visitorId:c=!1,...n}=o||{},{document:u}=e;if($(e))return p({dnt:!0}),{};const i={path:u.location.host+u.location.pathname,...A(u),..._(u),...F(e)};c&&delete i.clickId;const{leadSource:a}=T({leadSource:i},n,r,c);return a||{}}function p({dnt:e=!1}){const o={dnt:e};return e?R(o):g.remove(k,y),o}function L(){var e;return(e=v().leadSource)==null?void 0:e.clickId}function T(e,o,r=!1,c=!1){const n=v();if(n.dnt||e.dnt)return p({dnt:!0});p({dnt:!1});const u=n.leadSource||{},i=C.reduce((s,f)=>{const d=u[f];return d&&(s[f]=d),s},{}),a={leadSource:{...u,...w(e.leadSource),...i}};if(r){const s=a.leadSource;if(!s.source||!s.medium){const f=D(s.referrer);f&&(s.source=s.source||f.source,s.medium=s.medium||f.medium)}}if(c&&!a.leadSource.clickId){const s=U();s&&(a.leadSource.clickId=s)}return Object.assign(y,o||{}),R(a),a}function v(){const e=g.get(k);if(!e)return{};try{const o=JSON.parse(e);return o.dnt?{dnt:!0}:o}catch{return{}}}function R(e){g.set(k,JSON.stringify(e),y)}function A(e){const{dataset:o}=e.querySelector("#rls-token")||{};return w(o)}function F(e){const o=new URLSearchParams(e.location.search),r=S.reduce((c,n)=>(c[n]=o.get(`utm_${n}`)||o.get(n)||o.get(`utm_${n.toLowerCase()}`)||o.get(n.toLowerCase())||null,c),{});return w(r)}function _(e){try{return new URL(e.referrer).hostname!==e.location.hostname?{referrer:e.referrer}:{}}catch{return{}}}function $(e){const r=new URLSearchParams(e.location.search).has("dnt"),{dnt:c}=v(),n=M(e);return r||n||c}function M(e){const{navigator:o}=e;if(e.doNotTrack||o.doNotTrack||o.msDoNotTrack)return e.doNotTrack=="1"||o.doNotTrack=="yes"||o.doNotTrack=="1"||o.msDoNotTrack=="1"}function w(e={}){return S.reduce((o,r)=>{const c=(e[r]||"").trim();return c&&(o[r]=c),o},{})}return typeof window<"u"&&document.addEventListener("DOMContentLoaded",()=>{x(window)}),{collect:x,clear:p,getVisitorId:L}}));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rebilly/lead-source-tracker",
-    "version": "8.28.4",
+    "version": "8.30.0",
     "description": "Simple library which is used to collect and store lead source information into a cookie",
     "author": "Rebilly",
     "repository": "https://github.com/Rebilly/rebilly",
@@ -10,7 +10,9 @@
     ],
     "scripts": {
         "serve": "pnpm build && node ./dev/server.js",
-        "build": "vite build"
+        "build": "vite build",
+        "test:unit": "vitest run",
+        "test:unit:watch": "vitest"
     },
     "browserslist": [
         "> 1%",
@@ -20,7 +22,8 @@
         "@rebilly/eslint-config": "*",
         "express": "^5.1.0",
         "vite": "^6.4.3",
-        "vite-plugin-commonjs": "^0.10.4"
+        "vite-plugin-commonjs": "^0.10.4",
+        "vitest": "^4.1.0"
     },
     "dependencies": {
         "js-cookie": "^3.0.8"