@proctorio/observe

v1.0.9

Published

5 days ago

JavaScript SDK for subscribing to Proctorio exam monitoring events and implementing custom logic for online exam security.

0High
0Medium
0Low

artfulhacker

proctorio exam monitoring security sdk events browser-extension online-testing

Observe.js

A JavaScript SDK for subscribing to Proctorio exam monitoring events. This library enables developers to listen to key events during online exam lifecycles and implement custom logic for exam monitoring and security.

Features

Event-driven architecture for real-time exam monitoring
Singleton pattern ensures consistent state across your application
Cross-origin communication with Proctorio browser extension
Multiple build formats (ESM, CommonJS, IIFE) for flexible integration

Installation

Using npm (Node.js)

npm install @proctorio/observe

Using jsDelivr (CDN)

Observe.js is hosted on jsDelivr. The example below is using the latest package version at the time this README was updated (version 1.0.6), but by following the link https://www.jsdelivr.com/package/npm/@proctorio/observe you can see which versions are available and which is the latest version.

The package can be istalled by adding the following script to the <head> tag:

<script src="https://cdn.jsdelivr.net/npm/@proctorio/[email protected]/lib/index.min.js"></script>

Quick Start

1. Create Observe instance

Node.js

import { Observe } from '@proctorio/observe';

// Create observe instance (singleton)
const observe = new Observe();

JsDelivr

// Create observe instance (singleton)
const observe = new ObserveSDK.Observe();

2. Listen for events

// Listen for exam start
observe.startExam((data) => {
  console.log('Exam started at offset:', data.offset);
});

// Listen for security flags
observe.flags((data) => {
  console.log('Security flags detected:', data.flagsData);
  console.log('Time offset:', data.offset);
});

// Listen for live proctor events - available in live proctor exams:

//Listen for exam interrupted
observe.proctorInterrupted((data) => {
  console.log('Exam interrupted at offset:', data.offset);
});

//Listen for exam resumed
observe.proctorResumed((data) => {
  console.log('Exam resumed at offset:', data.offset);
});

//Listen for live proctor kickout 
observe.proctorKickedOut((data) => {
  console.log('Candidate kicked out from exam at offset:', data.offset);
});

// Check if Proctorio extension is running

// send (emit) Proctorio status request

// getproctorio
observe.proctorioStatusRequest();

//custom domain
observe.proctorioStatusRequest("https://your_custom_domain");

// listen for response
observe.proctorioStatusResponse((data) => {
  console.log("Proctorio is running: " + data.active);
});

Supported Events

One-time Events

These events trigger only once during the exam lifecycle:

startExam - Fired when the exam officially begins
takeExam - Fired when the user starts taking the exam
startDeskScan - Fired when desk scanning process starts
endDeskScan - Fired when desk scanning process completes
endExam - Fired when exam ending logic is triggered
examCloseCode - Fired when exam closes with a specific close code
proctorKickedOut - Fired when a sudent is kicked out by live proctor during an exam

Recurring Events

flags - Fired every 200-500ms when security flags are detected. Contains an object with boolean flags for various security violations.

Multi-trigger Events

proctorInterrupted - Fired when live proctor interrupts the exam, can happen multiple times during an exam.
proctorResumed - Fired when live proctor resumes the interrupted exam, can happen multiple times during an exam.
proctorioStatusResponse - Fired as a response to proctorio status check message

Sending requests through post message

proctorioStatusRequest - Send message to check if Proctorio is active on exam

Event Data Structure

All events include a data object. All event data objects, except for those related to proctorioStatusResponse, have an offset property representing milliseconds from exam start time.

Common Event Data

{
  offset: 1000 // milliseconds from exam start
}

examCloseCode Event

{
  offset: 5000, // milliseconds from exam start
  closeCode: 42 // specific close code number
}

flags Event

{
  offset: 2000, // milliseconds from exam start
  flagsData: {
    unfocus_detected: true,
    clipboard_detected: false,
    browser_resize_detected: false,
    multiple_faces_detected: true,
    leaving_exam_area_detected: false,
    speaking_detected: false,
    ai_detected: false,
    printing_detected: false,
    screenshot_detected: false,
    hardware_change_detected: false,
    external_action_detected: false,
    webcam_obscured_detected: false,
    mobile_phone_detected: false
  }
}

proctorioStatusResponse Event

{
  active: true
}

API Reference

Constructor

const observe = new Observe();

Returns a singleton instance of the Observe class.

Event Subscription Methods

`observe.startExam(callback)`

Subscribe to exam start events.

`observe.takeExam(callback)`

Subscribe to exam taking events.

`observe.startDeskScan(callback)`

Subscribe to desk scan start events.

`observe.endDeskScan(callback)`

Subscribe to desk scan completion events.

`observe.endExam(callback)`

Subscribe to exam end events.

`observe.examCloseCode(callback)`

Subscribe to exam close code events.

`observe.flags(callback)`

Subscribe to security flag detection events.

`observe.proctorInterrupted(callback)`

Subscribe to live proctor exam interrupted events.

`observe.proctorResumed(callback)`

Subscribe to live proctor exam resumed events.

`observe.proctorKickedOut(callback)`

Subscribe to live proctor exam kickout events.

`observe.proctorioStatusRequest(origin), observe.proctorioStatusResponse(callback)`

Subscribe to proctorio status check events.

Parameters:

callback (function): Function to execute when the event fires. Receives event data as parameter.
origin (string): Optional string parameter for proctorioStatusRequest. The default value is the getproctorio origin. If you are using a custom domains, you should use your domain as the parameter.

Browser Support

Modern browsers with ES6+ support
Requires window.top.postMessage and window.addEventListener APIs
Compatible with Proctorio browser extension

Important Notes

⚠️ Page Transition Limitations: Events triggered during page transitions (like endExam and examCloseCode) may not execute reliably due to browser unload behavior.

⚠️ Initialization Context: Avoid initializing Observe on exam completion pages as it will have no effect.

⚠️ Connection Behavior: The SDK automatically attempts to establish communication with the Proctorio extension using periodic message passing until successful connection.

Development

Building

npm run build  # Creates ESM, CommonJS, and minified IIFE builds in lib/

Testing

npm test  # Run Jest tests with jsdom environment

Build Outputs

lib/index.esm.js - ES module format
lib/index.cjs.js - CommonJS format
lib/index.min.js - Minified IIFE for browser use

Contributing

Fork the repository
Create a feature branch
Make your changes with tests
Ensure all tests pass
Submit a pull request

License

Apache License 2.0 - see LICENCE file for details.

Support

For issues and questions, please open an issue on GitHub.