Detector

What is Detector?

Detector is the MonitorDog SDK runtime instance created by MonitorDogDetector.init().

While the SDK runs in the browser, Detector manages the following lifecycle.

• Callback needed to request and renew the SDK access token
• Detection model loading and runtime state
• Webcam stream and video element
• Real-time detection result callback
• Login, logout, and termination handling

import { MonitorDogDetector } from "@monitordog/detector";

const detector = await MonitorDogDetector.init({
  apiBaseUrl: "https://api.monitor.dog/v1",
  sessionTokenProvider,
  onDetect,
  onError,
});

Lifecycle

A typical Detector lifecycle follows this order.

1. init()
2. login()
3. start()
4. Handle the onDetect callback
5. stop()
6. logout()
7. dispose()

init() creates the Detector instance and registers settings. User authentication and webcam detection have not started yet at this stage.

login() issues the SDK access token and prepares the login event and account/policy information. It does not run the webcam or detection model at this stage.

start() starts model loading, camera permission request, webcam stream, and the detection loop. After this, the SDK repeatedly handles the onDetect callback while the detection loop runs.

stop() stops only the local detection runtime. The SDK access token is retained, so the same user can call start() again.

logout() is used to end the current user session. If the detector is running, call stop() first. The same Detector instance can be kept and another user can call login() again.

dispose() is used to terminate the Detector instance itself. When leaving the page or when your app no longer uses the SDK, it cleans up the webcam stream, detection loop, and internal resources.

onDetect Callback

onDetect is the callback that lets the customer app receive real-time detection results.

This callback is called repeatedly from the SDK internal detection loop. The customer app can use the result to block or unblock the screen, show its own UI, or store its own audit logs.

const detector = await MonitorDogDetector.init({
  apiBaseUrl: "https://api.monitor.dog/v1",
  sessionTokenProvider,
  onDetect: (result) => {
    if (result.phoneDetected) {
      blockScreen("A phone has been detected.");
      return;
    }

    unblockScreen();
  },
});

onDetect is a real-time callback for the customer app. It is separate from the behavior that records security events on the MonitorDog server.

Detection Result Payload

The result passed to the onDetect callback includes the following values.

Field	Description
phoneDetected	Whether a phone was detected in the current frame.
faceDetected	Whether one or more faces were detected in the current frame.
phoneCount	Number of phones detected in the current frame.
faceCount	Number of faces detected in the current frame.
phoneDetections	Detailed phone detection results such as boxes and scores.
faceDetections	Detailed face detection results such as boxes and scores.
video	HTMLVideoElement used by the SDK for detection.
timestamp	Time when the detection result was generated.
mainUserTracking	Main user tracking state. This can be used to judge multiple users or user absence.

type DetectionResult = {
  phoneDetected: boolean;
  faceDetected: boolean;
  phoneCount: number;
  faceCount: number;
  phoneDetections: unknown[];
  faceDetections: unknown[];
  video: HTMLVideoElement;
  timestamp: number;
  mainUserTracking?: unknown;
};

The internal fields of detailed detection objects can be extended depending on SDK version. For common branches such as screen blocking, prefer phoneDetected, faceDetected, phoneCount, and faceCount.

Handling Examples

When a phone is detected, you can block the screen and unblock it when detection disappears.

onDetect: (result) => {
  if (result.phoneDetected) {
    blockScreen("Phone use has been detected.");
    return;
  }

  unblockScreen();
};

When multiple users are detected, you can lock an exam screen or security screen.

onDetect: (result) => {
  if (result.faceCount >= 2) {
    blockScreen("Multiple users have been detected.");
    return;
  }

  unblockScreen();
};

If no face is visible, you can treat the user as away from the seat or the webcam as covered.

onDetect: (result) => {
  if (!result.faceDetected) {
    showWarning("The user's face is not visible.");
    return;
  }

  hideWarning();
};

In a normal state, release the existing blocking UI and continue allowing app use.

onDetect: (result) => {
  const shouldBlock = result.phoneDetected || result.faceCount >= 2 || !result.faceDetected;

  setScreenBlocked(shouldBlock);
};

Difference from Automatic Server Events

onDetect is a callback for the customer app to handle real-time detection results. In general, the customer app does not need to call the MonitorDog server /event API directly.

Depending on its internal policy, the SDK automatically records the following security events on the MonitorDog server.

• mobileDevice
• twoFacesDetected
• noFaceDetected
• webcamBlocked

For example, when a phone is detected, the customer app's onDetect callback is called, and the SDK may also record a mobileDevice event on the MonitorDog server according to its internal policy.

Therefore, we recommend that customer apps handle real-time UX in onDetect and leave MonitorDog server audit/event recording to the SDK's automatic event recording policy.

Notes

• onDetect is called repeatedly, so do not run heavy work directly in it.
• If you need to call your own API or save logs, apply throttle or debounce.
• Compare the current UI state so you do not repeat the same blocking work every frame.
• Handle SDK runtime errors in onError, not in onDetect.
• Keep customer UI logic inside onDetect as small and predictable as possible to avoid exceptions.