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(툴바, 이슈 폼, 마커)를 마운트하는 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 전달 | 해당 사용자가 만든 이슈 | 자기가 만든 이슈만 | | 멤버 | 툴바의 "멤버 로그인" | 프로젝트의 모든 이슈 | 프로젝트의 모든 이슈 |

위젯 기능

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

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

단축키

| 기능 | 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' | X | 온보딩 가이드 트리거. 기본값 'onMount'. 'off'면 "가이드 다시 보기" 버튼도 숨겨집니다 | | toolbar | { corner?, offset? } | X | 툴바 초기 위치. corner는 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'(기본 'bottom-right'), offset은 코너로부터의 px(기본 { x: 20, y: 20 }). 사용자가 드래그해 저장한 위치가 있으면 그쪽이 우선합니다 | | screenshotCompression | { useWebWorker?: boolean } | X | 스크린샷 압축을 Web Worker에서 할지 여부 | | enabled | boolean | X | 위젯 활성화 여부. 기본값 true. useIssueSticker 전용 |

툴바 셀렉터

호스트 페이지에서 툴바 위치를 알아야 한다면 [data-issue-sticker-toolbar]로 찾으세요. 이 속성은 공개 계약이며 버전 간 유지됩니다. 내부 클래스명은 계약이 아니므로 의존하지 마세요.

컴포넌트가 마운트되면 위젯을 초기화하고, 언마운트되면 정리합니다. 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 가이드에 있습니다.

three.js 화면 등록

WebGL 캔버스는 브라우저가 화면에 합성한 뒤 내용을 비웁니다. 스크린샷을 찍는 시점에는 읽을 것이 남아 있지 않아, 3D 화면이 빈 채로 첨부됩니다.

화면을 계속 다시 그리는 앱은 이슈스티커가 알아서 한 프레임을 받아 채웁니다. 변경이 있을 때만 그리는 앱(3D 편집기, 제품 컨피규레이터)은 렌더러를 등록해야 찍힙니다.

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

const unregister = IssueSticker.registerThree({ renderer, scene, camera });

Headless 에서는 같은 이름의 함수를 가져옵니다.

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

const unregister = registerThree({ renderer, scene, camera });

등록하면 캡처 순간에 한 프레임을 더 그린 뒤 바로 읽습니다. 렌더러를 정리할 때는 반환된 함수를 호출합니다.

three 네임스페이스를 함께 넘기면, 3D 화면을 클릭했을 때 어떤 오브젝트를 눌렀는지 이름으로 세션 리플레이 로그에 남습니다. 그 시점의 화면 한 장과 카메라 위치도 함께 기록됩니다.

import * as THREE from 'three';

IssueSticker.registerThree({ renderer, scene, camera, three: THREE });

오브젝트에 name 을 붙여 두면 그 이름이 그대로 로그에 나옵니다. 이름이 없으면 이름이 붙은 상위 그룹까지 올라가 찾습니다.

수집하는 정보

init()이 끝난 시점부터 위젯이 호스트 페이지의 fetch, XMLHttpRequest, console을 감싸 네트워크 요청과 콘솔 출력을 메모리에 수집합니다. 이슈를 만들 때 그 시점의 최근 기록이 함께 첨부됩니다. 사용자가 이슈를 만들지 않으면 아무것도 전송되지 않습니다.

호스트 앱에 영향을 주지 않도록 다음을 지킵니다.

• 다른 라이브러리가 이미 감싼 fetch·XMLHttpRequest 래퍼를 보존합니다. destroy()로 정리할 때도 타 라이브러리 래퍼를 지우지 않습니다.
• 스트리밍 응답의 본문은 캡처하지 않습니다. 응답은 먼저 호출자에게 돌려주고 본문은 나중에 채웁니다.
• 계측 내부에서 난 예외는 호출자에게 전파하지 않습니다. 예외가 반복되면 수집기가 스스로 패치를 걷어냅니다.
• 자격증명으로 보이는 값, 국내 식별번호, 결제 관련 필드는 저장 전에 제거합니다.

문제 해결

• 위젯이 보이지 않으면 프로젝트에 등록한 허용 도메인과 현재 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를 참조하세요.