issue-sticker

이 문서는 이슈스티커 SDK(IssueSticker SDK for JavaScript) 사용 방법을 안내합니다.

사용자가 화면을 클릭해 이슈를 남기면 스크린샷과 콘솔·네트워크 로그, 브라우저 정보가 함께 기록됩니다.

준비

지원 환경

issue-sticker/react와 issue-sticker/headless/react는 React 어댑터입니다. 앱에 react, react-dom 18 또는 19가 설치되어 있어야 합니다.

issue-sticker/headless는 React를 요구하지 않습니다. 프레임워크에 상관없이 사용할 수 있습니다.

API key 발급

관리자 콘솔에서 프로젝트를 만들고, 위젯을 노출할 도메인을 허용 도메인으로 등록한 뒤 SDK API key를 발급받아야 합니다. SDK는 API key와 등록된 도메인을 기준으로 초기화합니다. 둘 중 하나라도 빠지면 위젯이 나타나지 않습니다.

발급 절차는 시작 준비에 있습니다.

설치

앱에 issue-sticker 패키지를 설치합니다.

npm install issue-sticker

| 경로 | 용도 | | ------------------------------ | ------------------------------------------------------- | | issue-sticker/react | 위젯 UI(FAB, 이슈 폼, 마커)를 마운트하는 React 어댑터 | | issue-sticker/headless | UI 없이 이슈 흐름을 구독하고 제어하는 컨트롤러 API | | issue-sticker/headless/react | Headless UI를 직접 만들 때 사용하는 최소 React 헬퍼 |

초기화

이슈스티커 초기화를 위한 컴포넌트를 생성합니다.

'use client'; // Next.js App Router

import { useIssueSticker } from 'issue-sticker/react';

export function IssueStickerWidget() {
  const { user } = useAuth(); // 앱의 사용자 정보

  useIssueSticker({
    apiKey: process.env.NEXT_PUBLIC_ISSUE_STICKER_SDK_KEY!,
    user: user ? { id: user.id, name: user.name } : undefined, // 사용자 식별
    enabled: isStaging || user?.role === 'admin', // 노출 조건
  });

  return null;
}

사용자 식별

| 모드 | 설정 | 이슈 조회 범위 | 수정·삭제 | | ----------- | ------------------- | ------------------------------------------------- | ------------------------- | | 익명 | user 없이 초기화 | 조회 없음 (이번 세션에서 만든 이슈만 화면에 표시) | 불가 (자기가 만든 이슈도) | | 사용자 식별 | user 전달 | 해당 사용자가 만든 이슈 | 자기가 만든 이슈만 | | 멤버 | FAB의 "멤버 로그인" | 프로젝트의 모든 이슈 | 프로젝트의 모든 이슈 |

위젯 기능

초기화를 마치면 화면 오른쪽 아래에 FAB가 표시됩니다. FAB는 아래 기능을 제공하며, 드래그로 위치를 옮길 수 있습니다.

• 이슈 생성
• 화면 녹화
• 마커 표시 토글
• 마커 기준 전환(생성 위치 기준 / 대상 요소 기준)
• 미표시 스티커 확인
• 가이드 다시 보기
• 멤버 로그인·로그아웃

단축키

| 기능 | macOS | Windows·Linux | | ------------------- | ----------- | ------------- | | 이슈 생성 모드 토글 | ⌘⌥1 ⌃⌥1 | Ctrl+Alt+1 | | 화면 녹화 시작/중지 | ⌘⌥2 ⌃⌥2 | Ctrl+Alt+2 | | 이슈 생성 모드 종료 | Esc | Esc |

설정

| 속성 | 타입 | 필수 | 설명 | | ----------------------- | ------------------------------------ | ---- | ------------------------------------------------------------------------------------------- | | apiKey | string | O | 관리자 콘솔에서 발급한 SDK API key | | user | SDKUser | X | 앱의 사용자 정보. 제공하면 작성자가 기록되고 자기 이슈를 조회·수정·삭제할 수 있습니다 | | onboarding | 'off' \| 'onMount' \| 'onFABClick' | X | 온보딩 가이드 트리거. 기본값 'onMount'. 'off'면 "가이드 다시 보기" 버튼도 숨겨집니다 | | screenshotCompression | { useWebWorker?: boolean } | X | 스크린샷 압축을 Web Worker에서 할지 여부 | | enabled | boolean | X | 위젯 활성화 여부. 기본값 true. useIssueSticker 전용 |

컴포넌트가 마운트되면 위젯을 초기화하고, 언마운트되면 정리합니다. apiKey나 enabled가 바뀌면 위젯을 다시 초기화하고, user만 바뀌면 위젯을 유지한 채 설정만 갱신합니다.

훅 없이 초기화하기

React 훅을 사용할 수 없는 경우 IssueSticker로 직접 제어합니다.

import { IssueSticker } from 'issue-sticker/react';

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

init(config)

init(config: SDKConfig): void

SDK를 초기화하고 위젯을 마운트합니다. 이미 초기화된 상태에서 다시 호출하면 설정을 갱신하고 위젯을 다시 마운트합니다.

updateConfig(config)

updateConfig(config: SDKConfig): void

위젯을 유지한 채 설정만 교체합니다. 초기화 전에 호출하면 init과 같게 동작합니다.

destroy()

destroy(): void

위젯을 언마운트하고 SDK를 종료합니다.

Headless 클라이언트

이슈 리포팅 버튼과 폼을 제품 디자인에 맞춰 직접 만들 때 사용합니다. 클라이언트를 만들고, 상태를 구독하고, 초기화하면 준비가 끝납니다.

import { createIssueStickerHeadless } from 'issue-sticker/headless';

const client = createIssueStickerHeadless({
  apiKey: 'YOUR_API_KEY',
  user: { id: currentUser.id, name: currentUser.name },
});

const unsubscribe = client.subscribe((snapshot) => renderYourUI(snapshot));

await client.initialize();
await client.refreshIssues();

captureButton.onclick = () => client.startIssueCapture();

클라이언트는 현재 상태를 읽기 전용 snapshot으로 넘겨줍니다. 메서드 전체, phase와 snapshot 모델, 동적 필드 descriptor, 에러 코드는 Headless 가이드에 있습니다.

문제 해결

• 위젯이 보이지 않으면 프로젝트에 등록한 허용 도메인과 현재 window.location.origin이 같은지 확인하세요.
• 특정 사용자에게만 노출했다면 enabled 조건이 실제 로그인 상태와 맞는지 확인하세요.
• Invalid hook call 또는 Cannot read properties of null (reading 'useRef')는 대부분 React가 두 벌 로드된 경우입니다. npm ls react react-dom으로 확인하고, Vite는 resolve.dedupe: ['react', 'react-dom']을, Webpack·Next.js는 alias로 React 경로를 하나로 맞추세요.
• Missing "./react" specifier in "issue-sticker" package는 설치된 패키지가 오래된 경우입니다. node_modules와 lockfile을 지우고 다시 설치하세요.

더 보기

| 가이드 | 내용 | | ---------------------------------------------------------------- | --------------------------------------------- | | 시작 준비 | 프로젝트 생성, 허용 도메인 등록, API key 발급 | | SDK Widget | 위젯 설치, 초기화, 운영 환경에서 켜는 조건 | | SDK Headless | 메서드, phase와 snapshot, 에러 코드 레퍼런스 | | 외부 연동 | Jira·Notion 연결과 필드 동기화 | | FAQ | 권한, 도메인, key, 필드 동기화 문제 해결 |

라이선스

Copyright (c) 2026 maana. All rights reserved.

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