ZeroShot SDK

웹 애플리케이션에 시각적 버그 트래킹 위젯을 삽입하는 SDK입니다. 사용자가 페이지 위에서 직접 클릭하여 이슈를 생성하고, 스크린샷/네트워크 로그/콘솔 로그를 자동으로 수집합니다.

목차

• 주요 기능
• 설치
• 빠른 시작
• 동작 모드
• API 레퍼런스
• 설정 옵션
• 이벤트
• 키보드 단축키
• 위젯 기능
• 브라우저 지원
• FAQ
• 라이선스

주요 기능

• 클릭 기반 이슈 생성 — 페이지 위 원하는 위치를 클릭하여 마커 생성
• 자동 스크린샷 캡처 — 이슈 생성 시점의 화면을 자동으로 캡처
• 네트워크/콘솔 로그 수집 — 이슈 발생 전후의 네트워크 요청 및 콘솔 로그 자동 기록
• 화면 녹화 — 버그 재현 과정을 영상으로 기록
• 마커 표시 — 생성된 이슈를 페이지 위에 마커로 표시

설치

npm

npm install zeroshot

yarn

yarn add zeroshot

pnpm

pnpm add zeroshot

React 어댑터 사용 시 peer dependency

zeroshot/react를 사용할 경우 호스트 앱에 react, react-dom이 필요합니다.

CDN (script 태그)

<script src="https://cdn.zeroshot.dev/sdk/zeroshot.umd.js"></script>
<script>
  ZeroShot.init({ apiKey: 'YOUR_API_KEY' });
</script>

빠른 시작

엔트리포인트

• zeroshot/runtime — 프레임워크 비의존 코어 런타임 API (ZeroShot) (UI 마운트 없음)
• zeroshot/react — React 어댑터 API (ZeroShot, useZeroshot) (위젯 UI 마운트 포함)

화면 위젯(FAB/이슈 폼/마커)을 사용하려면 zeroshot/react 경로를 사용해야 합니다.

React / Next.js

useZeroshot 훅을 사용하면 초기화와 정리를 자동으로 처리합니다.

import { useZeroshot } from 'zeroshot/react';

function App() {
  useZeroshot({ apiKey: 'YOUR_API_KEY' });

  return <div>My Application</div>;
}

Vanilla JavaScript

import { ZeroShot } from 'zeroshot/runtime';

ZeroShot.init({ apiKey: 'YOUR_API_KEY' });

zeroshot/runtime은 코어 런타임 경로로, React UI 마운트 없이 SDK 엔진 라이프사이클/API 이벤트를 다룰 때 사용합니다.

HTML

<script src="https://cdn.zeroshot.dev/sdk/zeroshot.umd.js"></script>
<script>
  ZeroShot.init({ apiKey: 'YOUR_API_KEY' });
</script>

UMD(zeroshot.umd.js)는 런타임 경로 기준입니다. UMD 경로는 위젯 UI를 자동 마운트하지 않습니다.

동작 모드

SDK는 user 옵션 전달 여부에 따라 두 가지 모드로 동작합니다. 아래 화면 동작(폼/마커/FAB)은 zeroshot/react 경로로 위젯이 마운트된 상태를 기준으로 설명합니다.

익명 모드 (기본)

user 옵션 없이 초기화합니다. 이슈는 익명으로 생성되며, 사용자별 이슈 조회는 불가능합니다.

useZeroshot({ apiKey: 'YOUR_API_KEY' });

| 항목 | 동작 | | ----------- | ------------------ | | 이슈 생성 | 익명으로 생성 | | 이슈 조회 | 불가 (생성만 가능) | | 보고자 표시 | 표시 안 됨 |

사용자 식별 모드

호스트 앱의 사용자 정보를 user에 전달합니다. 이슈에 보고자 정보가 기록되고, 해당 사용자가 생성한 이슈만 조회할 수 있습니다.

useZeroshot({
  apiKey: 'YOUR_API_KEY',
  user: {
    id: 'user-123',
    name: 'Hong Gildong',
  },
});

| 항목 | 동작 | | ----------- | -------------------------------- | | 이슈 생성 | 사용자 정보와 함께 생성 | | 이슈 조회 | 해당 사용자가 생성한 이슈만 표시 | | 보고자 표시 | user.name으로 표시 |

멤버 모드

워크스페이스에 등록된 멤버 계정으로 로그인합니다. FAB 메뉴의 "멤버 로그인"을 통해 진입할 수 있습니다. 멤버 모드에서는 프로젝트의 모든 이슈를 조회/관리할 수 있으며, 마커를 페이지 위에 표시합니다.

| 항목 | 동작 | | --------- | ----------------------------------------- | | 이슈 생성 | 멤버 계정으로 생성 | | 이슈 조회 | 프로젝트의 모든 이슈 조회 가능 | | 마커 | 현재 페이지의 이슈를 마커로 표시 | | 이슈 관리 | 상태 변경, 심각도 변경, 댓글 등 전체 기능 |

API 레퍼런스

useZeroshot(config)

React 커스텀 훅. 컴포넌트 마운트 시 SDK를 초기화하고, 언마운트 시 자동으로 정리합니다.

import { useZeroshot } from 'zeroshot/react';

function App() {
  useZeroshot({
    apiKey: 'YOUR_API_KEY',
    user: { id: 'user-123', name: 'Hong Gildong' },
  });

  return <div>My App</div>;
}

config.apiKey, config.user, config.enabled가 변경되면 SDK를 자동으로 재초기화합니다.

ZeroShot.init(config)

SDK 코어 런타임을 초기화합니다. 이 API(zeroshot/runtime)는 위젯 UI를 자동 마운트하지 않습니다. React 환경에서는 useZeroshot 훅 사용을 권장합니다.

import { ZeroShot } from 'zeroshot/runtime';

ZeroShot.init(config: SDKConfig): void

| 이름 | 타입 | 필수 | 설명 | | -------- | ----------- | ---- | ------------- | | config | SDKConfig | Yes | SDK 설정 객체 |

이미 초기화된 상태에서 다시 호출하면, 기존 런타임 상태를 정리한 뒤 새로 초기화합니다.

ZeroShot.destroy()

SDK 코어 런타임을 종료합니다. zeroshot/runtime 경로에서는 위젯 언마운트를 수행하지 않습니다.

ZeroShot.destroy(): void

ZeroShot.on(event, callback)

SDK 이벤트를 구독합니다.

ZeroShot.on(event: SDKEvent, callback: (...args: unknown[]) => void): void

예시:

ZeroShot.on('issue:created', (issue) => {
  console.log('새 이슈:', issue);
});

ZeroShot.on('error', (error) => {
  console.error('SDK 오류:', error);
});

ZeroShot.off(event, callback)

등록된 이벤트 구독을 해제합니다.

ZeroShot.off(event: SDKEvent, callback: (...args: unknown[]) => void): void

예시:

const handler = (issue) => console.log(issue);
ZeroShot.on('issue:created', handler);

// 나중에 구독 해제
ZeroShot.off('issue:created', handler);

설정 옵션

SDKConfig

| 속성 | 타입 | 필수 | 설명 | | --------- | --------- | ---- | -------------------------------------------------------------- | | apiKey | string | Yes | ZeroShot API 키. 대시보드에서 발급 | | user | SDKUser | No | 호스트 앱의 사용자 정보. 전달 시 사용자 식별 모드로 동작 | | enabled | boolean | No | SDK 활성화 여부 (기본값: true). useZeroshot 훅 전용 |

SDKUser

| 속성 | 타입 | 필수 | 설명 | | ------ | -------- | ---- | ------------------ | | id | string | Yes | 사용자 고유 식별자 | | name | string | Yes | 사용자 표시 이름 |

이벤트

SDK는 다양한 이벤트를 발생시켜 위젯의 상태 변화를 알려줍니다.

| 이벤트 | 발생 시점 | 콜백 인자 | | ------------------- | ------------------- | ------------------- | | ready | SDK 초기화 완료 | — | | error | 오류 발생 | error: string | | issue:created | 이슈 생성 완료 | issue: object | | issue:updated | 이슈 수정 완료 | issue: object | | issue:clicked | 마커 클릭 | issueId: string | | mode:changed | 이슈 생성 모드 변경 | isActive: boolean | | recording:started | 화면 녹화 시작 | — | | recording:stopped | 화면 녹화 종료 | — | | auth:login | 멤버 로그인 성공 | — | | auth:logout | 로그아웃 완료 | — |

키보드 단축키

| 단축키 | 기능 | | -------------------- | ------------------- | | Ctrl/Cmd + Alt + 1 | 이슈 생성 모드 토글 | | Ctrl/Cmd + Alt + 2 | 화면 녹화 시작/중지 | | Esc | 이슈 생성 모드 종료 |

위젯 기능

FAB (Floating Action Button)

zeroshot/react 경로로 SDK를 초기화하면 우측 하단에 플로팅 버튼이 나타납니다.

| 메뉴 | 설명 | 조건 | | ---------------- | ------------------------ | -------------- | | 이슈 생성 | 이슈 생성 모드 진입/종료 | 항상 표시 | | 화면 녹화 | 화면 녹화 시작/중지 | 항상 표시 | | 마커 보기/숨기기 | 마커 표시 토글 | 멤버 로그인 시 | | 멤버 로그인 | 워크스페이스 멤버 로그인 | 비로그인 시 | | 로그아웃 | 멤버 로그아웃 | 로그인 시 |

이슈 생성 모드

이슈 생성은 스크린샷 모드와 영상 녹화 모드 두 가지 방식을 지원합니다.

스크린샷 모드

이슈 생성 시점의 화면을 정지 이미지로 캡처합니다.

1. FAB 메뉴에서 "이슈 생성" 클릭 또는 Ctrl/Cmd + Alt + 1
2. 커서가 십자 모양으로 변경되고, 마우스 오버 시 요소가 하이라이트됨
3. 원하는 위치 클릭 → 이슈 생성 폼 표시 (스크린샷 자동 첨부)
4. 폼 작성 후 제출

영상 녹화 모드

버그 재현 과정을 영상으로 기록한 후 이슈에 첨부합니다.

1. FAB 메뉴에서 "화면 녹화" 클릭 또는 Ctrl/Cmd + Alt + 2
2. 화면 녹화가 시작됨 (녹화 인디케이터 표시)
3. 버그를 재현한 후, FAB 메뉴에서 "녹화 중지" 클릭 또는 Ctrl/Cmd + Alt + 2
4. 녹화 종료 후 자동으로 이슈 생성 모드 진입
5. 원하는 위치 클릭 → 이슈 생성 폼 표시 (녹화 영상 자동 첨부)
6. 폼 작성 후 제출

참고: SDK의 영상 녹화는 브라우저 getDisplayMedia API를 사용합니다. 녹화 중 페이지를 리로드하거나 다른 페이지로 이동하면 녹화가 중단되며 녹화 데이터가 유실됩니다. 페이지 이동에도 끊김 없는 녹화가 필요한 경우, ZeroShot Chrome Extension을 설치하면 백그라운드 녹화를 지원하여 페이지 리로드에도 녹화가 유지됩니다.

자동 수집 데이터

| 데이터 | 설명 | | ------------- | ---------------------------------------------- | | 스크린샷 | 클릭 시점의 페이지 스크린샷 | | 영상 | 화면 녹화 영상 (녹화 모드 사용 시) | | 네트워크 로그 | 최근 50개 네트워크 요청 (URL, 상태, 소요 시간) | | 콘솔 로그 | 최근 50개 콘솔 출력 (log, warn, error) | | User Agent | 브라우저 및 OS 정보 | | 클릭 위치 | 클릭한 요소의 CSS 선택자 및 XPath |

브라우저 지원

| 브라우저 | 최소 버전 | | -------- | --------- | | Chrome | 90+ | | Firefox | 90+ | | Safari | 15+ | | Edge | 90+ |

FAQ

API 키는 어디서 발급받나요?

ZeroShot 대시보드에서 프로젝트를 생성한 후 SDK 설정 페이지에서 API 키를 발급받을 수 있습니다.

호스트 페이지의 CSS에 영향을 주나요?

zeroshot/react 경로를 사용하는 경우, SDK 위젯은 호스트 페이지의 스타일과 격리되어 동작합니다. 단, 이슈 생성 모드에서 커서 변경과 요소 하이라이트를 위한 최소한의 스타일이 추가됩니다.

SPA(Single Page Application)에서 사용할 수 있나요?

네. URL 변경을 자동으로 감지하여 새 페이지의 이슈를 로드합니다. 위젯 UI까지 사용하려면 useZeroshot를 zeroshot/react에서 import해 앱 최상위에서 사용하는 방식을 권장합니다.

Invalid hook call / Cannot read properties of null (reading 'useRef') 오류가 나요

이 오류는 대부분 호스트 앱에 React 인스턴스가 2개 이상 로드될 때 발생합니다.

1. 의존성 중복 확인

npm ls react react-dom

react, react-dom이 단일 버전으로 정리되어 있는지 확인하세요.

2. Vite 사용 시 dedupe 설정

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    dedupe: ['react', 'react-dom'],
  },
});

Webpack/Next.js 사용 시에는 alias로 React 경로를 단일화하세요.

// next.config.js 또는 webpack config
const path = require('path');

module.exports = {
  webpack: (config) => {
    config.resolve.alias = {
      ...(config.resolve.alias || {}),
      react: path.resolve(__dirname, 'node_modules/react'),
      'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
    };
    return config;
  },
};

3. import 경로 점검

• React 환경: import { useZeroshot } from 'zeroshot/react'
• 비 React 환경: import { ZeroShot } from 'zeroshot/runtime'

루트(zeroshot)에서 React 훅을 import하지 않도록 주의하세요. zeroshot/react를 사용할 때는 호스트 앱에 react, react-dom이 반드시 설치되어 있어야 합니다.

[plugin:vite:import-analysis] Missing "./react" specifier in "zeroshot" package 오류가 보이면, 설치된 SDK tarball/lockfile이 오래된 상태일 가능성이 큽니다. node_modules와 lockfile을 갱신한 뒤 SDK를 재설치하세요.

리액트 없이도 사용할 수 있나요?

네. zeroshot/runtime으로 코어 런타임 초기화/이벤트 연동은 가능합니다. 다만 FAB/이슈 폼/마커 같은 위젯 UI 기능은 zeroshot/react 경로(React 환경)에서만 동작합니다.

user 정보를 넣으면 어떤 효과가 있나요?

동작 모드 섹션을 참조하세요. user.id를 전달하면 사용자 식별 모드로 동작하여 해당 사용자가 생성한 이슈만 조회할 수 있고, user.name이 보고자로 기록됩니다.

이슈 데이터는 어디에 저장되나요?

ZeroShot 클라우드 서버에 안전하게 저장됩니다. API 키에 연결된 프로젝트에 이슈가 귀속됩니다.

프로덕션 환경에서도 사용해도 되나요?

네. 다만 일반 사용자에게 노출하지 않으려면 특정 조건(예: 관리자 모드, 스테이징 환경)에서만 SDK를 초기화하도록 분기 처리하는 것을 권장합니다.

import { useZeroshot } from 'zeroshot/react';

function App() {
  useZeroshot({
    apiKey: 'YOUR_API_KEY',
    enabled: isAdminMode || isStagingEnv,
  });

  return <div>My App</div>;
}

라이선스

Copyright (c) 2026 maana. All rights reserved.

이 소프트웨어는 maana의 독점 소유물입니다. 자세한 내용은 LICENSE 파일을 참조하세요.