문서
WebQuestion은 이벤트가 발생한 순간, 질문 하나를 띄우는 마이크로서베이입니다. 설치는 5분이면 충분합니다.
1. 개념
대시보드에서 질문 1개 + 답변 옵션(최대 10개)을 만들고 트리거 이벤트 이름(예: export_completed)을 지정합니다. 그리고 제품 코드에서 그 순간에 wq.trigger("export_completed") 한 줄을 호출하면 끝입니다.
- 팝업은 사용자의 마지막 클릭 위치 근처에 뜹니다 (없으면 화면 우하단).
- Shadow DOM으로 렌더링되어 사이트의 CSS와 충돌하지 않습니다.
- 노출 빈도(사용자당 1회 등)는 대시보드 설정대로 SDK가 알아서 제어합니다.
- 응답과 함께 시간·URL·언어·화면 크기 등이 자동 수집됩니다.
2. 설치 A — 스크립트 태그 (가장 간단)
어떤 웹사이트든 동작합니다. pk_XXXX는 대시보드 각 서베이의 설치 탭에서 내 키가 채워진 코드를 복사할 수 있습니다.
<script src="https://wq.honenuki.com/wq.js" data-key="pk_XXXX"></script>
<script>
// 질문을 띄우고 싶은 순간에 한 줄
wq.trigger("export_completed");
</script>
3. 설치 B — npm SDK (React 등)
npm install @webquestion/sdk
import * as wq from "@webquestion/sdk";
// 앱 진입 시 1회 (클라이언트에서)
wq.init("pk_XXXX", { apiUrl: "https://wq.honenuki.com" });
// 원하는 순간에
wq.trigger("export_completed");
React 훅을 쓰면 초기화까지 한 번에:
import { useEffect } from "react";
import { useWebQuestion } from "@webquestion/sdk/react";
function App() {
const wq = useWebQuestion("pk_XXXX", { apiUrl: "https://wq.honenuki.com" });
useEffect(() => {
if (exportDone) wq.trigger("export_completed");
}, [exportDone]);
}
4. 트리거 옵션
// 특정 요소 옆에 띄우기
wq.trigger("export_completed", { anchor: buttonElement });
// 좌표 지정
wq.trigger("export_completed", { anchor: { x: 300, y: 200 } });
// 응답에 커스텀 데이터 첨부 (대시보드에서 함께 확인 가능)
wq.trigger("export_completed", { context: { plan: "free", durationSec: 31 } });
// 노출 빈도 제한 무시 (개발/테스트용)
wq.trigger("export_completed", { force: true });
// 이벤트 매핑 없이 서베이를 직접 띄우기
wq.show("sv_XXXX");
trigger()는 팝업이 실제로 노출됐으면 true를 반환하는 Promise입니다. 실패해도 앱에 영향을 주지 않으므로 try/catch가 필요 없고, SSR 환경에서는 자동으로 아무 일도 하지 않습니다.
5. 노출 빈도
| 설정 | 동작 |
|---|---|
| 사용자당 1회 | 응답한 사용자에게는 다시 뜨지 않음 (기본값). 닫기(×)만 한 경우 같은 세션에서는 다시 뜨지 않고, 다음 세션에 다시 물어봅니다 |
| 세션당 1회 | 브라우저 탭 세션마다 노출 1회 |
| N일마다 1회 | 마지막 노출 후 N일이 지나면 다시 노출 |
| 매번 | trigger가 호출될 때마다 노출 |
노출과 응답은 따로 집계됩니다 — 대시보드 응답 탭에서 응답률(응답/노출)을 확인할 수 있습니다.
6. 다국어
대시보드에서 다국어 옵션을 켜고 영어·中文·日本語·Español 번역을 추가하세요 (직접 입력 또는 🌐 자동 번역). SDK는 사용자의 브라우저 언어를 자동 감지해 해당 번역으로 팝업을 보여주고, 번역이 없으면 기본 언어로 표시합니다. 응답 집계는 언어와 무관하게 같은 옵션으로 합산됩니다.
언어를 직접 지정하려면:
<!-- 스크립트 태그 -->
<script src="https://wq.honenuki.com/wq.js" data-key="pk_XXXX" data-lang="en"></script>
// npm SDK
wq.init("pk_XXXX", { apiUrl: "https://wq.honenuki.com", language: "en" });
7. 팁 — 언제 물어볼까
- 행동 직후가 최고의 타이밍입니다: 내보내기 완료, 첫 기능 사용, 결제 이탈 복귀 직후.
- 이벤트 이름은
영문/숫자/_-.:로, 행동을 그대로 적으세요:export_completed,checkout_abandoned,third_session. - 질문은 하나만. 더 묻고 싶다면 서베이를 나눠 다른 순간에 붙이세요.