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 callback処理
stop()
logout()
dispose()

init()はDetector instanceを作成して設定を登録します。この段階では、まだユーザー認証やwebcam検知は開始されません。

login()はSDK access tokenを発行し、login eventとアカウント/ポリシー情報を準備します。この段階ではwebcamと検知モデルを実行しません。

start()は、モデルロード、カメラ権限リクエスト、webcam stream、検知loopを開始します。その後SDKは検知loopを実行しながらonDetect callbackを繰り返し処理します。

stop()はlocal detection runtimeだけを停止します。SDK access tokenは維持されるため、同じユーザーが再度start()できます。

logout()は現在のユーザーsessionを終了するときに使用します。実行中の場合は先にstop()を呼び出す必要があり、同じDetector instanceを維持したまま別のユーザーが再度login()できます。

dispose()はDetector instance自体を終了するときに使用します。ページを離れる、またはアプリでSDKをもう使用しないときに、webcam stream、検知loop、内部resourceを整理します。

onDetect callback

onDetectは、顧客アプリがリアルタイム検知結果を受け取るためのcallbackです。

このcallbackはSDK内部の検知loopで繰り返し呼び出され、顧客アプリは結果に応じて画面ブロック/解除、独自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で顔が1つ以上検知されたかどうかです。
`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 versionによって拡張される場合があるため、画面ブロックのような一般的な分岐では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​

処理例​

自動サーバーイベントとの違い​

注意事項​