SDK Reference

Install

npm install @incproctor/proctoring-sdk

yarn add @incproctor/proctoring-sdk

pnpm add @incproctor/proctoring-sdk

<script src="https://cdn.jsdelivr.net/npm/@incproctor/proctoring-sdk"></script>
<!-- exposes window.InCruiterProctoring -->

The package ships TypeScript types. Named exports only — there is no default export.

import {
  createProctoringSession,   // the factory you call
  ProctoringSession,         // the class it returns
  ProctoringEvent,           // event name constants
  ProctoringError,           // the error type
  checkSupport,              // browser capability probe
  VERSION,
} from '@incproctor/proctoring-sdk'

Lifecycle

Four steps, and only the first happens on your server.

1. Your backend mints a session

   Your server calls the mint endpoint and receives session_id and session_token. See the quickstart.

   Your API key and secret never enter the browser. Only the minted session belongs client-side — it expires, and it works for one candidate on one origin.

2. Create the session in the browser

   Creating it does not start monitoring or request any permission.

   const proctoring = createProctoringSession({
     baseUrl: INCPROC_BASE,   // the same base URL your server uses
     session,                 // exactly what your backend received
     camera:   { enabled: true, required: false },
     evidence: { enabled: true, intervalSec: 15, sources: ['camera'], maxDimension: 640 },
   })

3. Start it

   start() is where permissions are requested and monitoring begins. Call it from a user gesture — browsers refuse camera access otherwise.

   const status = await proctoring.start()
   console.log(status.state)   // 'active'

4. Stop it when the candidate finishes

   Flushes anything queued and closes the session cleanly.

   await proctoring.stop()

   If the tab simply closes, the session is detected and closed server-side — but the explicit call is cleaner and settles the credit sooner.

Browser support

Check before you create a session, so you can tell the candidate what will not work before the exam rather than during it.

import { checkSupport, UNSUPPORTED_DETECTIONS } from '@incproctor/proctoring-sdk'

const support = checkSupport()
if (!support.supported) {
  // Tell the candidate to switch browser before they begin.
}

The SDK requires a modern browser with getUserMedia, fetch and the Page Visibility API. It runs only in a secure context — HTTPS, or localhost. On plain http:// the browser blocks camera access outright.

Configuration

createProctoringSession(config)

session — SessionCredentials

Pass the mint response through unchanged. The field names are the API's, in snake_case; do not rename them to camelCase on the way.

camera / microphone — CameraOptions, MicrophoneOptions

screen — ScreenShareOptions

evidence — EvidenceOptions

monitors — MonitorOptions

environment — EnvironmentOptions

Methods

Lifecycle

Permissions you must ask for yourself

These need a user gesture — call them from a click or key-press handler, never on page load or inside a useEffect. The browser silently refuses otherwise.

Evidence & media

Events & state

Events

Subscribe with the constant, never a raw string — the constants are what your editor autocompletes and your compiler checks.

import { ProctoringEvent } from '@incproctor/proctoring-sdk'

const off = proctoring.on(ProctoringEvent.TAB_SWITCH, (payload) => {
  showWarning('Please stay on the exam tab.')
})

// Everything, for logging or a live activity feed:
proctoring.on(ProctoringEvent.ANY, (payload) => console.debug(payload))

off()   // unsubscribe

Activity

Media

Session & connection

Status & state

const status = proctoring.getStatus()
// {
//   state:       'idle' | 'starting' | 'active' | 'paused' | 'stopping' | 'stopped' | 'expired',
//   sessionId:   'pbs_…',
//   referenceId: 'your-own-id' | null,
//   connection:  'online' | 'offline' | 'degraded',
//   elapsedSec:  412,
//
//   camera:      { active: true,  permission: 'granted', deviceLabel: 'FaceTime HD Camera' },
//   microphone:  { active: false, permission: 'prompt' },
//   screen:      { active: true,  permission: 'granted', displaySurface: 'monitor' },
//
//   events:      { generated: 37, sent: 35, queued: 2, dropped: 0 },
//   evidence:    { captured: 12, uploaded: 12, failed: 0 },
//
//   hidden:      false,   // is the exam tab currently hidden?
//   fullscreen:  true,
// }

The three media entries are MediaStatus objects, each carrying active, permission (granted | denied | prompt | unknown), an optional deviceLabel, an error string when something went wrong, and — for screen only — displaySurface, which is what the candidate actually chose to share.

sessionState is a shorthand getter returning just the state string.

Errors

Everything the SDK throws is a ProctoringError carrying a stable code. Branch on the code, never the message — messages get reworded, codes do not.

import { ProctoringError } from '@incproctor/proctoring-sdk'

try {
  await proctoring.start()
} catch (err) {
  if (err instanceof ProctoringError) {
    console.error(err.code, err.message, err.requestId)
  }
}

What a ProctoringError carries

Every code

Grouped by who has to do something about it.

Your integration — fix these in code

The candidate's environment — tell them what to change

Permissions and devices — recoverable by the candidate

Media

Transport and session

Permissions

Three rules decide whether camera access will work at all, and none of them are ours:

Patterns

React

useEffect(() => {
  let session
  let cancelled = false

  createExamSession().then((minted) => {        // your backend
    if (cancelled) return
    session = createProctoringSession({ baseUrl: INCPROC_BASE, session: minted })
    session.on(ProctoringEvent.TAB_SWITCH, () => setWarning(true))
    return session.start()
  })

  return () => {
    cancelled = true
    // destroy() releases camera tracks — without it the light stays on.
    session?.destroy()
  }
}, [])

Warn, don't punish

let awayCount = 0
proctoring.on(ProctoringEvent.TAB_SWITCH, () => {
  awayCount += 1
  if (awayCount === 1) showBanner('Please stay on this tab.')
  if (awayCount === 3) showBanner('Repeated tab switching is recorded in your report.')
  // Do NOT end the exam here. The signal is advisory.
})

Survive a dropped network

proctoring.on(ProctoringEvent.CONNECTION_LOST, () => setBanner('Reconnecting…'))
proctoring.on(ProctoringEvent.CONNECTION_RESTORED, () => setBanner(null))

Nothing else is needed — events queue while offline and are resent on reconnect. Delivery is at-least-once and de-duplicated server-side.

Handle an expired session

proctoring.on(ProctoringEvent.SESSION_EXPIRED, async () => {
  // Monitoring has stopped. Mint a fresh session on your backend and start again.
  const minted = await createExamSession()
  proctoring = createProctoringSession({ baseUrl: INCPROC_BASE, session: minted })
  await proctoring.start()
})