SAZU 위젯 문서

설치부터 과금까지, 이 한 페이지로 끝

사람도, AI 코딩 도구도 이 문서만 읽으면 위젯을 설치하고 운영할 수 있도록 핵심만 정리했습니다.

1. 위젯이란 · 동작 구조

SAZU 위젯은 스크립트 한 줄로 내 웹사이트에 설치하는 사주 운세 도구입니다. 방문자가 위젯에 생년월일시·성별·출생도시를 입력하고 버튼을 누르면, 그 순간에만 SAZU 서버가 사주를 계산해 풀이를 표시합니다. 페이지를 열거나 새로고침하는 것만으로는 어떤 호출도 일어나지 않습니다.

구조 — 설치 스크립트(embed.js)가 페이지에 iframe 을 삽입하고, iframe 이 SAZU 서버와 통신합니다. 운영자 사이트의 코드·데이터에는 접근하지 않습니다.
도메인 잠금 — 위젯은 대시보드(https://www.sazu.app/widget/dashboard/keys)에 등록된 도메인에서만 동작합니다. 연동 키가 HTML 에 노출돼도 다른 사이트에서 쓸 수 없습니다.
높이 자동 동기화 — 위젯이 콘텐츠에 맞춰 스스로 높이를 조절합니다. 컨테이너에 고정 높이 CSS 를 주지 마세요.

2. 설치

규칙은 세 가지입니다.

위젯을 표시할 자리에 <div id="sazu-widget"></div> 컨테이너를 둔다.
설치 스크립트는 </body> 바로 앞에 둔다(사이트 리소스와 로딩 경쟁 방지). 컨테이너가 있으면 스크립트 위치와 무관하게 컨테이너 자리에 렌더된다.
컨테이너에 고정 높이를 주지 않는다 — 높이는 위젯이 자동으로 맞춘다.

<!DOCTYPE html>
<html>
<body>
  <!-- ① 위젯이 표시될 자리 — 높이는 위젯이 자동으로 맞춥니다 -->
  <div id="sazu-widget"></div>

  <!-- ② 설치 스크립트 — </body> 바로 앞이 최적 위치 -->
  <script src="https://www.sazu.app/embed.js" data-key="wgt_YOUR_KEY" async></script>
</body>
</html>

컨테이너 없이 스크립트만 넣으면 스크립트 태그 자리에 위젯이 표시됩니다(간이 방식). 워드프레스는 ‘사용자 정의 HTML’ 블록에 붙여넣으면 됩니다.

3. 속성 레퍼런스

속성	필수	기본값	설명
data-key	필수	—	연동 키(공개 식별자). 대시보드 → 연동 키에서 발급. 노출돼도 안전.
data-service	선택	today	운세 종류 코드. 코드 목록은 아래 표 참고. 별칭: multi-love → love.
data-theme	선택	dark	dark \| light \| auto. auto 는 설치된 사이트의 배색을 자동 감지.
data-accent	선택	#fbbf24	강조색 hex(#RGB/#RRGGBB). 버튼·헤드라인에 적용. 기본은 골드.
data-text-color	선택	테마 기본색	본문 글자색 hex. 미지정 시 다크 #f4f4f5 / 라이트 #18181b.
data-button-text-color	선택	#18181b	버튼 글자색 hex(강조색 배경 위). 기본은 다크 톤.
data-token	선택	없음	유료 페이백 보호용 서명 토큰. 보호를 켠 키에서만 필요.
data-target	선택	#sazu-widget	위젯을 넣을 요소의 CSS 선택자. 대상이 없으면 스크립트 자리에 렌더.
data-height	선택	560	위젯 로드 전 초기 높이(px, 최소 320). 로드 후엔 자동 동기화되므로 보통 불필요.

4. 운세 서비스 코드

data-service 에 넣는 코드입니다. 서비스에 따라 방문자 입력 폼이 자동으로 달라집니다 — 모든 폼은 생년월일 8자리·성별·양력/음력·시간(직접 입력 또는 12지 시간)·출생도시를 받습니다.

코드	서비스	차감 크레딧
today	오늘의 운세	1
monthly	월간 운세	2
consult	고민 맞춤분석	2
yearly	연간 운세	3
compatibility	관계운 (궁합)	3
love	연애 운 (다중궁합)	3
decade	대운 (10년)	3
life	인생흐름 (총운)	3

5. 크레딧 · 무료와 유료

무료 플랜 = 연동 테스트 — 모든 운세가 방문자 입력과 무관한 고정 예시(SAMPLE 배지)로 표시됩니다. 정식 구독 전 설치·디자인 구현을 위한 개발 용도입니다.
구독 중 = 라이브 — 방문자 각자의 사주로 계산한 실제 풀이가 나가고, 호출당 서비스에 상응하는 크레딧이 차감됩니다.
플랜 크레딧 · 충전 크레딧 — 구독으로 매월 지급되는 플랜 크레딧은 갱신 시 리셋되어 미사용분이 소멸합니다. 따로 충전한 크레딧은 유효기간 없이 이월되며, 차감은 먼저 소멸하는 크레딧부터 이루어져 충전분이 마지막까지 남습니다. 크레딧은 유료플랜 가입시에만 사용 가능합니다.
크레딧 소진 시 — 방문자에게 오류 대신 예시 결과가 표시되고, 충전하면 즉시 복구됩니다.

권장 — 테스트는 무료 키, 라이브는 유료 키로 분리하세요

키는 최대 5개까지 발급할 수 있고 구독은 키 단위로 붙습니다. 개발·테스트 단계에서는 무료 키로 설치와 디자인을 확인하고(고정 예시라 크레딧 소모 없음), 실서비스에는 구독한 유료 키를 <script> 내의 data-key 값에 사용하세요. 이렇게 분리하면 테스트 호출이 라이브 크레딧을 소모하지 않고, 테스트 도메인(localhost 등)과 라이브 도메인도 키별로 따로 관리할 수 있습니다.

6. 유료 페이백 보호 (선택)

방문자에게 직접 요금을 받는 운영자를 위한 기능입니다. 켜면 운영자 서버가 결제 완료 후 발급한 서명 토큰(data-token)이 있는 요청만 실제 풀이를 받습니다 — 설치 코드를 복사한 무단 호출과 크레딧 소진을 차단합니다.

대시보드 → 연동 키에서 보호를 켜고 서명 시크릿(wsk_...)을 발급받아 서버 환경변수(SAZU_WIDGET_SECRET)에 보관합니다. 시크릿은 서버 밖으로 내보내지 마세요.
결제 완료 시점에 아래 산식으로 토큰을 만들어 위젯 스크립트의 data-token 에 넣습니다.

// 결제 완료 후 — 운영자 서버 (Node 예시. 다른 언어는 HMAC-SHA256 hex 동일 산식)
import crypto from 'crypto'
const secret = process.env.SAZU_WIDGET_SECRET // 대시보드에서 발급한 wsk_...
const message = Buffer
  .from(JSON.stringify({ exp: Math.floor(Date.now()/1000) + 300 })) // 유효 300초
  .toString('base64url')
const sig = crypto.createHmac('sha256', secret).update(message).digest('hex')
const token = message + '.' + sig
// 위젯 스크립트에 주입:
// <script src="https://www.sazu.app/embed.js" data-key="wgt_..." data-token={token} async></script>

7. 문제 해결

증상	원인 · 해결
위젯 자리에 "허용되지 않은 도메인" 오류	설치한 사이트 주소가 허용 도메인에 없음 — 대시보드 → 연동 키에서 사이트 origin(예: https://mysite.com)을 등록.
위젯이 아예 표시되지 않음	data-key 누락/오타, 또는 컨테이너·스크립트가 모두 없는 경우. 브라우저 콘솔의 [SAZU embed] 경고를 확인.
결과에 SAMPLE 배지가 표시됨	무료 플랜(연동 테스트)이거나, 유료 페이백 보호가 켜진 키에 유효한 data-token 이 없는 경우, 또는 크레딧 소진.
위젯 아래 콘텐츠가 가려짐	컨테이너에 고정 높이 CSS 를 준 경우 — 제거하면 위젯이 내용에 맞춰 높이를 자동 조절.
결과 화면이 좁게 나옴	풀이 화면에서 위젯은 최대 800px 까지 자동 확장되지만 설치된 컨테이너 폭을 넘지 못합니다 — 위젯 자리를 800px 이상 확보하면 표·긴 문단이 넓게 표시됩니다.
분당 호출 한도 초과(429)	오늘의 운세는 분당 20회 한도. 잠시 후 재시도.

해결되지 않으면 대시보드의 연동 키·크레딧 상태를 먼저 확인하세요. 문의: contact@sazu.app