In short: the module is the source of a signal, not a fulfilment engine. Identity, rate-limiting, anti-abuse, tax/compliance reporting, and ledger integrity all live on your side.

Depending on the module and your setup, the completion signal arrives by one or both of these channels. Both carry the same result data.

A · postMessage event (iframe → your page)

The module sends a window.parent.postMessage(...) when the player finishes. Fires once per attempt; a fresh attempt fires again with new values.

// completion — fires on success and on the fail screen
{
  type:         "module:case-complete",
  caseId:       "CSC-001",
  product:      "crucible" | "cascade" | "simulator",
  tier:         "A" | "B" | "C",
  success:      true,        // false on fail screen
  score:        52,
  maxScore:     60,
  percent:      71,
  points:       587,
  streakMax:    5,
  achievements: 4,
  timestamp:    1730000000000
}

A second module:reward-eligible event fires immediately after, in the same tick, only when reward trigger is enabled, the attempt succeeded, and the threshold was met. It carries an opaque rewardLabel you map back to your reward catalog.

B · URL parameters (module → sponsor redemption page)

Used by Cascade-style reward redemption: the player clicks “Claim my reward” and the module opens the sponsor’s page with the result appended as query parameters. The sponsor’s page reads them and decides what to grant.

https://sponsor.example.com/reward/?caseId=CSC-001&drugName=TYK2i-DEMO
   &points=587&percent=71&streakMax=5
   &achievements=4&tier=C&totalAttempts=12

Paste this on the page where you embed the module. One listener handles every product.

<iframe id="rv-module"
  src="https://www.rheumaview.com/m/CSC-001/"
  width="900" height="940"
  style="border:0;max-width:100%;" loading="lazy"></iframe>

<script>
window.addEventListener("message", (e) => {
  // 1 · origin check — required
  if (e.origin !== "https://www.rheumaview.com") return;
  if (!e.data || typeof e.data !== "object") return;

  // 2 · reward-eligible — credit the player using YOUR session
  if (e.data.type === "module:reward-eligible") {
    fetch("/api/rv/credit", {
      method: "POST", credentials: "include",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        caseId: e.data.caseId, score: e.data.score,
        rewardLabel: e.data.rewardLabel
      })
    });
    return;
  }

  // 3 · case-complete — analytics, completion tracking, leaderboards
  if (e.data.type === "module:case-complete") {
    yourAnalytics.track("rv_complete", e.data);
  }
});
</script>

The module has no idea who the player is. You do.

Pattern A — your own session (recommended)

Your page already requires login, so when your listener runs, the browser carries your authenticated session. Your credit endpoint reads it, looks up the user, and credits them. The module never participates in identity.

Pattern B — echo a token through the module

If your session cookie is not available in the module’s context, generate a short-lived opaque token, pass it via the URL (?uid=opaque_token), and the module echoes it back as echoToken in the payload. Your endpoint maps the token to the user.

For high-value rewards your fulfilment endpoint must: require an authenticated session; be idempotent on (userId, caseId); rate-limit per user per window; and log every attempt, accepted or rejected, for audit.

The module emits a technical signal and collects no PII. The completion and reward-eligible payloads contain no user-identifying fields. Linking a real person to an attempt happens entirely on your platform, under your privacy notice and legal basis.

1. Embed the module on a staging page and open the DevTools console.
2. Add the listener with extra console.log() calls.
3. Pass the module to a clearing score — confirm case-complete (success:true) then reward-eligible with the expected label.
4. Re-run below threshold — case-complete fires, reward-eligible does not.
5. Trigger the fail screen — case-complete fires with success:false; no eligibility.
6. Curl your credit endpoint with no session — confirm it rejects the request.
7. Hit it twice with the same (userId, caseId) — confirm the duplicate is rejected.