본문으로 건너뛰기

모니터독 Web SDK v1.0.16 업데이트: Pose 추적 및 카메라 오류 처리 개선

|
약 3분
모니터독(MonitorDog) 팀
모니터독(MonitorDog) 팀
AI 기반 시각적 해킹 차단 솔루션
Web SDK 업데이트

이 문서는 모니터독 Web SDK v1.0.16 기준으로 작성된 업데이트 노트입니다.

사용자 감지 안정성과 연동 편의성을 개선했습니다.

MediaPipe Pose 추적을 추가하고 탐지 결과를 사용자 중심 필드로 정리했으며, 웹캠을 열 수 없는 원인을 더 구체적으로 확인할 수 있도록 오류 처리를 개선했습니다.

업데이트 주요 내용​

Web SDK v1.0.16 변경 사항

• Pose 추적 추가 : MediaPipe Pose를 활용해 사용자 추적을 보완하고 탐지 안정성을 높였습니다.
• 탐지 결과 API 개선 : 사용자 유무와 인원수를 personDetected, personCount로 제공합니다.
• 카메라 오류 세분화 : 카메라 사용 중, 장치 없음, 권한 거부 등 시작 실패 원인을 구체적인 오류 코드로 전달합니다.
• Runtime 안정화 : 유효하지 않은 video frame 처리, 초기 모델 준비 구간, MediaPipe asset 경로와 실행 fallback을 개선했습니다.

상세 변경 사항​

1. MediaPipe Pose 사용자 추적 추가​

기존 얼굴 및 휴대폰 탐지에 MediaPipe Pose 추적을 추가했습니다. 얼굴이 일시적으로 명확하게 보이지 않는 상황에서도 자세 추적 상태를 함께 활용하여 사용자 존재 여부를 더 안정적으로 판단할 수 있습니다.

Pose의 세부 상태는 poseTracking에서 확인할 수 있습니다. bounding box와 landmark 좌표도 제공되며, 이 정보는 일반적인 화면 차단 로직보다는 탐지 상태 확인과 문제 분석을 위한 디버깅 용도로 사용할 수 있습니다.

2. 사용자 중심 탐지 결과 API​

onDetect 결과의 사용자 관련 필드가 다음과 같이 변경되었습니다.

이전 필드v1.0.16 필드
faceDetectedpersonDetected
faceCountpersonCount

일반적인 사용자 유무와 인원수 판단에는 personDetected, personCount를 사용하세요. 얼굴 탐지 상세 정보가 필요한 경우에는 기존처럼 faceDetections를 확인할 수 있습니다.

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

  if (result.personCount >= 2) {
    blockScreen("여러 명의 사용자가 감지되었습니다.");
  }
};
업데이트 시 코드 변경이 필요합니다.

v1.0.15에서 faceDetected 또는 faceCount를 사용하던 연동 코드는 v1.0.16에 맞게 personDetected, personCount로 변경해야 합니다.

3. 카메라 시작 오류 안내 개선​

카메라 시작 실패를 MonitorDogSdkError로 전달하고, 상황에 맞는 오류 코드를 제공합니다. 다른 애플리케이션이나 브라우저 탭이 카메라를 사용 중일 가능성이 있는 경우에도 별도 코드로 처리할 수 있습니다.

  • CAMERA_PERMISSION_DENIED
  • CAMERA_NOT_FOUND
  • CAMERA_IN_USE
  • CAMERA_CONSTRAINT_FAILED
  • CAMERA_REQUEST_TIMEOUT
  • CAMERA_UNSUPPORTED
  • CAMERA_READ_FAILED

원본 브라우저 오류는 cause에서 확인할 수 있습니다.

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

onError: (error) => {
  if (error instanceof MonitorDogSdkError) {
    console.error(error.code, error.message, error.cause);
  }
};

업데이트 방법​

npm을 사용하는 프로젝트는 package를 업데이트하세요.

npm install @monitordog/detector@1.0.16

static zip을 사용하는 환경은 v1.0.16 zip의 monitordog/ 폴더 전체를 다시 배포해야 합니다. 이번 버전부터 assets/mediapipe/ 아래에 Pose model과 WebAssembly runtime이 포함되므로 기존 UMD script만 교체하면 정상적으로 동작하지 않을 수 있습니다.

서버에서 static asset을 직접 제공하는 경우 .task 확장자를 application/octet-stream MIME 타입으로 제공해야 합니다.

업데이트 체크리스트​

  • faceDetected를 personDetected로 변경했는가?
  • faceCount를 personCount로 변경했는가?
  • static zip 사용 시 monitordog/ 폴더 전체를 교체했는가?
  • static 서버에서 .task MIME 타입을 제공하는가?
  • onError에서 세분화된 카메라 오류 코드를 처리하는가?

Web SDK v1.0.16으로 업데이트하세요

변경된 탐지 결과 API와 설치 방법은 Web SDK 연동 문서에서 확인할 수 있습니다.

목차

이 콘텐츠 공유