Quickstart

Enable referrals in the dashboard

Open your server's dashboard → the Referrals tab (/dashboard/<game>/<server>/referrals). Flip Enable referrals on and save.

Enabling mints your per-server signing secret — the HMAC key every inbound event is signed with. The link https://mmolove.com/r/<your-server>?ref=<code> goes live immediately.

Copy your secret and set the registration URL

Two fields on that same tab:

• Signing secret — click Generate secret (or Rotate secret) to reveal it. It's shown once; copy it now and store it where your server can read it (env var, secrets manager — never the browser or game client).
• Registration URL — your sign-up page, e.g. https://your-server.example/register. MMOLove appends ?mmref=<token> to it when it redirects a referred player. It must be a public https:// URL.

You'll also pick an identity field (username / account / character / email) — the field you'll use in-game to resolve who to reward. MMOLove only stores the choice; you do the granting.

Drop in the kit

Grab the single-file helper for your stack and set your SECRET + SERVER_ID:

Your SERVER_ID is the MMOLove server id — copy it from the Referrals tab.

Capture the mmref token at registration

When a referred player lands on your registration page, the token is in the query string (and in a first-party mmref cookie as a fallback). Read it and store it against the new account — it's the bond you echo back in the next step.

$mmref = $_GET['mmref'] ?? ($_COOKIE['mmref'] ?? null);
// Persist $mmref on the new account row.

Fire registered — mint the anchor

As soon as the account exists, sign and POST a registered event. This binds the referrer to this referee (first-touch) and mints the durable referral_id.

mmolove_send_event($SECRET, $SERVER_ID, 'registered', [
    'token'            => $mmref,                 // the captured token
    'referee_identity' => $newPlayerId,           // your stable id for the referee
    'server_event_id'  => 'reg-' . $newPlayerId,  // idempotency key
]);

A 200 with { "ok": true, "referral_id": "...", "state": "registered" } means it landed. (referee_identity is required on registered — it's the anchor key.)

Send a test event and watch the log

Before relying on real traffic, prove the wiring end-to-end. On the Referrals tab, click Send test event — it fires a signed payload with test: true, which MMOLove fully signature-verifies but never writes. A 200 with { "ok": true, "test": true } confirms your secret + header are correct.

Then scroll to the Delivery log on that same tab: your real registered event from the previous step appears there, newest first, with its type, the referral's current state, and a payload snippet. That's the full loop.