SDK Widget 시작하기

이 문서가 필요한 경우

고객, 베타 테스터, 내부 사용자가 제품 안에서 직접 피드백을 남기는 경우
피드백 도구를 제품 기능에 통합할 필요가 없으며, 스테이징 환경이나 선택된 일부 사용자 등 특정 조건에서만 활성화하는 것으로 충분한 경우

시작하기 전에

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

SDK는 프로젝트에 등록된 도메인과 API key 기준으로 초기화되므로, 둘 중 하나라도 빠지면 위젯이 뜨지 않습니다. 아직 완료하지 않은 부분이 있다면 시작 준비를 끝내고 오세요.

끝나면 확인할 것

앱에 SDK를 설치하고 API key를 환경 변수로 넣었습니다.
원하는 조건에서만 위젯 버튼이 보이고, 테스트 피드백이 관리자 콘솔에 저장됐습니다.

1. SDK 설치하기

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

npm install issue-sticker

SDK Widget은 현재 React 기반 프로젝트만 지원합니다. 지원 대상 프레임워크는 주기적으로 확대할 예정입니다.

2. 앱에 초기화하기

앱의 최상위 레이아웃이나 인증된 영역에서 한 번만 초기화하세요.

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

export function AppShell({ user, children }) {
  useIssueSticker({
    apiKey: process.env.NEXT_PUBLIC_ISSUE_STICKER_SDK_KEY!,
    user: user ? { id: user.id, name: user.name } : undefined,
  });

  return children;
}

user를 넘기면 보고자 이름이 남고, 사용자는 본인과 관련된 이슈를 구분할 수 있습니다. 고객에게 익명 피드백만 받는다면 user 없이 시작해도 됩니다.

3. 운영에서 켜는 조건 정하기

모든 사용자에게 항상 보여줄지, 베타 사용자나 관리자에게만 보여줄지 먼저 정하세요. 조건이 필요하면 enabled로 분기합니다.

useIssueSticker({
  apiKey: process.env.NEXT_PUBLIC_ISSUE_STICKER_SDK_KEY!,
  enabled: user?.role === 'admin' || user?.flags?.betaFeedback === true,
});

enabled가 false면 위젯이 뜨지 않고, 값이 바뀌면 그 시점에 다시 켜지거나 사라집니다.

4. 첫 피드백 확인하기

위젯 FAB를 클릭하면 이슈 생성, 표시 형식 변경, 스티커 on/off 등의 기능을 사용할 수 있습니다.

처음 연결한 뒤에는 실제 고객 화면과 가까운 페이지에서 한 번 남겨보세요. 이슈가 원하는 프로젝트에 생성되는지, 이슈 발생 URL과 콘솔/네트워크 로그 같은 환경 정보, 세션 리플레이 같은 재현 정보가 함께 담기는지 확인해보세요.

문제가 생겼을 때 먼저 확인할 것

초기화가 실패하면 프로젝트에 등록된 도메인과 현재 window.location.origin이 같은지 확인합니다.
React hook 오류가 나면 앱에 react와 react-dom이 중복 설치되어 있는지 확인합니다.
특정 사용자에게만 보이게 했다면 enabled 조건이 실제 로그인 상태와 맞는지 확인합니다.

다음 단계