SDK Headless 시작하기

이 문서가 필요한 경우

이슈 리포팅 버튼과 폼을 제품 디자인에 맞춰 직접 만드는 경우
사용자 입력 없이 원하는 시점에 이슈를 생성하도록 코드로 제어하는 경우
React 외의 환경에 붙여야 하는 경우

시작하기 전에

관리자 콘솔에서 프로젝트, 허용 도메인, SDK API key를 먼저 준비해야 합니다.

headless 클라이언트도 SDK Widget과 같은 API key로 초기화되고, 등록되지 않은 도메인에서는 초기화가 통과하지 않습니다. 아직 완료하지 않은 부분이 있다면 시작 준비를 끝내고 오세요.

끝나면 확인할 것

앱에 SDK를 설치하고 issue-sticker/headless에서 클라이언트를 만들었습니다.
상태를 구독하고 초기화까지 끝냈습니다.
직접 만든 버튼에서 캡처를 시작해 이슈를 한 건 남겼습니다.

headless 클라이언트란

이슈스티커 SDK는 바로 쓸 수 있는 위젯 UI(issue-sticker/react)를 기본 제공합니다. headless 클라이언트는 이 화면을 그리지 않습니다.

대신 이슈 생성과 조회에 필요한 동작(캡처 시작, 초안 수정, 제출 등)을 메서드로 제공하고, 현재 상태를 snapshot으로 넘겨줍니다. 이 상태를 구독해 원하는 UI를 그리면 됩니다.

1. SDK 설치하기

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

npm install issue-sticker

headless 클라이언트는 issue-sticker/headless에서 가져옵니다. React, Vue, 바닐라 등 프레임워크에 상관없이 사용할 수 있습니다.

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

이슈 상세 화면을 React로 만든다면 세션 리플레이 뷰어는 따로 제공되는 헬퍼를 쓸 수 있습니다. UI 헬퍼를 참고하세요.

2. 클라이언트 만들고 초기화하기

클라이언트를 만들고, 상태를 구독한 뒤, 초기화합니다. 이 세 단계면 이슈를 만들고 불러올 준비가 끝납니다.

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

// 1. 클라이언트 생성 — 발급받은 API key를 넣습니다.
const client = createIssueStickerHeadless({
  apiKey: 'YOUR_API_KEY',
  user: { id: currentUser.id, name: currentUser.name }, // 선택: 사용자 식별
});

// 2. 상태 구독 — 상태가 바뀔 때마다 직접 만든 UI를 다시 그립니다.
const unsubscribe = client.subscribe((snapshot) => {
  renderYourUI(snapshot);
});

// 3. 초기화 — API key를 확인하고 사용할 준비를 마칩니다.
await client.initialize();

// 이제 이슈를 불러오거나
await client.refreshIssues();
// 새 이슈 만들기를 시작할 수 있습니다.
captureButton.onclick = () => client.startIssueCapture();

여기까지 왔다면 상태 모델을 볼 차례입니다. phase와 snapshot을 이해하면 어떤 화면을 언제 그릴지 판단할 수 있습니다.

phase와 snapshot 보기

남길 정보

다음 단계