@rebilly/lead-source-tracker 8.28.3 → 8.29.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 one non-cookie option, `classifyReferrer`:
+
+`RebillyLeadSource.collect(window, { domain: 'rebilly.com', secure: true, classifyReferrer: true })`
+
+See [Referrer classification](#referrer-classification-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,22 @@ 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.
+
 ### Query params
 
 | key                              | example                 | purpose                                                                                      |

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.7 | 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 i=arguments[o];for(var n in i)n!=="__proto__"&&(e[n]=i[n])}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 g(e,o){function i(r,u,c){if(!(typeof document>"u")){c=l({},o,c),typeof c.expires=="number"&&(c.expires=new Date(Date.now()+c.expires*864e5)),c.expires&&(c.expires=c.expires.toUTCString()),r=encodeURIComponent(r).replace(/%(2[346B]|5E|60|7C)/g,decodeURIComponent).replace(/[()]/g,escape);var s="";for(var a in c)c[a]&&(s+="; "+a,c[a]!==!0&&(s+="="+c[a].split(";")[0]));return document.cookie=r+"="+e.write(u,r)+s}}function n(r){if(!(typeof document>"u"||arguments.length&&!r)){for(var u=document.cookie?document.cookie.split("; "):[],c={},s=0;s<u.length;s++){var a=u[s].split("="),d=a.slice(1).join("=");try{var p=decodeURIComponent(a[0]);if(p in c||(c[p]=e.read(d,p)),r===p)break}catch{}}return r?c[r]:c}}return Object.create({set:i,get:n,remove:function(r,u){i(r,"",l({},u,{expires:-1}))},withAttributes:function(r){return g(this.converter,l({},this.attributes,r))},withConverter:function(r){return g(l({},this.converter,r),this.attributes)}},{attributes:{value:Object.freeze(o)},converter:{value:Object.freeze(e)}})}var h=g(m,{path:"/"});function t(e,o,i){return{test:n=>n===e||n.endsWith(`.${e}`),source:o,medium:i}}const S=[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 i=S.find(n=>n.test(o));return i?{source:i.source,medium:i.medium}:null}const k="rls",y={expires:45},U=["source","medium","campaign","term","content","affiliate","subAffiliate","clickId","salesAgent"],C=["path","referrer"],w=[...C,...U];function x(e,o){const{classifyReferrer:i=!1,...n}=o||{},{document:r}=e;if(I(e))return f({dnt:!0}),{};const u={path:r.location.host+r.location.pathname,...L(r),...F(r),...T(e)},{leadSource:c}=O({leadSource:u},n,i);return c||{}}function f({dnt:e=!1}){const o={dnt:e};return e?R(o):h.remove(k,y),o}function O(e,o,i=!1){const n=b();if(n.dnt||e.dnt)return f({dnt:!0});f({dnt:!1});const r=n.leadSource||{},u=C.reduce((s,a)=>{const d=r[a];return d&&(s[a]=d),s},{}),c={leadSource:{...r,...v(e.leadSource),...u}};if(i){const s=c.leadSource;if(!s.source||!s.medium){const a=D(s.referrer);a&&(s.source=s.source||a.source,s.medium=s.medium||a.medium)}}return Object.assign(y,o||{}),R(c),c}function b(){const e=h.get(k);if(!e)return{};try{const o=JSON.parse(e);return o.dnt?{dnt:!0}:o}catch{return{}}}function R(e){h.set(k,JSON.stringify(e),y)}function L(e){const{dataset:o}=e.querySelector("#rls-token")||{};return v(o)}function T(e){const o=new URLSearchParams(e.location.search),i=w.reduce((n,r)=>(n[r]=o.get(`utm_${r}`)||o.get(r)||o.get(`utm_${r.toLowerCase()}`)||o.get(r.toLowerCase())||null,n),{});return v(i)}function F(e){try{return new URL(e.referrer).hostname!==e.location.hostname?{referrer:e.referrer}:{}}catch{return{}}}function I(e){const i=new URLSearchParams(e.location.search).has("dnt"),{dnt:n}=b(),r=_(e);return i||r||n}function _(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 v(e={}){return w.reduce((o,i)=>{const n=(e[i]||"").trim();return n&&(o[i]=n),o},{})}return typeof window<"u"&&document.addEventListener("DOMContentLoaded",()=>{x(window)}),{collect:x,clear:f}}));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rebilly/lead-source-tracker",
-    "version": "8.28.3",
+    "version": "8.29.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%",
@@ -19,10 +21,11 @@
     "devDependencies": {
         "@rebilly/eslint-config": "*",
         "express": "^5.1.0",
-        "vite": "^5.4.21",
-        "vite-plugin-commonjs": "^0.10.4"
+        "vite": "^6.4.3",
+        "vite-plugin-commonjs": "^0.10.4",
+        "vitest": "^4.1.0"
     },
     "dependencies": {
-        "js-cookie": "^3.0.7"
+        "js-cookie": "^3.0.8"
     }
 }