SDK Headless API

이 문서가 필요한 경우

이슈스티커 위젯 UI를 띄우지 않고 SDK 초기화 상태만 앱에서 다루고 싶습니다.
SDK 준비, 오류, 이슈 생성 같은 이벤트를 기존 제품 분석 흐름에 연결해야 합니다.
직접 이슈 제출 API가 공개되어 있는지 확인해야 합니다.

끝나면 확인할 것

issue-sticker/runtime의 공개 범위가 init, destroy, on, off임을 확인했습니다.
위젯 UI, 이슈 폼, 마커가 자동으로 붙지 않는다는 점을 이해했습니다.
실제 이슈 생성 UI가 필요하면 issue-sticker/react로 전환하기로 결정했습니다.

언제 쓰나요

Headless 방식은 이슈스티커 위젯 UI를 띄우지 않고, 호스트 앱에서 SDK lifecycle과 이벤트만 직접 다루고 싶을 때 씁니다.

현재 공개된 headless 범위는 init, destroy, on, off입니다. 이슈 생성 폼이나 마커 UI는 마운트되지 않습니다. UI까지 쓰려면 issue-sticker/react를 사용하세요.

Headless API는 UI 없는 이슈 제출 API가 아닙니다. 제품 안에서 피드백을 실제로 받으려면 SDK Widget을 사용하세요.

설치와 import

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

issue-sticker/runtime은 React를 요구하지 않습니다. 대신 FAB, 이슈 폼, 마커 같은 화면 요소도 자동으로 붙지 않습니다.

init

SDK runtime을 초기화합니다. 이미 초기화된 상태에서 다시 호출하면 설정만 갱신됩니다.

IssueSticker.init({
  apiKey: 'pk_live_xxx',
  user: { id: 'user-123', name: '홍길동' },
});

apiKey는 필수입니다. user는 선택값이며, 전달하면 사용자 식별 모드로 동작합니다.

이벤트 구독

초기화 전에도 on을 먼저 걸 수 있습니다. SDK가 준비되면 등록된 listener가 runtime event bus에 연결됩니다.

IssueSticker.on('ready', () => {
  console.log('IssueSticker runtime ready');
});

IssueSticker.on('error', (error) => {
  console.error('IssueSticker error', error);
});

지원 이벤트는 아래와 같습니다.

이벤트	설명
`ready`	runtime 초기화 완료
`error`	SDK 오류
`issue:created`	이슈 생성 완료
`issue:updated`	이슈 수정 완료
`issue:clicked`	마커 클릭
`mode:changed`	이슈 생성 모드 변경
`recording:started`	녹화 시작
`recording:stopped`	녹화 종료
`auth:login`	멤버 로그인 성공
`auth:logout`	로그아웃 완료

Headless runtime만 쓸 때는 UI에서 발생하는 이벤트가 자연스럽게 제한됩니다. 실제 이슈 생성 UI가 필요하면 React 위젯 경로로 전환하세요.

구독 해제와 정리

const handleReady = () => console.log('ready');

IssueSticker.on('ready', handleReady);
IssueSticker.off('ready', handleReady);
IssueSticker.destroy();

SPA에서 페이지나 feature flag에 따라 SDK를 껐다 켜야 한다면, 화면을 떠날 때 destroy()를 호출해 listener를 정리하세요.

현재 범위

Headless API는 “UI 없는 이슈 제출 API”가 아닙니다. 지금은 runtime 초기화와 이벤트 연결을 안정적으로 다루는 용도입니다. 직접 이슈 제출까지 필요하다면 SDK Widget을 쓰거나, 별도 API 공개 범위를 정한 뒤 붙이는 편이 안전합니다.

확인할 증거

다음 단계