Detector

Detector란?

Detector는 MonitorDogDetector.init()으로 생성되는 MonitorDog SDK의 runtime instance입니다.

Detector는 브라우저에서 SDK가 동작하는 동안 다음 lifecycle을 관리합니다.

SDK access token 요청 및 갱신에 필요한 callback
탐지 모델 로딩과 실행 상태
webcam stream과 video element
실시간 탐지 결과 callback
로그인, 로그아웃, 종료 처리

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

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

Lifecycle

Detector의 일반적인 lifecycle은 다음 순서로 진행됩니다.

init()
login()
start()
onDetect 콜백 처리
stop()
logout()
dispose()

init()은 Detector instance를 만들고 설정을 등록합니다. 이 단계에서는 아직 사용자 인증이나 webcam 탐지가 시작되지 않습니다.

login()은 SDK access token을 발급받고, login event와 계정/정책 정보를 준비합니다. 이 단계에서는 webcam과 탐지 모델을 실행하지 않습니다.

start()는 모델 로드, 카메라 권한 요청, webcam stream, 탐지 loop를 시작합니다. 이후 SDK는 탐지 루프를 돌면서 onDetect callback을 반복 처리합니다.

stop()은 local detection runtime만 중지합니다. SDK access token은 유지되므로 같은 사용자가 다시 start()할 수 있습니다.

logout()은 현재 사용자 세션을 종료할 때 사용합니다. 실행 중이면 먼저 stop()을 호출해야 하며, 같은 Detector instance를 유지한 채 다른 사용자가 다시 login()할 수 있습니다.

dispose()는 Detector instance 자체를 종료할 때 사용합니다. 페이지를 떠나거나 앱에서 SDK를 더 이상 사용하지 않을 때 webcam stream, 탐지 루프, 내부 리소스를 정리합니다.

onDetect callback

onDetect는 고객사 앱이 실시간 탐지 결과를 받기 위한 callback입니다.

이 callback은 SDK 내부 탐지 루프에서 반복 호출되며, 고객사 앱은 결과에 따라 화면 차단/해제, 자체 UI 표시, 자체 audit log 저장 같은 처리를 할 수 있습니다.

const detector = await MonitorDogDetector.init({
  apiBaseUrl: "https://api.monitor.dog/v1",
  sessionTokenProvider,
  onDetect: (result) => {
    if (result.phoneDetected) {
      blockScreen("휴대폰이 감지되었습니다.");
      return;
    }

    unblockScreen();
  },
});

onDetect는 고객사 앱을 위한 실시간 callback입니다. MonitorDog 서버에 보안 이벤트를 기록하는 동작과는 별개입니다.

Detection result payload

onDetect callback으로 전달되는 result에는 다음 값이 포함됩니다.

필드	설명
`phoneDetected`	현재 frame에서 휴대폰이 감지되었는지 여부입니다.
`faceDetected`	현재 frame에서 얼굴이 하나 이상 감지되었는지 여부입니다.
`phoneCount`	현재 frame에서 감지된 휴대폰 수입니다.
`faceCount`	현재 frame에서 감지된 얼굴 수입니다.
`phoneDetections`	휴대폰 탐지 box, score 등 상세 결과 목록입니다.
`faceDetections`	얼굴 탐지 box, score 등 상세 결과 목록입니다.
`video`	SDK가 탐지에 사용하는 `HTMLVideoElement`입니다.
`timestamp`	탐지 결과가 생성된 시각입니다.
`mainUserTracking`	주 사용자 추적 상태입니다. 다중 사용자 또는 사용자 이탈 판단에 활용할 수 있습니다.

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

상세 detection object의 내부 필드는 SDK 버전에 따라 확장될 수 있으므로, 화면 차단처럼 일반적인 분기는 phoneDetected, faceDetected, phoneCount, faceCount를 우선 사용하세요.

처리 예시

휴대폰이 감지되면 화면을 차단하고, 감지가 사라지면 차단을 해제할 수 있습니다.

onDetect: (result) => {
  if (result.phoneDetected) {
    blockScreen("휴대폰 사용이 감지되었습니다.");
    return;
  }

  unblockScreen();
};

다중 사용자가 감지되면 시험 화면이나 보안 화면을 잠글 수 있습니다.

onDetect: (result) => {
  if (result.faceCount >= 2) {
    blockScreen("여러 명의 사용자가 감지되었습니다.");
    return;
  }

  unblockScreen();
};

얼굴이 없으면 사용자가 자리를 비웠거나 webcam이 가려진 상태로 처리할 수 있습니다.

onDetect: (result) => {
  if (!result.faceDetected) {
    showWarning("사용자 얼굴이 보이지 않습니다.");
    return;
  }

  hideWarning();
};

정상 상태에서는 기존 차단 UI를 해제하고 앱 사용을 계속 허용합니다.

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

  setScreenBlocked(shouldBlock);
};

자동 서버 이벤트와의 차이

onDetect는 고객사 앱이 실시간 탐지 결과를 처리하기 위한 callback입니다. 고객사 앱이 보통 MonitorDog 서버의 /event API를 직접 호출할 필요는 없습니다.

SDK는 내부 정책에 따라 다음 보안 이벤트를 MonitorDog 서버에 자동 기록합니다.

mobileDevice
twoFacesDetected
noFaceDetected
webcamBlocked

예를 들어 휴대폰이 감지되면 고객사 앱의 onDetect callback이 호출되고, SDK 내부 정책에 따라 MonitorDog 서버에도 mobileDevice 이벤트가 기록될 수 있습니다.

따라서 고객사 앱은 실시간 UX 처리는 onDetect에서 수행하고, MonitorDog 서버 audit/event 기록은 SDK의 자동 이벤트 기록 정책에 맡기는 구성을 권장합니다.

주의사항

onDetect는 반복 호출되므로 무거운 작업을 직접 실행하지 마세요.
자체 API 호출이나 로그 저장이 필요하면 throttle 또는 debounce를 적용하세요.
같은 차단 상태를 매 frame마다 중복 처리하지 않도록 현재 UI 상태를 비교하세요.
SDK 실행 중 오류 처리는 onDetect가 아니라 onError에서 처리하세요.
onDetect 안에서 예외가 발생하지 않도록 고객사 UI 로직은 가능한 한 작고 예측 가능하게 유지하세요.

Detector란?​

Lifecycle​

onDetect callback​

Detection result payload​

처리 예시​

자동 서버 이벤트와의 차이​

주의사항​