Handling the Exam Session Lifecycle: Tab Close, Refresh, and Network Drop

Why the exam session lifecycle needs handling at all

A real exam does not run in a single uninterrupted page view. Candidates refresh, close the tab by accident, lose Wi-Fi, hit the back button, or sit an exam that outlasts its session token. Each of those could, if handled badly, split one attempt into several partial reports, each billed separately and each missing part of the story. ProctorLink is built so that the common interruptions rejoin the same attempt instead. The one design rule you own is a stable attempt_id; the SDK and the server handle the rest.

import { ProctorLink } from '@proctorlink/sdk';

// attempt_id must be STABLE for the attempt. Derive it from your own
// attempt record, never from a random value generated on page load.
const attemptId = exam.attemptId;

// Mint on your backend. If this attempt already has an active session,
// the response comes back with resumed: true and the SAME session_id,
// so a refresh or a reopened tab rejoins instead of starting over.
const { session_id, session_jwt } = await mintSession({
  attempt_id: attemptId,
});

let session = ProctorLink.createSession({
  jwt: session_jwt,   // short-lived, origin-bound session token
  sessionId: session_id,
});

await session.start();   // rejoins the same attempt if one was active

If you are integrating from scratch, start with how to add proctoring to a web application for the full mint-start-report loop, then use this page for the edge cases that loop has to survive. For the wider choice between an SDK, a REST API, and an LMS plugin, see proctoring SDK vs API vs LMS plugin.

How does resume by attempt_id work?

Resume is the mechanism behind all of this. When you mint a session with an attempt_id that already has an active session, ProctorLink does not create a second one. It returns the existing session_id with a fresh token and resumed: true.

// POST /v1/sessions with the same attempt_id while a session is still active:
{
  "session_id": "6a7b18df70e4f8ecf2597b6f",
  "session_jwt": "eyJhbGciOi...",
  "expires_at": 1786443201,
  "resumed": true
}

So a candidate who refreshes, reconnects, or reopens the exam continues the same proctoring record instead of splitting into two partial ones, and you are billed once for the attempt rather than twice. For this to work, attempt_id must be stable for the attempt: derive it from your own attempt record, not from a random value generated on page load, or every refresh starts a new session. This is the same identity split explained in why proctoring runs in a cross-origin iframe: your backend holds the API key and mints, the browser only ever receives a short-lived token for one attempt.

How do I handle token expiry during a long exam?

The session token is short-lived, 2 hours by default. The clean approach is to avoid expiry altogether: set ttl_seconds at mint to your exam length plus a buffer, and read the returned expires_at rather than assuming your requested value was used, because out-of-range values are clamped. Keep token-expired as the safety net for exams that run longer than planned.

session.on('token-expired', async () => {
  // Re-mint for the SAME attempt_id. This resumes while the session
  // is still active, returning the same session_id with a fresh token.
  const res = await mintSession({ attempt_id: attemptId });

  if (res.resumed) {
    session.updateToken(res.session_jwt);   // same session — carry on,
                                            // queued events flush now
  } else {
    // The old session was already closed (e.g. the 3-hour sweep after a
    // long outage). This is a new attempt with its own report.
    session.destroy();
    session = ProctorLink.createSession({
      jwt: res.session_jwt,
      sessionId: res.session_id,
    });
    await session.start();
  }
});

The important branch is resumed. A re-mint only resumes while the session is still active. If the session has already ended, most likely the 3-hour abandonment sweep closed it after a long outage, the mint creates a new session, and its token belongs to that one. Passing it to updateToken would make every upload fail, so check resumed and start a fresh session deliberately when it is absent. Do not call stop() or destroy() and start a new session just to refresh a token; that ends the attempt server-side and the next mint creates a separate report, billed twice.

Lifecycle events and how to handle each one

Every interruption maps to a specific response. The table below is the short version of the whole page: what the SDK does on its own, what you have to do, and how the event shows up in the report a reviewer reads.

Common mistakes with the session lifecycle

• Generating a new attempt_id on every page load. A random id per load means every refresh mints a brand-new session, so one exam fragments into several partial reports and is billed several times. Fix: derive attempt_id from your own attempt record so it is stable across reloads.
• Using stop() or a bare destroy() for an SPA route change. Both end the attempt server-side, so returning to the exam mints a separate session with its own report and its own billed credit. Fix: tear down with destroy({ endSession: false }) and rejoin with the same attempt_id.
• Calling updateToken without checking resumed. If the old session already ended, the re-mint returns a token for a new session; applying it to the old one makes every upload fail. Fix: branch on resumed and start a fresh session when it is absent.
• Refreshing a token by tearing down and re-creating the session. Calling stop()/destroy() and starting again does not refresh a token, it ends the attempt. Fix: handle token-expired and call updateToken, which keeps the same attempt running.
• Reading the report the instant the exam ends. Face analysis is deferred, so an immediate fetch shows zeroed counts and identity_match: pending, which is an unfinished result, not a clean one. Fix: fetch when status is validated.

Frequently Asked Questions

Next steps

Want to watch a refresh and a reconnect rejoin the same attempt? Sign up at app.proctorlink.com to get your API keys, mint a session, and run one end to end.

More Proctoring Guides