How to Add Proctoring to a Web Application

What are the moving parts?

Proctoring a custom application is a split between two places. A backend call cannot see the candidate, and a browser tab cannot hold a secret safely, so the work divides cleanly along that line. Your server does the two things a server can do, mint the session before the exam and read the report after it, and the browser does the one thing only a browser can do, capture the candidate.

If you are still deciding whether the SDK route is right for you at all, rather than the Moodle plugin or an LTI 1.3 launch, start with Proctoring SDK vs API vs LMS plugin. If you are new to the field, read What is online proctoring? and What is AI proctoring? first, then come back here to build.

Step 2: Start proctoring in the candidate browser

Install the SDK and hand it the token your backend just minted. In the default flow, recording begins as soon as the camera is granted and the first captured frame becomes the identity reference. That is the entire browser integration.

npm install @proctorlink/sdk@^0.1.3

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

// jwt and sessionId come from the POST /v1/sessions response above,
// fetched from your own backend endpoint.
const session = ProctorLink.createSession({
  jwt: sessionJwt,   // session_jwt
  sessionId,         // session_id
});

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

await session.start();

// when the attempt finishes:
session.stop();
session.destroy();

Candidates install nothing. This is Tier 1, the browser-only tier: it observes camera, microphone, focus and blur, fullscreen state, clipboard, and device changes. If you want matching against a deliberate, well-framed photo rather than whatever the first frame caught, create the session with autoStartCapture: false, call captureIdentity() after start() resolves, then call beginCapture() to start the exam.

If your page sets a Content-Security-Policy, allow the enclave origin so the iframe can mount:

frame-src https://enclave.proctorlink.com;

Step 4: Read the integrity report on your backend

After the exam, your backend calls GET /v1/sessions/:id. Face analysis is deferred, not real-time, so fetch the report once status is validated, or equivalently when integrity.analysis_complete is true. Before that, face counts are zero and identity_match is pending, which is an unfinished result rather than a clean one.

// Your backend. Fetch once status is "validated"
// (or integrity.analysis_complete is true).
GET /v1/sessions/6a7b18df70e4f8ecf2597b6f
access-token: <YOUR_ACCESS_TOKEN>
secret-token: <YOUR_SECRET_TOKEN>

// Response (trimmed)
{
  "status": "validated",
  "integrity": {
    "score": 100,
    "level": "low",
    "flagged": false,
    "identity_match": "pass",
    "reasons": []
  }
}

The integrity.score starts at 100 and drops as penalties apply. The level is low at 80 or above, medium from 50 to 79, and high below 50, and flagged turns true below 80. The verdict is computed server-side only, so the candidate cannot influence it. A score alone should not fail anyone: use reasons and evidence to drive human review of anything flagged.

Common mistakes when wiring the integration

• Putting your API key in browser JavaScript. The access-token and secret-token are server-side credentials. Anyone holding them can mint sessions billed to your account and read your reports. Fix: mint on your backend and pass only the session_jwt to the SDK.
• Generating a random attempt_id on page load. Resume keys off attempt_id, so a new value on every refresh splits one exam into several sessions and bills the attempt more than once. Fix: derive attempt_id from your own attempt record so it is stable for the attempt.
• Fetching the report the instant the exam ends. Face analysis is deferred, so an immediately fetched report has zero face counts and identity_match of pending. Fix: fetch when status is validated, polling on a sensible interval rather than a tight loop.
• Forgetting the CSP frame-src rule. If your page sets a Content-Security-Policy and does not allow the enclave origin, the iframe cannot mount and capture never starts. Fix: add the enclave origin to frame-src.
• Refreshing a token by tearing the session down. Calling stop() or destroy() to get a new token ends the attempt server-side, so the next mint creates a separate session: two reports for one attempt, billed twice. Fix: handle token-expired and call updateToken() with a freshly minted token for the same attempt_id.

Frequently Asked Questions

Next steps

Ready to add proctoring to software you already own? Get credentials, then wire the three calls above into a real exam and check the reviewer workload before you commit.

More Proctoring Guides