@sandesh__07/examshield

Silent, high-fidelity exam proctoring SDK for the browser.

ExamShield is a robust proctoring library designed for easy integration into any Learning Management System (LMS). It monitors candidate behavior in real-time — detecting tab switching, secondary displays, copy-paste attempts, DevTools usage, and webcam anomalies.

🚀 Quick Start

Integration is designed to be minimal. You only need two calls:

import { ExamShield } from '@sandesh__07/examshield';

// 1. Start proctoring (handles permissions & overlays automatically)
ExamShield.start({
  sessionId:   'exam-session-123',
  apiEndpoint: 'https://api.your-lms.com',
  getToken:    () => userAuthToken,
  onReady:     () => startExam(),      // Called when setup is complete
  onCancelled: () => exitProctoring(), // Called if user denies permissions
  onError:     (msg) => showError(msg)
});

// 2. Stop proctoring (on submit or exit)
ExamShield.stop();

✨ Key Features

• Built-in Overlays: Automatic, themeable UI for screen share, camera access, and fullscreen enforcement.
• Unified Event Reporting: All violations and snapshots are sent to a single REST endpoint (POST /api/proctor/event).
• Permission Flow: Orchestrates browser checks, screen sharing (full-monitor enforcement), and webcam verification.
• Robust Monitoring:
  • Tab Switch & Window focus detection
  • Fullscreen Exit enforcement
  • Multiple monitor / Display change detection
  • Keyboard shortcut & Right-click blocking
  • Face detection (TinyFaceDetector + SSD fallback)
  • Microphone noise detection (voice / loud / repeated speech — no recording)
• Automatic Retries: In-memory event queue with retry logic for zero data loss during network blips.

⚙️ Configuration

| Option | Type | Description | | :--- | :--- | :--- | | sessionId | string | Required. Unique ID for the exam session. | | apiEndpoint | string | Required. Base URL for the proctoring API. | | getToken | function | Required. Function returning the current auth token. | | features | object | Toggle specific monitors (webcam, screenShare, mic, etc.). | | webcam | object | Snapshot interval, quality, and face detection paths. | | screenCapture | object | Screen frame capture interval and quality. | | mic | object | Microphone monitoring config (see below). |

Microphone Config (mic)

ExamShield.start({
  // ...existing config...
  features: {
    mic: true,          // default true — set false to disable entirely
  },
  mic: {
    mandatory:           false, // true = no skip button, retry on denial
    volumeThreshold:     0.5,  // RMS above this → VOICE_DETECTED
    loudThreshold:       0.75, // RMS above this → LOUD_CONVERSATION
    sampleIntervalMs:    1000, // check every 1 s
    repeatedSpeechCount: 3,    // REPEATED_SPEECH after 3 detections in 20 s
  },
});

// To disable mic completely:
// features: { mic: false }  — no overlay, no getUserMedia for audio

🛠️ Theming

ExamShield UI can be themed using CSS variables:

:root {
  --es-primary: #2563eb;
  --es-bg: #ffffff;
  --es-text: #111827;
  --es-border-radius: 12px;
}

📜 License

MIT © sandesh__07