본문으로 건너뛰기

검증 및 문제 해결

연동 후에는 패키지 설치, access token provider, 브라우저 SDK, camera 권한, MonitorDog runtime API를 순서대로 확인합니다.

빠른 점검 체크리스트​

  • npm install @monitordog/detector 후 브라우저 앱 빌드가 성공합니다.
  • 고객 서버 access token endpoint가 POST /v1/sdk/sessions를 호출합니다.
  • access token 요청 body는 {"email":"user@example.com"} 형태입니다.
  • partner API key는 고객 서버 환경변수 또는 secret manager에만 있고 브라우저에는 없습니다.
  • SDK token 응답의 expires_in은 1800입니다.
  • MonitorDogDetector.init() 직후에는 서버 호출이 없습니다.
  • detector.login({ email }) 시점에 sessionTokenProvider({ email })가 호출됩니다.
  • detector.start() 시점에 모델 로드와 카메라 권한 요청이 시작됩니다.
  • HTTPS 또는 localhost에서 카메라 권한을 허용했습니다.
  • 화면 이탈 또는 로그아웃 시 실행 중이면 detector.stop() 후 detector.logout() 또는 detector.dispose()가 호출됩니다.

SDK runtime API 목록​

브라우저 SDK token으로 접근하는 runtime API는 제한되어 있습니다.

호출 주체MethodPath목적
고객 서버 access token endpointPOST/v1/sdk/sessionsemail로 SDK access token 발급
브라우저 SDKGET/v1/auth/sdk-model암호화된 detector model 다운로드 정보 요청
브라우저 SDKGET/v1/account/me현재 SDK 사용자 확인
브라우저 SDKGET/v1/account/{uuid}/lock_policy사용자 감지 정책 확인
브라우저 SDKPOST/v1/eventlogin, logout, 감지 이벤트 기록
브라우저 SDKPOST/v1/file/image이벤트 이미지 업로드

외부 SDK flow에서는 refresh token, cookie refresh, password login, MFA 인증을 사용하지 않습니다. 다음 endpoint는 일반 웹/에이전트 인증 흐름용이며 SDK 브라우저 연동에서 호출하지 않습니다.

  • /v1/auth
  • /v1/auth/v2
  • /v1/auth/cookie
  • /v1/auth/mfa

Access token provider 오류​

401 또는 403​

partner API key가 잘못됐거나 누락된 경우가 많습니다.

확인할 항목:

  • 서버 환경변수 MONITORDOG_PARTNER_API_KEY가 설정되어 있습니다.
  • MonitorDog API 요청에 Authorization: Bearer <partner API key>가 들어갑니다.
  • 브라우저가 partner API key를 직접 보내고 있지 않습니다.

validation 오류​

현재 /v1/sdk/sessions body는 email-only 계약입니다.

{
  "email": "user@example.com"
}

account_uuid, external_user_id, external_session_id, scopes를 보내면 validation 오류가 발생합니다.

브라우저 SDK 오류​

MonitorDog sessionTokenProvider is required for SDK login.​

MonitorDogDetector.init() 옵션에 sessionTokenProvider가 없습니다.

const detector = await MonitorDogDetector.init({
  apiBaseUrl: "https://api.monitor.dog/v1",
  sessionTokenProvider: async ({ email }) => {
    const response = await fetch("/api/monitordog/access-token", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ email }),
    });

    return response.json();
  },
  onDetect: () => undefined,
});

init 후 access token provider가 호출되지 않음​

정상 동작입니다. init()은 detector 생성이며 서버 호출이 아닙니다. access token provider 호출은 detector.login({ email })에서 발생합니다.

token이 30분 뒤 만료됨​

정상 동작입니다. SDK token은 expires_in: 1800으로 발급됩니다. SDK는 만료 전 sessionTokenProvider({ email })를 다시 호출합니다. access token provider가 일시적으로 실패해도 현재 token이 아직 유효하면 SDK는 남은 유효 시간 동안 기존 token을 사용합니다.

카메라 오류​

권한 요청이 표시되지 않음​

  • 페이지가 HTTPS 또는 localhost에서 열렸는지 확인합니다.
  • 브라우저 site setting에서 camera 권한이 차단되지 않았는지 확인합니다.
  • detector.login({ email }) 후 detector.start()까지 호출됐는지 확인합니다.

camera permission denied​

사용자가 권한을 거부했거나 브라우저 정책에서 차단한 상태입니다. site setting에서 camera 권한을 허용한 뒤 다시 start()를 호출합니다.

Network 탭 확인 순서​

  1. detector.login({ email })
  2. 고객사 endpoint /api/monitordog/access-token
  3. 고객사 서버에서 MonitorDog POST /v1/sdk/sessions
  4. 브라우저 SDK에서 login activity POST /v1/event
  5. 브라우저 SDK에서 GET /v1/account/me
  6. 브라우저 SDK에서 GET /v1/account/{uuid}/lock_policy
  7. detector.start()
  8. 브라우저 SDK에서 GET /v1/auth/sdk-model
  9. detection 이벤트 발생 시 POST /v1/event와 POST /v1/file/image

이 순서에서 partner API key는 3번 서버 간 호출에만 존재해야 합니다.

목차

이 콘텐츠 공유