SDK Widget 시작하기

이 문서가 필요한 경우

고객, 베타 사용자, 내부 사용자가 제품 안에서 직접 피드백을 남겨야 합니다.
모바일 웹, 웹뷰, SPA처럼 Extension만으로는 충분하지 않습니다.
피드백을 남긴 사용자의 식별값을 함께 보고 싶습니다.

끝나면 확인할 것

SDK를 띄울 운영, 스테이징, 로컬 origin을 프로젝트에 등록했습니다.
프로젝트용 SDK API key를 만들고 안전한 환경 변수에 넣었습니다.
위젯 버튼이 보이고, 테스트 피드백이 관리자 화면에 저장됐습니다.

1. 프로젝트를 먼저 만듭니다

SDK key는 프로젝트 단위로 발급됩니다. 고객 피드백을 받을 서비스가 하나라면 프로젝트도 하나로 시작하면 됩니다. 운영 앱과 관리자 앱처럼 흐름이 분리되어 있다면 프로젝트도 나누는 편이 관리하기 쉽습니다.

2. 허용 도메인을 등록합니다

SDK는 승인된 origin에서만 초기화됩니다. 관리자 화면의 프로젝트 도메인 관리에서 실제로 SDK를 띄울 주소를 등록합니다.

운영: https://app.example.com
스테이징: https://staging.example.com
로컬 확인: http://localhost:3000

도메인이 승인되지 않으면 API key가 맞아도 public init 단계에서 막힙니다. key를 만들기 전에 도메인부터 정리하세요.

3. SDK API key를 만듭니다

프로젝트 설정에서 SDK API key를 생성합니다. 생성된 전체 key는 한 번만 보입니다. 닫기 전에 설치 코드와 key를 프로젝트의 안전한 환경 변수로 옮겨두세요.

권장 scope는 처음에는 아래 세 가지입니다.

issues:create
issues:read
media:write

4. React 앱에 설치합니다

React 환경에서는 issue-sticker/react를 사용합니다. 앱의 최상위 레이아웃이나 인증된 영역에 한 번만 초기화하세요.

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 없이 시작해도 됩니다.

5. 운영에서 켜는 조건을 정합니다

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

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

6. 첫 피드백을 확인합니다

위젯 버튼이 보이면 이슈 생성, 화면 녹화, 마커 보기/숨기기를 확인합니다. 이슈가 저장되면 관리자 화면에서 URL, 스크린샷, 로그가 함께 들어왔는지 확인하세요.

처음 연결한 뒤에는 실제 고객 화면과 가까운 페이지에서 한 번 남겨보세요. 사용자 식별값, 현재 URL, 콘솔/네트워크 로그가 기대한 프로젝트에 들어오는지 확인하는 것이 첫 성공 기준입니다.

막히면 먼저 볼 것

위젯이 안 보이면 React import 경로가 issue-sticker/react인지 확인합니다.
public init이 실패하면 허용 도메인과 현재 window.location.origin이 같은지 확인합니다.
React hook 오류가 나면 앱에 react와 react-dom이 중복 설치되어 있는지 확인합니다.
특정 사용자에게만 보이게 했다면 enabled 조건이 실제 로그인 상태와 맞는지 확인합니다.

SDK Headless API 보기

확인할 증거

다음 단계