문제 해결

PrivateStater 사용 시 자주 발생하는 문제와 해결 방법입니다.

공통 문제

스크립트가 로드되지 않아요

증상: 콘솔에 [PrivateStater Getter] Missing prstSite config 에러

원인: PrivateStaterConfig가 스크립트보다 먼저 정의되지 않음

해결:

<!-- 반드시 이 순서로 -->
<script>
  window.PrivateStaterConfig = { prstSite: "YOUR_SITE_ID" };
</script>
<script src="https://privatestater.com/privatestater.js"></script>

host_mismatch 에러

증상: 콘솔에 host_mismatch 에러

원인: 요청 Origin이 대시보드에 등록된 Host와 불일치

해결:

대시보드에서 웹사이트의 Host 값 확인
실제 접속 도메인과 일치하는지 확인
서브도메인 포함 여부 확인 (예: www.example.com vs example.com)

localhost에서 작동하지 않아요

원인: 기본적으로 localhost 접근이 차단됨

해결:

대시보드 > 웹사이트 > [기능] > 설정
로컬호스트 허용 옵션 활성화

참고: 각 기능(캡차, 피드백)별로 별도로 설정해야 합니다.

광고 차단기에 의해 차단돼요

증상: 스크립트 로드 실패 또는 API 요청 차단

원인: 일부 광고 차단기가 analytics 관련 스크립트를 차단

해결:

사용자에게 privatestater.com 차단 해제 안내
또는 해당 필터 관리자에게 차단 해제 요청

분석 문제

방문자 통계가 표시되지 않아요

확인 사항:

스크립트 설치 확인

console.log(window.PrivateStater); // 객체가 출력되어야 함

websiteId 확인
- 대시보드에서 생성한 ID와 일치하는지 확인
네트워크 요청 확인
- 브라우저 개발자 도구 > Network 탭
- /api/analytics/collect/visit 요청이 있는지 확인
- 응답이 204인지 확인
대기 시간
- 통계는 약 1분 내에 반영됩니다

중복 방문자가 집계돼요

원인 아님: 정상 동작입니다.

설명: PrivateStater는 시간별로 중복을 제거합니다. 같은 방문자가 다른 시간대에 방문하면 별도로 집계됩니다.

예시:

오전 10시 방문 → 1회 집계
오전 10시 30분 재방문 → 중복 제거 (같은 시간대)
오전 11시 재방문 → 1회 추가 집계 (다른 시간대)

클릭 추적이 안 돼요

확인 사항:

함수 호출 확인

window.PrivateStater.statsClick("button_id");

buttonId 형식 확인
- 영문, 숫자, 하이픈, 언더스코어만 사용
- 공백 불가

캡차 문제

캡차 위젯이 표시되지 않아요

확인 사항:

활성화 확인
- 대시보드 > 캡차 > 설정 > 활성화 여부
data-captcha 속성 확인
```
<div data-captcha="prst"></div>
```
콘솔 에러 확인
- captcha_not_enabled: 캡차가 활성화되지 않음
- website_not_found: 잘못된 websiteId

퍼즐 검증이 실패해요

원인:

퍼즐 조각 위치가 정확하지 않음 (허용 오차: ±8px)
세션 만료 (5분)

해결: 퍼즐 조각을 정확한 위치에 맞추세요.

PoW가 너무 오래 걸려요

원인: PoW 난이도가 높게 설정됨

해결:

대시보드 > 캡차 > 설정
PoW 난이도를 low로 변경

난이도별 예상 시간:

low: ~1초
medium: ~2초
high: ~3초

토큰 검증이 실패해요

확인 사항:

토큰 만료 확인
- 토큰은 5분 후 만료됩니다
중복 사용 확인
- 토큰은 1회만 사용 가능합니다
- 이미 검증한 토큰은 재사용 불가
websiteId 일치 확인
- 클라이언트와 서버에서 같은 websiteId 사용

API 요청 형식 확인

{
    "websiteId": "my-site",
    "verifyToken": "session-id:signature"
}

honeypot_triggered 에러

원인: 허니팟 필드가 채워짐 (봇으로 감지됨)

확인 사항:

자동 폼 채우기 도구 비활성화
브라우저 확장 프로그램 확인

피드백 문제

피드백 버튼이 표시되지 않아요

확인 사항:

활성화 확인
- 대시보드 > 피드백 > 설정 > 활성화 여부
z-index 충돌
- 다른 요소가 버튼을 가리고 있을 수 있음
- 피드백 버튼 z-index: 999998

스크린샷 첨부가 안 돼요

원인:

이미지 크기가 1MB 초과
일부 요소가 캡처되지 않음 (CORS 이미지 등)

해결:

스크린샷은 html2canvas 라이브러리로 캡처됨
외부 이미지는 CORS 제한으로 캡처 불가

피드백이 제출되지 않아요

확인 사항:

필수 데이터 확인
- 평점, 텍스트, 스크린샷 중 하나 이상 필요
Rate Limit 확인
- 1분에 10회 제한
네트워크 요청 확인
- /api/feedback/submit 응답 확인

에러 코드 레퍼런스

에러 코드	원인	해결 방법
`missing_required_fields`	필수 필드 누락	요청 body 확인
`invalid_website_id`	잘못된 websiteId 형식	ID 형식 확인 (영문소문자, 숫자, 하이픈)
`website_not_found`	존재하지 않는 웹사이트	대시보드에서 웹사이트 생성 확인
`host_mismatch`	Origin과 Host 불일치	도메인 등록 확인
`captcha_not_enabled`	캡차 비활성화	대시보드에서 활성화
`feedback_not_enabled`	피드백 비활성화	대시보드에서 활성화
`token_invalid_or_expired`	토큰 만료/사용됨	새 캡차 시작
`token_expired`	세션 만료 (5분)	새 캡차 시작
`puzzle_mismatch`	퍼즐 위치 오류	정확한 위치에 맞추기
`pow_invalid`	PoW 해시 오류	새 캡차 시작
`honeypot_triggered`	봇 감지	자동 폼 채우기 비활성화
`empty_feedback`	빈 피드백	내용 입력 필요
`rate_limit_*`	요청 한도 초과	잠시 후 재시도

추가 지원

위 방법으로 해결되지 않는 문제가 있다면:

이메일: hello@privatestater.com
필요하다면 문제 설명, 에러 메시지, 브라우저 콘솔 로그를 함께 보내주세요