Web SDK

For web products: capture the referral when the visitor lands, then bind it to the user at signup. Works with any billing provider — see the Web SaaS guide for the end-to-end flow.

Integrate MyAppAffiliate into my project.

Documentation (read these first, they are the source of truth):
- Page: https://docs.myappaffiliate.com/sdk-web.md
- Full docs index: https://docs.myappaffiliate.com/llms.txt

Task: Add the MyAppAffiliate Web SDK to my site: install the package, start it once in my app shell so it auto-captures ?via= referral codes including on client-side route changes, and identify the user at signup with the same id my billing provider reports.

Rules:
- Follow the documented API exactly — no invented method names, endpoints, parameters or field names.
- Match the conventions already used in my codebase.
- Ask me for my SDK key instead of guessing, and never hard-code it — read it from config/environment.
- Do NOT set an API base URL anywhere. Every SDK compiles the production host in; a staging or self-hosted host belongs in a build setting, not in code.
- Tell me afterwards which steps I still have to do by hand (dashboard settings, capabilities, webhook configuration).

Install

Script tag — no build tooling, no inline JavaScript. Best for a landing page:

<script
  src="https://cdn.jsdelivr.net/npm/@myappaffiliate/sdk-web@0/dist/sdk.js"
  data-api-key="pk_live_…"
  async
></script>

The tag starts the SDK itself and puts the same surface on window.myAppAffiliate, so step 1 is already done and step 2 is one line of inline script. @0 tracks the latest 0.x; pin @0.2.0 if you want a frozen bundle.

npm — for app frontends:

npm i @myappaffiliate/sdk-web

1. Start it

import { myAppAffiliate } from "@myappaffiliate/sdk-web";
 
myAppAffiliate.start("pk_live_…");

That is the whole call — no host, no options. Put it in your app shell, root layout, or a <script type="module"> on the landing page.

It is safe to call on the server: every function is a no-op when window is undefined, so Next.js / Remix / SvelteKit need no typeof window guard.

2. Identify the user at signup

Call this when the account is created. The id must be the same string your billing provider reports back to us — your Stripe metadata.customer_user_id, Paddle custom data, or the provider's own customer id. See Billing & Webhooks.

await myAppAffiliate.identify(user.id);

That's the whole integration. (You can do this server-side instead with the Node SDK's trackSignup.)

What start captures, automatically

On the current URL, and again on every client-side route change:

• ?via=LUMI (also ?ref=, ?maa_code=, ?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. If the network call fails, the code stays persisted and is retried on the next start.

SPAs need nothing extra. The SDK hooks pushState/replaceState/popstate, so a creator linking to a deep route (/pricing?via=LUMI) is captured whether or not that route was the entry page. Turn it off with spa: false and call capture() yourself.

Optional

myAppAffiliate.applyCode("LUMI");             // a referral-code field at checkout
myAppAffiliate.capture();                     // re-scan the URL manually
myAppAffiliate.attribute("https://…?via=…");  // claim from an explicit URL
myAppAffiliate.attributedAffiliateId();       // string | null, for your own UI
myAppAffiliate.reset();                       // on logout / account deletion

Staging or self-hosted API, custom storage, debug logging:

myAppAffiliate.start({
  apiKey: "pk_live_…",
  apiBaseUrl: "https://staging.example.com",  // or globalThis.MAA_API_BASE_URL
  storage: myCookieStore,                     // { get, set, remove }
  autoCapture: true,
  spa: true,
  debug: true,
});

API

Every function is also a named export (import { start, identify } from …) if you prefer that to the namespace.

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.