A light-weight proctoring library for some of the commonly used proctoring events
npm install proctor-sdkProctorSDK is a client-side JavaScript library designed to provide essential proctoring and user monitoring functionalities for web applications. It helps ensure exam integrity or user presence by leveraging browser APIs and TensorFlow.js for face detection.
- Face Detection:
- Detects if zero, one, or multiple faces are present in the webcam feed.
- Draws bounding boxes around detected faces.
- Environment Monitoring:
- Fullscreen Exit Detection: Warns if the user exits fullscreen mode.
- Tab Switch / Window Minimize Detection: Warns if the page visibility changes (user switches tabs or minimizes the window).
- Copy/Paste/Cut Attempt Detection: Warns if the user attempts clipboard actions on the page.
- Multiple Screen Detection: Warns if the user has an extended display setup (using window.screen.isExtended where available).
- Configurable:
- Enable or disable specific checks.
- Customize CDN paths for TensorFlow.js and BlazeFace models.
- Set custom throttle durations for violation event reporting.
- Event-Driven:
- Provides callbacks for status changes (e.g., "initializing", "started", "error") and proctoring violations.
- Easy Integration:
- Designed to be integrated into existing web applications, including those built with frameworks like React, Vue, or Angular.
- Requires a designated DOM container element where it will inject the webcam feed and canvas overlay.
- Modular Design:
- Internally structured for better maintainability and separation of concerns.
- TypeScript Support:
- Includes type definitions for a better development experience in TypeScript projects.
- Installation
- Quick Start
- Configuration
- Core Options
- Callbacks
- Enabled Checks
- Model Paths
- Throttle Durations
- API Reference
- ProctorSDK Class
- Public Methods
- Static Properties
- Data Structures
- StatusData Object
- ViolationData Object
- Usage with React (Example)
- How it Works (Brief Overview)
- Browser Compatibility
- Contributing
- License
Install ProctorSDK using npm (or yarn):
``bash`
npm install proctor-sdkor
yarn add proctor-sdk
Then, import it into your project:
`javascript`
import ProctorSDK, { STATUS_TYPES, WARNING_TYPES } from "proctor-sdk";
Here's a minimal example of how to use ProctorSDK in plain JavaScript after installing it via npm:
`html
ProctorSDK Demo
Status: Idle
`
The ProctorSDK is initialized with a configuration object.
- containerElement (Required): HTMLElement | string
- The DOM element (or its ID string) where the SDK will inject the webcam video feed and canvas overlay. The SDK will clear the contents of this element.
- Important: For proper canvas overlay, this container element should have its CSS set to relative, absolute, or fixed. If it's static (the default for most elements), the canvas overlay might not align correctly. The SDK will log a warning if it detects a static position.
- callbacks (Optional): object
- An object containing callback functions for SDK events.
-
- Called when the SDK's operational status changes (e.g., loading models, starting, error).
- See StatusData Object.
-
- Called when a proctoring rule is triggered (violation becomes active) or cleared (violation becomes inactive).
- See ViolationData Object.
-
- Called when webcam access is granted and the is available.onFacePredictions: (predictions: Array
-
- enabledChecks (Optional): object
- An object with boolean flags to enable or disable specific proctoring checks. Defaults to all .faceDetection: boolean
- (Checks for no face, one face, multiple faces)fullscreen: boolean
- (Checks for fullscreen exit)tabSwitch: boolean
- (Checks for page visibility changes)copyPaste: boolean
- (Checks for copy, paste, cut events)multipleScreens: boolean
- (Checks for extended display usage)
- tfjsModelPaths (Optional): object
- Allows overriding the default CDN URLs for TensorFlow.js and the BlazeFace model.
- (URL for TensorFlow.js core library)blazeface: string
- (URL for the BlazeFace model script)
- violationThrottleDurations (Optional): object
- An object to customize the minimum time (in milliseconds) between consecutive callbacks for _active_ violations of the same type. This prevents flooding the host application with events for continuous issues. Clearing a violation is not throttled.ProctorSDK.WARNING_TYPES
- Keys should be values from (e.g., [ProctorSDK.WARNING_TYPES.NO_FACE]: 5000).NO_FACE
- Defaults:
- : 3000msMULTIPLE_FACES
- : 3000msFULLSCREEN_EXIT
- : 1000msTAB_SWITCH
- : 1000msCOPY_PASTE_ATTEMPT
- : 1000msMULTIPLE_SCREENS
- : 10000ms
The main class you interact with.
`javascript`
import ProctorSDK from "proctor-sdk";
const instance = new ProctorSDK(config);
- async start(): Promise
- Initiates the proctoring session.
-
- Stops the currently active proctoring session.
-
- Returns if proctoring is currently running.requestFullscreen(): Promise
-
- Attempts to make the SDK's container element (or the document) enter fullscreen mode.
-
- Completely cleans up the SDK instance.
Accessible directly on the imported ProctorSDK class (e.g., ProctorSDK.STATUS_TYPES).
- ProctorSDK.STATUS_TYPES: object
- An enum-like object for status strings (see ).ProctorSDK.WARNING_TYPES: object
-
- An enum-like object for violation type strings (see ).
Type definitions are provided for TypeScript users.
Passed to the onStatusChange callback.
`typescript`
interface StatusData {
status: string; // A value from ProctorSDK.STATUS_TYPES
message: string;
error?: Error; // Present if status is ERROR
}
Passed to the onViolation callback.
`typescript`
interface ViolationData {
type: string;
active: boolean;
message: string;
timestamp: Date;
details?: {
count?: number;
eventType?: "copy" | "paste" | "cut";
};
}
`jsx
// SimpleProctor.jsx / SimpleProctor.tsx
import React, { useEffect, useRef, useCallback } from "react";
import ProctorSDK, { STATUS_TYPES, WARNING_TYPES } from "proctor-sdk";
const SimpleProctor = () => {
const proctorContainerRef = useRef(null);
const proctorSDKInstanceRef = useRef(null);
const handleStatusChange = useCallback((statusData) => {
console.log(
"[ProctorSDK Status]",
statusData.status,
"-",
statusData.message
);
if (statusData.error) console.error("[ProctorSDK Error]", statusData.error);
}, []);
const handleViolation = useCallback((violation) => {
if (violation.active) {
console.warn(
[ProctorSDK Violation ACTIVE] ${violation.type}: ${violation.message},[ProctorSDK Violation CLEARED] ${violation.type}: ${violation.message}
violation.details || ""
);
} else {
console.info(
);
}
}, []);
useEffect(() => {
if (proctorContainerRef.current && !proctorSDKInstanceRef.current) {
const sdkConfig = {
containerElement: proctorContainerRef.current,
callbacks: {
onStatusChange: handleStatusChange,
onViolation: handleViolation,
},
};
try {
proctorSDKInstanceRef.current = new ProctorSDK(sdkConfig);
} catch (e) {
console.error("[ProctorSDK] Initialization failed:", e);
}
}
return () => {
if (proctorSDKInstanceRef.current) {
proctorSDKInstanceRef.current.destroy();
proctorSDKInstanceRef.current = null;
}
};
}, [handleStatusChange, handleViolation]);
const start = () => proctorSDKInstanceRef.current?.start();
const stop = () => proctorSDKInstanceRef.current?.stop();
return (
Check console for logs.
How it Works (Brief Overview)
1. Initialization: The SDK sets up a designated container element, creating internal