Overview
How the MMOLove Referral Kit works — the conduit/affiliate model where we track and you grant the reward.
The Referral Kit lets you reward the players who bring their friends to your server. It follows a conduit / affiliate-network model:
- MMOLove tracks the journey — the share link click, the signed token, and the lifecycle events your kit reports.
- You grant the reward — in-game, on your terms. You decide what "qualified" means (reached level 10, played 2 hours, made a purchase) and you hand out the loot. MMOLove never touches your economy.
This split keeps the model clean: we own attribution, you own the payout.
New here? Go straight to the Quickstart for the 5-minute path: enable referrals, copy your secret, fire your first event, and watch it land in the delivery log.
How the pieces fit
The share link — /r/<server>
A player shares their personal link, e.g. https://mmolove.com/r/your-server?ref=<their-code>.
When someone follows it, MMOLove:
- records the click,
- mints a signed
mmreftoken (HMAC, server-bound, 90-day expiry), - drops a first-party
mmrefcookie, and - redirects to your registration URL with
?mmref=<token>appended.
Capture the mmref at registration
Your registration page reads mmref from the query string (or the cookie
fallback) and stores it against the new account. This is the link between "who
referred whom" — keep it.
Report registered — the anchor
As soon as the referee creates an account, your server sends a signed
POST /api/referral/events with event: "registered", the mmref token, and the
referee's identity. This mints the referral anchor (first-touch: the first
referrer to register a given referee wins).
Report qualified — the milestone
When the referee hits your qualification milestone, send another signed
POST /api/referral/events with event: "qualified". MMOLove advances the
referral and credits the referrer in the analytics + leaderboard. You then grant
the in-game reward.
The lifecycle
clicked ──registered──▶ registered ──qualified──▶ qualified
│ │
└────── reversed / expired ─┘- clicked — the
/r/<server>link was followed (a click row +mmreftoken exist). - registered — your
registeredevent minted the anchor (referrer ↔ referee bound). - qualified — your
qualifiedevent fired at the milestone; reward time. - reversed — an owner reversal (refund/chargeback/abuse). Modelled; not acted on by the Phase-2 endpoint yet.
- expired — the attribution window elapsed. Time-driven; modelled.
Read next
Quickstart
Zero to a verified event in 5 minutes.
Concepts
The lifecycle, the anchor, first-touch, and the attribution window.
REST reference
The authoritative endpoint contract.
Signing & security
The exact HMAC scheme + the #1 integration bug.
Events reference
Per-event payload schemas.
Errors & troubleshooting
Every status code, with cause + fix.
Testing & sandbox
Dry-run with test:true before going live.
SDK guides
Complete copy-paste integrations per stack.
The REST contract is the source of truth
The SDKs and the snippets in the SDK guides are
thin, signed-HTTP wrappers — convenience, not magic. The authoritative behaviour
(fields, signing, replay window, idempotency, status codes) is the REST
contract: POST /api/referral/events. When
in doubt, the endpoint wins.
Skip the boilerplate with an SDK: npm i @mmolove/referral,
pip install mmolove-referral, dotnet add package MMOLove.Referral, or the
single-file PHP mmolove-referral.php drop-in. You don't need one — any language
that can compute an HMAC-SHA256 and make an HTTPS POST can integrate directly.