@affiliateo/web 4.4.0 → 4.5.0

package/README.md

@@ -11,7 +11,7 @@ npm install @affiliateo/web
 ## Setup
 
 1. Connect your Stripe account on the Affiliateo dashboard
-2. Wrap your app in `<AffiliateoProvider>` with your campaign ID
+2. Wrap your app in `<AffiliateoProvider>` with your app ID
 3. At checkout time, call `getAttribution()` and pass the result to Stripe metadata
 
 ### Step 1. wrap your app
@@ -22,7 +22,7 @@ import { AffiliateoProvider } from '@affiliateo/web';
 
 export default function RootLayout({ children }) {
   return (
-    <AffiliateoProvider campaignId="YOUR_CAMPAIGN_ID">
+    <AffiliateoProvider appId="YOUR_APP_ID">
       {children}
     </AffiliateoProvider>
   );
@@ -53,7 +53,7 @@ async function handleCheckout() {
 }
 ```
 
-`getAttribution()` reads `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from `localStorage` and returns them as an object, ready to pass to Stripe.
+`getAttribution()` reads the stored attribution from `localStorage` and returns `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_app_id` as an object, ready to pass to Stripe.
 
 ### Step 3. in your checkout API route (server-side)
 
@@ -107,7 +107,7 @@ If you're not using React, use the tracking script directly instead of the provi
 
 ```html
 <script defer
-  data-campaign="YOUR_CAMPAIGN_ID"
+  data-app="YOUR_APP_ID"
   src="https://affiliateo.com/t.js"
 ></script>
 ```
@@ -118,7 +118,7 @@ Then in your checkout flow (vanilla JS):
 const attribution = {
   affiliateo_ref: localStorage.getItem('affiliateo_ref'),
   affiliateo_visitor_id: localStorage.getItem('affiliateo_visitor_id'),
-  affiliateo_campaign_id: localStorage.getItem('affiliateo_campaign_id'),
+  affiliateo_app_id: localStorage.getItem('affiliateo_campaign_id'), // stored under its legacy key
 };
 
 // Send to your server with the rest of your checkout payload
@@ -210,12 +210,12 @@ or any other PII.
 
 ## API
 
-### `<AffiliateoProvider campaignId="..." apiUrl?="...">`
+### `<AffiliateoProvider appId="..." apiUrl?="...">`
 
 React provider. Wrap your app once. Reads `?ref=` from URL, persists to localStorage, sends pageview events, sets up data-attribute + scroll listeners.
 
 Props:
-- `campaignId` (required): your Affiliateo campaign ID
+- `appId` (required): your Affiliateo app ID (`campaignId` still works as a deprecated alias)
 - `apiUrl` (optional): defaults to `https://affiliateo.com`
 
 ### `useAffiliateRef()`
@@ -227,7 +227,7 @@ React hook that returns `{ refCode, visitorId, track, identify }`.
 
 ### `getAttribution()`
 
-Client-side function. Returns an object with `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_campaign_id` from localStorage. Pass directly as Stripe `metadata`.
+Client-side function. Returns an object with `affiliateo_ref`, `affiliateo_visitor_id`, and `affiliateo_app_id` from localStorage. Pass directly as Stripe `metadata`.
 
 ## Framework support
 

package/dist/provider.d.ts

@@ -18,6 +18,6 @@ export declare function useAffiliateRef(): AffiliateoContextValue;
  * ```
  */
 export declare function getAttribution(): Record<string, string>;
-export declare function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }: AffiliateoConfig & {
+export declare function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }: AffiliateoConfig & {
     children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/provider.js

@@ -7,7 +7,10 @@ import { isDevHost } from './dev-host';
 const DEFAULT_API_URL = 'https://affiliateo.com';
 const LS_VISITOR_ID = 'affiliateo_visitor_id';
 const LS_REF = 'affiliateo_ref';
-const LS_CAMPAIGN_ID = 'affiliateo_campaign_id';
+// Storage key keeps its historical name: t.js and the WooCommerce tracker
+// write the same key, and renaming it would orphan existing visitors'
+// attribution mid-session.
+const LS_APP_ID = 'affiliateo_campaign_id';
 // Persistent opt-out flag (affiliateo_opt_out) —
 // when set to "true" the SDK silently noops every outbound call. Survives
 // page reloads. removed by optIn(). Checked at init time so a previously
@@ -149,13 +152,15 @@ export function getAttribution() {
     const data = {};
     const vid = lsGet(LS_VISITOR_ID);
     const ref = lsGet(LS_REF);
-    const cid = lsGet(LS_CAMPAIGN_ID);
+    const cid = lsGet(LS_APP_ID);
     if (vid)
         data.affiliateo_visitor_id = vid;
     if (ref)
         data.affiliateo_ref = ref;
+    // Key renamed from affiliateo_campaign_id in 4.5.0 — the Affiliateo
+    // webhook accepts both, so checkouts created by older SDKs keep working.
     if (cid)
-        data.affiliateo_campaign_id = cid;
+        data.affiliateo_app_id = cid;
     return data;
 }
 // Double-mount detection. The host app should mount AffiliateoProvider
@@ -165,7 +170,7 @@ export function getAttribution() {
 // 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, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }) {
+export function AffiliateoProvider({ appId, campaignId, apiUrl, allowedHostnames, allowLocalhost, allowIframe, allowFileProtocol, debug, flushInterval, maxQueueSize, autoCapturePageviews, children, }) {
     // Normalize autoCapturePageviews. Three shapes:
     //   - undefined / true / object → auto-capture ON (with object overrides)
     //   - false → auto-capture OFF entirely (host must call trackPageview)
@@ -211,12 +216,15 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             console.log('[Affiliateo] ' + msg);
     }, [debug]);
     const apiBase = (apiUrl || DEFAULT_API_URL).replace(/\/$/, '');
-    // campaignIdRef stays current so callbacks defined inside useEffect
+    // appId is the documented prop; campaignId is the pre-4.5.0 name kept as
+    // a working alias so upgrading the package never breaks an integration.
+    const resolvedAppId = appId ?? campaignId ?? '';
+    // appIdRef 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
+    const appIdRef = useRef(resolvedAppId);
+    appIdRef.current = resolvedAppId;
+    // Mint visitorId once and put it in a ref so it survives appId
     // 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);
@@ -230,7 +238,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
     // handlers, which fire after mount.
     const queueRef = useRef(null);
     // track + identify are defined OUTSIDE the route-effect so they
-    // close over refs (campaignIdRef, visitorIdRef) rather than the
+    // close over refs (appIdRef, 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) => {
@@ -246,7 +254,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             const name = eventName.trim().toLowerCase();
             if (!name || name.length > 64 || !/^[a-z0-9_:-]+$/.test(name))
                 return;
-            const cid = campaignIdRef.current;
+            const cid = appIdRef.current;
             const vid = visitorIdRef.current;
             if (!cid || !vid)
                 return;
@@ -285,7 +293,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             // firebase uid, supabase uuid.
             if (!uid || uid.length > 128)
                 return;
-            const cid = campaignIdRef.current;
+            const cid = appIdRef.current;
             const vid = visitorIdRef.current;
             if (!cid || !vid)
                 return;
@@ -315,7 +323,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
                 return;
             if (isOptedOut())
                 return;
-            const cid = campaignIdRef.current;
+            const cid = appIdRef.current;
             const vid = visitorIdRef.current;
             if (!cid || !vid)
                 return;
@@ -425,6 +433,13 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
+        // Neither appId nor the legacy campaignId alias was passed — nothing to
+        // attribute events to, so stay dormant instead of firing junk.
+        if (!appIdRef.current) {
+            // eslint-disable-next-line no-console
+            console.error('[Affiliateo] Missing appId — pass your app ID to <AffiliateoProvider appId="...">.');
+            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.
@@ -613,7 +628,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             vid = uuid();
         }
         lsSet(LS_VISITOR_ID, vid);
-        lsSet(LS_CAMPAIGN_ID, campaignIdRef.current);
+        lsSet(LS_APP_ID, appIdRef.current);
         visitorIdRef.current = vid;
         // Read ref. Cross-domain inbound wins, then fresh affiliate link
         // params (?ref / ?via / ?source), then stored value.
@@ -628,7 +643,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             visitorId: vid,
             track, identify, trackPageview, reset, optOut, optIn, flush,
         });
-        log('init', { campaign: campaignIdRef.current, visitor: vid, ref: ref || null });
+        log('init', { app: appIdRef.current, visitor: vid, ref: ref || null });
         // lastSendTime drives the visibility-refire heuristic below (refire a
         // pageview when a tab returns after the session window). Duplicate
         // suppression itself is the persisted same-URL throttle inside
@@ -661,7 +676,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             ended = false;
             queue.enqueue(endpoint, {
                 type: 'pageview',
-                campaign_id: campaignIdRef.current,
+                campaign_id: appIdRef.current,
                 visitor_id: vid,
                 session_id: getSessionId(),
                 url: href,
@@ -702,7 +717,7 @@ export function AffiliateoProvider({ campaignId, apiUrl, allowedHostnames, allow
             queue.flushOnUnload();
             const data = JSON.stringify({
                 type: 'session_end',
-                campaign_id: campaignIdRef.current,
+                campaign_id: appIdRef.current,
                 visitor_id: vid,
                 ref: ref || lsGet(LS_REF) || '',
             });

package/dist/types.d.ts

@@ -1,5 +1,11 @@
 export interface AffiliateoConfig {
-    campaignId: string;
+    /** Your Affiliateo app ID — shown in the dashboard when you create a
+     *  Web App Affiliate app. One of `appId` / `campaignId` is required;
+     *  `appId` wins when both are set. */
+    appId?: string;
+    /** @deprecated Affiliateo campaigns are now called apps — use `appId`.
+     *  Kept working so existing integrations don't break. */
+    campaignId?: string;
     /** Base URL for the API. Defaults to https://affiliateo.com */
     apiUrl?: string;
     /** Other domains that are part of the same merchant property and should
@@ -22,7 +28,7 @@ export interface AffiliateoConfig {
      *
      *  Example:
      *    <AffiliateoProvider
-     *      campaignId="..."
+     *      appId="..."
      *      allowedHostnames={['app.merchant.com', 'docs.merchant.com']}
      *    > */
     allowedHostnames?: string[];
@@ -36,7 +42,7 @@ export interface AffiliateoConfig {
      *  land server-side).
      *
      *  Example:
-     *    <AffiliateoProvider campaignId="..." allowLocalhost> */
+     *    <AffiliateoProvider appId="..." allowLocalhost> */
     allowLocalhost?: boolean;
     /** Allow tracking when the page is rendered inside an iframe. Defaults
      *  to false so scrapers, preview tools, and other sites embedding yours
@@ -55,7 +61,7 @@ export interface AffiliateoConfig {
      *  showing up?". Leave off in production.
      *
      *  Example:
-     *    <AffiliateoProvider campaignId="..." debug> */
+     *    <AffiliateoProvider appId="..." debug> */
     debug?: boolean;
     /** Allow tracking from pages served via the `file://` protocol (someone
      *  double-clicking a built HTML file instead of running a server).

package/package.json

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