@affiliateo/web 2.1.0 → 2.3.0

package/README.md

@@ -171,7 +171,11 @@ attributes become metadata (kebab-case → snake_case, up to 10 params).
 </section>
 ```
 
-Fires once when the section becomes 50%+ visible. Great for landing pages
+Fires once when 10% of the section enters the viewport (combined with a
+small bottom-edge rootMargin so it doesn't fire on sections barely peeking
+up from the bottom of the screen). The lower threshold catches tall
+sections like pricing pages with comparison tables that would otherwise
+top out under 50% intersection and never fire. Great for landing pages
 where you want to know which sections convert.
 
 ### Goal naming rules
@@ -194,13 +198,15 @@ export default function AuthBoundary({ children }) {
   const { identify } = useAffiliateRef()
   const user = useUser()
   useEffect(() => {
-    if (user) identify(user.id, { email: user.email })
+    if (user) identify(user.id)
   }, [user])
   return <>{children}</>
 }
 ```
 
 Idempotent. safe to fire on every page load while a user is signed in.
+**user_id only.** The SDK does not accept, collect, or transmit email
+or any other PII.
 
 ## API
 
@@ -217,8 +223,7 @@ Props:
 React hook that returns `{ refCode, visitorId, track, identify }`.
 
 - `track(eventName, metadata?)`. fire a custom goal
-- `identify(userId, opts?)`. link this visitor to a merchant user_id;
-  `opts.email` optional
+- `identify(userId)`. link this visitor to a merchant user_id (no PII)
 
 ### `getAttribution()`
 

package/dist/provider.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useRef, useState } from 'react';
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
@@ -69,6 +69,13 @@ export function getAttribution() {
         data.affiliateo_campaign_id = cid;
     return data;
 }
+// Double-mount detection. The host app should mount AffiliateoProvider
+// exactly once near the root. Mounting twice produces double pageviews,
+// duplicate history.pushState patches stacking on each other, and
+// competing session_end signals. We can't always *prevent* the second
+// mount (host has the call sites) but we can shout in dev so the
+// mistake is visible.
+let providerMountCount = 0;
 export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
     const [state, setState] = useState({
         refCode: null,
@@ -77,11 +84,108 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         identify: asyncNoop,
     });
     const apiBase = (apiUrl || DEFAULT_API_URL).replace(/\/$/, '');
+    // campaignIdRef stays current so callbacks defined inside useEffect
+    // always read the latest value, even after a prop change. Closures
+    // captured by host-side `useRef` no longer drift to a stale id.
     const campaignIdRef = useRef(campaignId);
+    campaignIdRef.current = campaignId;
+    // Mint visitorId once and put it in a ref so it survives campaignId
+    // prop changes without forcing a re-fetch / re-mint cycle. Same UUID
+    // for the lifetime of the localStorage entry across the whole tab.
+    const visitorIdRef = useRef(null);
+    // track + identify are defined OUTSIDE the route-effect so they
+    // close over refs (campaignIdRef, visitorIdRef) rather than the
+    // captured-once values from inside the effect. A consumer caching
+    // `track` keeps firing under the LATEST (campaignId, visitorId).
+    const track = useCallback(async (eventName, metadata) => {
+        try {
+            if (typeof window === 'undefined')
+                return;
+            if (!eventName || typeof eventName !== 'string')
+                return;
+            const name = eventName.trim().toLowerCase();
+            if (!name || name.length > 64 || !/^[a-z0-9_:-]+$/.test(name))
+                return;
+            const cid = campaignIdRef.current;
+            const vid = visitorIdRef.current;
+            if (!cid || !vid)
+                return;
+            const payload = {
+                type: 'custom',
+                campaign_id: cid,
+                visitor_id: vid,
+                event_name: name,
+            };
+            if (metadata && typeof metadata === 'object')
+                payload.metadata = metadata;
+            const data = JSON.stringify(payload);
+            const endpoint = `${apiBase}/api/v1/web/event`;
+            if (navigator.sendBeacon) {
+                navigator.sendBeacon(endpoint, new Blob([data], { type: 'application/json' }));
+            }
+            else {
+                fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: data,
+                    keepalive: true,
+                }).catch(() => { });
+            }
+        }
+        catch { /* swallow */ }
+    }, [apiBase]);
+    // identify(userId). user_id only — the SDK does NOT accept, collect,
+    // or transmit email or any other PII. Cross-device stitching uses the
+    // merchant's own user_id; we never touch identifying personal data.
+    const identify = useCallback(async (userId) => {
+        try {
+            if (typeof window === 'undefined')
+                return;
+            if (!userId || typeof userId !== 'string')
+                return;
+            const uid = userId.trim();
+            // Cap at 128 chars (matches the server). Covers every common
+            // foreign user-id shape: uuid, ulid, mongo objectId, auth0 sub,
+            // firebase uid, supabase uuid.
+            if (!uid || uid.length > 128)
+                return;
+            const cid = campaignIdRef.current;
+            const vid = visitorIdRef.current;
+            if (!cid || !vid)
+                return;
+            const payload = {
+                campaign_id: cid,
+                visitor_id: vid,
+                user_id: uid,
+            };
+            const data = JSON.stringify(payload);
+            const url = `${apiBase}/api/v1/web/identify`;
+            if (navigator.sendBeacon) {
+                navigator.sendBeacon(url, new Blob([data], { type: 'application/json' }));
+            }
+            else {
+                fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: data,
+                    keepalive: true,
+                }).catch(() => { });
+            }
+        }
+        catch { /* swallow */ }
+    }, [apiBase]);
     const sentRef = useRef(false);
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
+        // Mount-count warning. Fires only when more than one Provider has
+        // ever mounted in the page lifetime. Dev-only; production swallows
+        // the warning to avoid noise in real merchant consoles.
+        providerMountCount += 1;
+        if (providerMountCount > 1 && process.env.NODE_ENV !== 'production') {
+            // eslint-disable-next-line no-console
+            console.warn('[Affiliateo] AffiliateoProvider mounted more than once. Mount it exactly once near the root of your app, or pageviews will double-fire.');
+        }
         // Get or create visitor ID
         let vid = lsGet(LS_VISITOR_ID);
         if (!vid) {
@@ -89,6 +193,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         }
         lsSet(LS_VISITOR_ID, vid);
         lsSet(LS_CAMPAIGN_ID, campaignIdRef.current);
+        visitorIdRef.current = vid;
         // Read ref from URL params or localStorage
         const params = new URLSearchParams(window.location.search);
         const ref = params.get('ref') || params.get('via') || params.get('source')
@@ -97,83 +202,6 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             lsSet(LS_REF, ref);
         }
         const endpoint = `${apiBase}/api/v1/web/event`;
-        // track() fires custom goals (signup_completed, trial_started, etc.).
-        // Best-effort: a failed network call is swallowed so analytics never
-        // throws in the host app. Goal-name validation matches the server's
-        // gate so merchants get instant feedback if they pass garbage.
-        const track = async (eventName, metadata) => {
-            try {
-                if (!eventName || typeof eventName !== 'string')
-                    return;
-                const name = eventName.trim().toLowerCase();
-                if (!name || name.length > 64 || !/^[a-z0-9_:-]+$/.test(name))
-                    return;
-                const payload = {
-                    type: 'custom',
-                    campaign_id: campaignIdRef.current,
-                    visitor_id: vid,
-                    event_name: name,
-                };
-                if (metadata && typeof metadata === 'object')
-                    payload.metadata = metadata;
-                const data = JSON.stringify(payload);
-                // sendBeacon doesn't accept a response, but for custom goals we
-                // also don't care about it. fire-and-forget is exactly the
-                // semantic we want. Same fetch fallback shape as pageview/sendEnd.
-                if (navigator.sendBeacon) {
-                    navigator.sendBeacon(endpoint, new Blob([data], { type: 'application/json' }));
-                }
-                else {
-                    fetch(endpoint, {
-                        method: 'POST',
-                        headers: { 'Content-Type': 'application/json' },
-                        body: data,
-                        keepalive: true,
-                    }).catch(() => { });
-                }
-            }
-            catch { /* swallow */ }
-        };
-        // identify() links the anonymous visitor_id to the merchant's
-        // user_id once they sign in. Required for cross-device / cross-
-        // subdomain funnels to stitch properly. POSTs to /api/v1/web/identify
-        // which updates visitors.user_id (+ optional user_email).
-        //
-        // Idempotent: safe to call on every page load. We only fire if a
-        // non-empty userId is provided; calls with a blank id are silently
-        // swallowed so merchants who guard the call with `if (user)` and
-        // pass a falsy id during hydration don't get errors.
-        const identify = async (userId, opts) => {
-            try {
-                if (!userId || typeof userId !== 'string')
-                    return;
-                const uid = userId.trim();
-                if (!uid || uid.length > 256)
-                    return;
-                const email = opts?.email ? String(opts.email).trim().slice(0, 320) : undefined;
-                const payload = {
-                    campaign_id: campaignIdRef.current,
-                    visitor_id: vid,
-                    user_id: uid,
-                };
-                if (email)
-                    payload.user_email = email;
-                const data = JSON.stringify(payload);
-                const url = `${apiBase}/api/v1/web/identify`;
-                if (navigator.sendBeacon) {
-                    navigator.sendBeacon(url, new Blob([data], { type: 'application/json' }));
-                }
-                else {
-                    fetch(url, {
-                        method: 'POST',
-                        headers: { 'Content-Type': 'application/json' },
-                        body: data,
-                        keepalive: true,
-                    }).catch(() => { });
-                }
-            }
-            catch { /* swallow */ }
-        };
         setState({ refCode: ref, visitorId: vid, track, identify });
         function beacon(payload) {
             const data = JSON.stringify(payload);
@@ -278,10 +306,19 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             for (const { name, value } of Array.from(el.attributes)) {
                 if (!name.startsWith('data-affiliateo-goal-'))
                     continue;
+                // Skip the bare "data-affiliateo-goal" attribute itself
+                // (slice would produce an empty key).
+                if (name === 'data-affiliateo-goal')
+                    continue;
                 if (count >= 10)
                     break;
                 const key = name.slice('data-affiliateo-goal-'.length).replace(/-/g, '_');
-                if (key && value) {
+                // Skip the reserved `event` key so an attribute like
+                // `data-affiliateo-goal-event="x"` can't override the actual
+                // goal name when the SDK / server folds metadata.event in.
+                if (!key || key === 'event')
+                    continue;
+                if (value) {
                     meta[key] = String(value).slice(0, 255);
                     count++;
                 }
@@ -294,8 +331,26 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
         // the viewport. Use IntersectionObserver (cheap, off the scroll hot
         // path) and unobserve after the first fire so the same element can't
         // double-count if the user scrolls back up.
+        //
+        // Threshold: 0.1 (was 0.5). 50% visibility is unreachable for tall
+        // sections — a 1600px pricing section in an 800px viewport tops out
+        // at ~50% intersection ratio, so the observer's threshold was either
+        // a bare miss (section maxes at 49%) or a brittle hit. Funnel steps
+        // tied to those sections silently dropped from every merchant's
+        // conversion count without anyone noticing the section was even
+        // being rendered. 0.1 fires when 10% of the section is visible,
+        // which on a typical laptop is "the user has scrolled enough that
+        // the section is meaningfully on screen" without firing on sections
+        // that barely peek up from the bottom edge.
+        //
+        // rootMargin: trim the bottom 10% of the viewport from the trigger
+        // zone so a section creeping up from the very bottom of the screen
+        // doesn't fire instantly. The user has to scroll enough that the
+        // section is starting to settle into the main visible area, which
+        // matches a human's intuitive sense of "I've reached that section."
         const scrollFired = new WeakSet();
         let scrollObserver = null;
+        let scrollMo = null;
         if (typeof IntersectionObserver !== 'undefined') {
             scrollObserver = new IntersectionObserver((entries) => {
                 for (const entry of entries) {
@@ -309,7 +364,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
                         track(goal);
                     scrollObserver?.unobserve(entry.target);
                 }
-            }, { threshold: 0.5 });
+            }, { threshold: 0.1, rootMargin: '0px 0px -10% 0px' });
             // Observe everything that exists at mount time.
             document.querySelectorAll('[data-affiliateo-scroll]').forEach((el) => {
                 scrollObserver?.observe(el);
@@ -317,7 +372,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
             // SPA-rendered sections that appear later get observed via
             // MutationObserver. Cheap because we only scan added nodes, not
             // the whole tree on each mutation.
-            const mo = new MutationObserver((mutations) => {
+            scrollMo = new MutationObserver((mutations) => {
                 for (const m of mutations) {
                     m.addedNodes.forEach((node) => {
                         if (!(node instanceof Element))
@@ -328,19 +383,19 @@ export function AffiliateoProvider({ campaignId, apiUrl, children, }) {
                     });
                 }
             });
-            mo.observe(document.body, { childList: true, subtree: true });
-            scrollObserver._mo = mo;
+            scrollMo.observe(document.body, { childList: true, subtree: true });
         }
         return () => {
             document.removeEventListener('visibilitychange', onVisibilityChange);
             window.removeEventListener('pagehide', sendEnd);
             window.removeEventListener('popstate', onUrlChange);
             document.removeEventListener('click', onDocClick);
-            scrollObserver?._mo?.disconnect();
+            scrollMo?.disconnect();
             scrollObserver?.disconnect();
             history.pushState = origPushState;
             history.replaceState = origReplaceState;
+            providerMountCount = Math.max(0, providerMountCount - 1);
         };
-    }, [campaignId, apiBase]);
+    }, [apiBase, track, identify]);
     return (_jsx(AffiliateoContext.Provider, { value: state, children: children }));
 }

package/dist/types.d.ts

@@ -27,13 +27,11 @@ export interface AffiliateoContextValue {
      *  both events resolve to the same user_id and the funnel reports a
      *  single converted person.
      *
-     *  Idempotent: safe to call on every page load. Optional email is
-     *  bounded to 320 chars (RFC 5321 max).
+     *  Idempotent: safe to call on every page load. user_id only —
+     *  the SDK does not accept or transmit email or any other PII.
      *
      *  Example:
      *    const { identify } = useAffiliateRef()
-     *    useEffect(() => { if (user) identify(user.id, { email: user.email }) }, [user]) */
-    identify: (userId: string, opts?: {
-        email?: string;
-    }) => Promise<void>;
+     *    useEffect(() => { if (user) identify(user.id) }, [user]) */
+    identify: (userId: string) => Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affiliateo/web",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Affiliateo web SDK — affiliate attribution and tracking for web apps",
   "main": "dist/index.js",
   "module": "dist/index.js",