Web SDK

For SaaS web products: capture the referral on the landing page, then bind it to the user at signup. Pairs with Stripe webhooks — see the full Web SaaS guide.

Install

Script tag (landing pages — captures automatically on load):

<script
  src="https://cdn.myappaffiliate.com/sdk.js"
  data-api-key="pk_live_…"
  data-base-url="https://api.myappaffiliate.com"
  async
></script>

npm (app frontends):

npm i @maa/sdk-web

import { maa } from "@maa/sdk-web";
 
maa.configure({ apiKey: "pk_live_…", baseUrl: "https://api.myappaffiliate.com" });

Attribute — automatic ?via= capture

On load (script tag) or on configure() (npm), the SDK inspects the current URL:

• ?via=LUMI (also ?ref= / ?code=) → referral-code attribution
• ?claim_token=<uuid> (or ?ct=) → click-claim attribution from a branded go. link

The winner is persisted in localStorage, so the referral survives navigation, a closed tab, and the days between landing and signup. You can also attribute manually:

maa.applyCode("LUMI");            // e.g. a "referral code" field at checkout
maa.attribute(window.location.href);

Identify the user (at signup)

Call this when the user account is created — use the same id you will put in Stripe's metadata.customer_user_id:

await maa.identify(user.id);

(Alternatively do this server-side with the Node SDK's trackSignup.)

SPA notes

• Client-side routers don't reload the page, so the script-tag auto-capture runs only once. Call maa.capture() (re-reads window.location) on route change if creators link to deep routes: e.g. in a React Router effect or Next.js useSearchParams handler.
• Capture is idempotent — re-running it with no via/claim_token present changes nothing, and the stored attribution is kept.
• Server-rendered pages need no special handling; the SDK runs client-side only.

API

The SDK persists a generated device id + attribution in localStorage. No cookies, no fingerprinting, first-party only. Network failures resolve to false/null — never an uncaught error on your page.