exam-proctor-sdk3
v1.1.5
Published
A Node.js SDK for integrating exam proctoring features(Registration + verification) into your applications.
Maintainers
muralidhar55Readme
exam-proctor-sdk3
Lightweight Express middleware for in-page exam proctoring — no iframes, no sidecars, no separate processes.
How It Works
exam-proctor-sdk3 mounts directly into your existing Express app as middleware.
It handles registration, session verification, and client-side proctoring inside
your app's same-origin flow without iframes or a sidecar service.
Your Express App
└── app.use(examProctor.middleware(config))
├── GET /proctor/register
├── GET /proctor/verify
├── GET /proctor/api/session-token
└── GET /proctor/proctor-bundle.js ← injected client SDKInstall
npm install exam-proctor-sdk3Quick Start (Developer Guide)
Here's how to integrate the SDK into your Express project and trigger it from your frontend.
1. Server-Side Setup
const express = require('express');
const examProctor = require('exam-proctor-sdk3');
const app = express();
// Mount the middleware
app.use(examProctor.middleware({
// Optional: Save violations to your own database (MongoDB, Postgres, etc.)
onViolation: async (violationData) => {
console.log("New violation received:", violationData);
// await myDatabase.violations.insert(violationData);
},
// Optional: override default violation log directory
// violationLogDir: './my-violations-folder',
// See Configuration section for more options
}));
// Inject the config tag and bundle in your HTML response
app.get('/exam', (req, res) => {
res.send(`
<html>
<head>
${examProctor.configScriptTag({ /* runtime config */ })}
</head>
<body>
<h1>My Exam Application</h1>
<!-- Inject the proctoring client script -->
<script src="/proctor/proctor-bundle.js"></script>
<script>
// Start proctoring when the exam begins
document.addEventListener('DOMContentLoaded', () => {
// Ensure you pass a unique session ID and the student's name
window.ProctoringSystem.start('unique-session-123', 'John Doe');
});
// Stop proctoring when the exam is submitted
function submitExam() {
window.ProctoringSystem.stop();
}
</script>
</body>
</html>
`);
});
app.listen(3000);2. Client-Side API
Once /proctor/proctor-bundle.js is loaded in the browser, the global ProctoringSystem object is available:
// Start proctoring for a student session
window.ProctoringSystem.start('session-123', 'Student Name');
// Stop proctoring (call on exam submit or timeout)
window.ProctoringSystem.stop();The system also fires custom events on the window object that you can listen to:
window.addEventListener('examproctor:ready', () => {
console.log('Proctoring SDK is ready to start');
});
window.addEventListener('examproctor:started', (e) => {
console.log('Proctoring started for session:', e.detail.sessionId);
});
window.addEventListener('examproctor:violation_limit_exceeded', (e) => {
console.log('Student exceeded violations. Terminate exam!', e.detail);
});Exam Flow
/ → /proctor/register → /proctor/verify → /exam → /result- Student lands on
/and is redirected to/proctor/register - After registration, identity is verified at
/proctor/verify - On success, student proceeds to
/exam - On submit, session ends and student sees
/result
Server API
These are exported directly from require('exam-proctor-sdk3'):
| Export | Type | Description |
|---|---|---|
| middleware(config) | function | Express middleware — mounts all /proctor/* routes into your app |
| configScriptTag(config) | function | Returns an inline <script> tag with runtime config for the client |
| registerUrl() | function | Returns the registration route path (/proctor/register) |
| verifyUrl(sessionId) | function | Returns the verification route path for a given session |
Configuration
The middleware() and configScriptTag() functions accept a config object with the following properties:
| Property | Default | Description |
|---|---|---|
| modelsBaseUrl | https://cdn.jsdelivr.net/gh/Murali55-09/violation-detect@models-cdn/ | CDN path for YOLO and FaceMesh models. |
| yoloModelFile | best_int8rc.onnx | YOLO model filename to use during the exam runtime. |
| yoloRequestedInputSize | 640 | Preferred YOLO input size before ONNX metadata auto-adjustment. |
| yoloClassThresholds | built-in defaults | Per-class confidence thresholds, e.g. { phone: 0.28, book: 0.35, earbuds: 0.25 }. |
| yoloClassIou | built-in defaults | Per-class NMS IoU thresholds, e.g. { phone: 0.45, book: 0.45, earbuds: 0.40 }. |
| yoloMotionThreshold | 0 | Motion score needed before object detection runs early. |
| yoloObjectForceInterval | 1 | Force YOLO every Nth frame even when motion is low. |
| yoloViolationCooldownMs | 3000 | Minimum time between repeated object violations of the same type. |
| yoloTrackDecay | 0.70 | Per-frame decay for stale object tracks. |
| yoloTrackDrop | 0.25 | Drop threshold for stale object tracks. |
| yoloTrackReappearMs | 1200 | Time gap before an object is treated as a new appearance again. |
| yoloVisualTtlMs | 450 | How long detected boxes remain visible after the last fresh detection. |
| onViolation | null | An async callback function triggered whenever a new violation is detected, allowing you to save it to your own custom database (e.g. MongoDB, Postgres, MySQL). |
| violationLogDir | .exam-proctor/violations | Directory on your local server where violation JSON logs will be saved as a local file backup. |
| mountPath | /proctor | The base path where proctoring routes are mounted. |
| workerPath | /proctor/proctoringWorker.js | Path to the background proctoring worker script. |
AI Features & Model Support
Includes a built-in YOLOv8n model optimized for academic integrity:
- Class 0: Phone — Detects mobile devices in frame.
- Class 1: Book/Notes — Detects physical study materials.
- FaceMesh / MobileFaceNet — 468-point landmark tracking for head-pose (looking away) and identity validation.
Detection models are loaded from CDN by default:
https://cdn.jsdelivr.net/gh/Murali55-09/violation-detect@models-cdn/Self-hosting: Place model files locally and point to them via your middleware(config) options. Local models in exam-proctor-sdk3/models/* are supported as a fallback for air-gapped or offline environments.
Headers
The SDK expects your Express app to serve pages with the following headers for full browser API access (camera, cross-origin isolation):
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Resource-Policy: same-originPublish & Release
To publish a new version:
- Increment
versioninpackage.json(e.g.,npm version patch). - Run
npm run buildto bundle client assets. - Run
npm publish --access public(Make sure you are logged in usingnpm login).
Requirements
- Node.js >= 18
- Express >= 4
License
MIT