How to Add Proctoring to a React Assessment App

Where does the SDK fit in a React app?

The SDK is imperative and the camera lives in a cross-origin iframe enclave that mounts itself, so it does not belong in your render tree. It belongs in an effect. React’s job is to tell you when the exam component appears and disappears; the SDK’s job is to start when it appears and tear down when it goes. Map each SDK call to the React moment that should trigger it and the integration writes itself.

This is the same three-part split covered in How to add proctoring to a web application, applied to React’s lifecycle. If you are still choosing between the SDK, the REST API, and the Moodle plugin, start with Proctoring SDK vs API vs LMS plugin. New to the field? Read What is online proctoring? and What is AI proctoring? first.

Step 2: Wrap the SDK in a hook

Put the whole lifecycle in one custom hook so your exam component stays about questions, not cameras. Create the session inside a useEffect, hold it in a useRef rather than state, wire the events once, and return a cleanup that ends the attempt. The ref keeps the SDK instance stable while the rest of your UI re-renders.

npm install @proctorlink/sdk@^0.1.3

// useProctoring.ts
import { useEffect, useRef } from 'react';
import { ProctorLink } from '@proctorlink/sdk';

type RemintResult = { session_jwt: string; session_id: string; resumed?: boolean };

type UseProctoringArgs = {
  jwt: string;          // session_jwt from your backend
  sessionId: string;    // session_id from your backend
  attemptId: string;    // stable per attempt, from your own record
  remint: (attemptId: string) => Promise<RemintResult>;
};

export function useProctoring({ jwt, sessionId, attemptId, remint }: UseProctoringArgs) {
  const sessionRef = useRef<ReturnType<typeof ProctorLink.createSession> | null>(null);

  useEffect(() => {
    const session = ProctorLink.createSession({ jwt, sessionId });
    sessionRef.current = session;

    session.on('permission', ({ camera }) => {
      if (camera === 'denied') { /* block or warn, your policy */ }
    });
    session.onEvent((event) => console.log(event.type, event));

    // Safety net for exams that outlast the token.
    session.on('token-expired', async () => {
      const res = await remint(attemptId);
      if (res.resumed) {
        session.updateToken(res.session_jwt);   // same session, carry on
      }
      // If res.resumed is false the old session ended — start a fresh one.
    });

    session.start();

    // Runs on unmount, and again between StrictMode's dev remount.
    return () => {
      session.stop();
      session.destroy();
      sessionRef.current = null;
    };
    // One attempt, one effect: identity comes from your backend, not re-renders.
  }, [jwt, sessionId, attemptId, remint]);

  return sessionRef;
}

Two events earn a listener. The permission event reports whether the candidate granted the camera, so you can enforce your own policy. The token-expired event fires only if a token dies mid-attempt, so capture never fails silently. The default flow records as soon as the camera is granted and uses the first captured frame as the identity reference. If you want matching against a deliberate photo instead, create the session with autoStartCapture: false, call captureIdentity() after start() resolves, then call beginCapture().

Step 4: Keep long exams alive through token expiry

The session token is short-lived. For an exam that can outlast it, the token-expired handler in the hook re-mints on your backend for the same attempt_id. Because that attempt still has an active session, ProctorLink returns the existing session_id with a fresh token and resumed set to true, and you pass the new token to updateToken(). Events queued while the token was dead are flushed as soon as it lands, so nothing from the gap is lost.

Check resumed before calling updateToken(). A re-mint only resumes while the session is still active; if the abandonment sweep has already closed it, the mint creates a new session whose token belongs to a different attempt. The simplest way to avoid the whole situation is to set ttl_seconds generously at mint and treat token-expired as a safety net.

Common mistakes in a React integration

• Storing the session in useState. The session is an imperative handle, not render state. Putting it in state triggers re-renders and leaves you with stale closures when you later call updateToken(). Fix: hold it in a useRef and read sessionRef.current from your handlers.
• Creating the session in the render body. Anything outside an effect runs on every render, and in the Next.js App Router it can run on the server, where there is no camera. Fix: only call ProctorLink.createSession() inside a useEffect, and mark the component 'use client'.
• Missing effect cleanup. Without a cleanup that calls stop() then destroy(), StrictMode doubles the camera preview in development and, worse, real navigation leaves an enclave running. Fix: return the cleanup from useEffect.
• Generating attempt_id on render. A value created with useState(() => crypto.randomUUID()) or on each mount defeats resume, so every refresh mints a new session and bills the attempt twice. Fix: derive attempt_id from your own attempt record so it is stable for the attempt.
• Refreshing a token by remounting. Unmounting the component to “restart” proctoring ends the attempt server-side, and the next mint creates a separate session: two reports for one attempt. Fix: handle token-expired and call updateToken() with a freshly minted token for the same attempt_id.

Frequently Asked Questions

Next steps

Ready to proctor exams in your React app? Get credentials, wire the hook above into a real attempt, and check the reviewer workload before you commit.

More Proctoring Guides