@affitor/tracker

@affitor/tracker

Official JavaScript/TypeScript SDK for Affitor affiliate tracking. A Promise-based wrapper around the Affitor tracker script, inspired by @stripe/stripe-js.

Install

npm install @affitor/tracker

Entry Points

The SDK provides two entry points for different use cases:

Entry Point	Import	Best For
@affitor/tracker	import { loadAffitor } from '@affitor/tracker'	Any JS/TS application
@affitor/tracker/react	import { AffitorProvider, useAffitor } from '@affitor/tracker/react'	React / Next.js apps

@affitor/tracker — Core SDK

loadAffitor(programId, options?)

Loads the Affitor tracker script and returns a Promise that resolves to the tracker instance.

• Singleton — calling loadAffitor multiple times returns the same Promise
• SSR-safe — resolves to null on the server
• Guaranteed — the instance is always ready when the Promise resolves

import { loadAffitor } from '@affitor/tracker';

const affitor = await loadAffitor('59');

Options

Option	Type	Default	Description
env	'production' | 'uat' | 'local'	'production'	Environment preset (selects the tracker script URL)
debug	boolean	false	Enable debug mode (verbose console logs, cookie verification)
scriptUrl	string	—	Custom script URL (overrides env preset)

Environment Presets

env	Script URL
'production'	https://api.affitor.com/js/affitor-tracker.js
'uat'	https://uat-affitor-cms.vanilla-ott.com/js/affitor-tracker-uat.js
'local'	http://localhost:1337/js/affitor-tracker-local.js

// Production (default)
const affitor = await loadAffitor('59');

// Local development with debug
const affitor = await loadAffitor('29', { env: 'local', debug: true });

// UAT
const affitor = await loadAffitor('29', { env: 'uat' });

// Custom URL (overrides env)
const affitor = await loadAffitor('29', { scriptUrl: 'https://my-cdn.com/tracker.js' });

Methods

Once loaded, the affitor instance provides these methods:

Method	Description
signup(customerKey, email)	Track a signup event. Takes the user's ID and email as positional args. Returns a Promise.
trackLead(data)	Deprecated. Alias for signup(). Accepts { email, user_id }. Use signup() instead.
trackTest(data?)	Send a test event to verify tracking is working.
redirectToCheckout(params)	Redirect the user to the Affitor-powered checkout page.

Properties

Property	Type	Description
customerCode	string | null	The affiliate customer code from cookie
affiliateUrl	string | null	The affiliate referral URL from cookie
hasAffiliateAttribution	boolean	Whether the current visitor was referred by an affiliate
debugMode	boolean	Whether debug mode is enabled
programId	number	The advertiser program ID

Example: Track Signup

import { loadAffitor } from '@affitor/tracker';

async function handleSignup(email: string, password: string) {
  // 1. Create the user account
  const { data } = await supabase.auth.signUp({ email, password });

  // 2. Track the signup — awaits script load, guaranteed to fire
  if (data.user) {
    const affitor = await loadAffitor('59');
    await affitor?.signup(data.user.id, data.user.email);
  }

  // 3. Navigate to dashboard
  router.push('/dashboard');
}

Example: Redirect to Checkout

import { loadAffitor } from '@affitor/tracker';

async function handleUpgrade() {
  const affitor = await loadAffitor('59');
  affitor?.redirectToCheckout({
    price: 19.99,
    programId: 59,
  });
}

@affitor/tracker/react — React Hooks

The React entry point provides two patterns: Provider + hook and standalone hook.

Pattern A: AffitorProvider + useAffitor()

Best when your whole app needs access to the tracker state (e.g. showing referral badges).

import { AffitorProvider, useAffitor } from '@affitor/tracker/react';

// 1. Wrap your app (layout.tsx or _app.tsx)
export default function RootLayout({ children }) {
  return (
    <AffitorProvider programId="59">
      {children}
    </AffitorProvider>
  );
}

// 2. Read tracker state in any component
function ReferralBadge() {
  const affitor = useAffitor();

  if (!affitor?.hasAffiliateAttribution) return null;

  return <span>Referred by a partner!</span>;
}

AffitorProvider Props

Prop	Type	Required	Description
programId	string | number	Yes	Your Affitor program ID
debug	boolean	No	Enable debug mode
scriptUrl	string	No	Custom script URL

useAffitor()

Returns AffitorInstance | null. Returns null while the SDK is loading.

Important: useAffitor() is best for reading tracker state in the UI (e.g. hasAffiliateAttribution, customerCode). For critical tracking events like signup, use await loadAffitor() directly instead — see Which approach should I use? below.

Pattern B: useLoadAffitor() (Standalone)

Use this when you don't need a provider — the hook loads the SDK on mount.

import { useLoadAffitor } from '@affitor/tracker/react';

function MyComponent() {
  const affitor = useLoadAffitor('59', { debug: true });

  return (
    <div>
      {affitor?.hasAffiliateAttribution && <p>Partner referral detected</p>}
    </div>
  );
}

Which approach should I use?

For tracking events (signup, redirectToCheckout)

Always use await loadAffitor() directly. This guarantees the script is loaded before the event fires. Critical events must never be silently skipped.

// GOOD — guaranteed to fire
const affitor = await loadAffitor('59');
await affitor?.signup(userId, email);

// BAD — affitor could be null if script still loading
const affitor = useAffitor();
await affitor?.signup(userId, email); // silently skipped if null

For reading tracker state in UI

Use useAffitor() or useLoadAffitor(). If the value is null momentarily while loading, the UI simply doesn't render that part yet. No data is lost.

// GOOD — fine for UI, gracefully handles loading state
const affitor = useAffitor();
return affitor?.hasAffiliateAttribution ? <Badge /> : null;

Summary

Use Case	Approach	Why
signup on registration	await loadAffitor()	Must not be lost — awaits script load
redirectToCheckout	await loadAffitor()	Must not be lost — awaits script load
Show referral badge in UI	useAffitor()	OK to show nothing while loading
Display customer code	useAffitor()	OK to show nothing while loading
Check hasAffiliateAttribution for conditional UI	useAffitor()	OK to show nothing while loading

Migrating from Script Tag

If you're currently using the <script> tag approach:

Before (script tag)

<script src="https://api.affitor.com/js/affitor-tracker.js"
        data-affitor-program-id="59"></script>

<script>
  // Must check if loaded, use queue fallback, handle timing manually
  if (window.affitor) {
    window.affitor.trackLead({ email, user_id });
  } else {
    window.affitorQueue = window.affitorQueue || [];
    window.affitorQueue.push(['trackLead', { email, user_id }]);
  }
</script>

After (npm SDK)

import { loadAffitor } from '@affitor/tracker';

// No timing issues — awaits script load automatically
const affitor = await loadAffitor('59');
await affitor?.signup(userId, email);

No more:

• Manual if (window.affitor) checks
• Queue fallback code (affitorQueue.push)
• Race conditions between script load and event firing
• (window as any) type casting in TypeScript

API Reference

loadAffitor(programId, options?)

Parameter	Type	Description
programId	string | number	Your Affitor program ID
options.env	'production' | 'uat' | 'local'	Environment preset
options.debug	boolean	Enable debug mode
options.scriptUrl	string	Custom script URL (overrides env)

Returns: Promise<AffitorInstance | null>

AffitorInstance

Method / Property	Type	Description
signup(customerKey, email)	(customerKey: string, email: string) => Promise<void>	Track a signup event
trackLead(data)	(data: TrackLeadData) => void	Deprecated. Alias for signup().
trackTest(data?)	(data?: TrackTestData) => void	Send test event
redirectToCheckout(params)	(params: RedirectToCheckoutParams) => void	Redirect to checkout
customerCode	string | null	Affiliate customer code
affiliateUrl	string | null	Affiliate referral URL
hasAffiliateAttribution	boolean	Has affiliate attribution
debugMode	boolean	Debug mode enabled
programId	number	Program ID

TrackLeadData

Field	Type	Required	Description
email	string	Yes	User's email
user_id	string	Yes	Your app's user ID (critical for payment attribution)
additional_data	Record<string, unknown>	No	Extra metadata

TrackTestData

Field	Type	Required	Description
step_id	string	No	Step identifier (default: 'pageview')
message	string	No	Test message
user_id	string	No	User ID

RedirectToCheckoutParams

Field	Type	Required	Description
price	number	No	Price amount
programId	string | number	No	Override program ID

License

MIT