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

위젯으로 운세를 붙이는 전체 그림입니다. 여섯 조각이 어떤 순서로 이어지고 그중 무엇을 SAZU 가 맡는지를 먼저 보시면 아래 설치 방법이 쉬워집니다.

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

• 구조 — 설치 스크립트(embed.js)가 페이지에 iframe 을 삽입하고, iframe 이 SAZU 서버와 통신합니다. 운영자 사이트의 코드·데이터에는 접근하지 않습니다.
• 도메인 잠금 — 위젯은 내 프로필 → 연동 키에 등록된 도메인에서만 동작합니다. 연동 키가 HTML 에 노출돼도 다른 사이트에서 쓸 수 없습니다.
• 높이 자동 동기화 — 위젯이 콘텐츠에 맞춰 스스로 높이를 조절합니다. 컨테이너에 고정 높이 CSS 를 주지 마세요.
• 운세별 프롬프트 지정 — 내 프로필 → 프롬프트 만들기에서 운세 상품마다 풀이 방식을 지정할 수 있습니다. 자동 검토를 통과해 승인된 프롬프트만 저장되고, 방문자가 그 운세를 호출할 때부터 SAZU 기본 풀이의 정확성 규칙 뒤에 덧붙어 적용됩니다. 지정하지 않은 운세는 기본 풀이 그대로이고, 오늘의 운세는 풀이 방식이 달라 지정 대상이 아닙니다.

규칙은 세 가지입니다.

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

<!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’ 블록에 붙여넣으면 됩니다.

• 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-field-*

  필수

  선택

  기본값

  true

  설명

  방문자 입력 항목을 켜고 끈다. 끌 수 있는 항목은 아래 「입력 폼 커스터마이즈」 참고.

• data-default-birth-city

  필수

  선택

  기본값

  서울

  설명

  출생도시를 감췄을 때 쓸 도시명(표시 중이면 초기값).

• data-option-*

  필수

  선택

  기본값

  서비스 기본값

  설명

  서비스별 추가 선택의 고정값. 선택지를 감췄을 때 무엇으로 계산할지 정한다.

• data-target

  필수

  선택

  기본값

  #sazu-widget

  설명

  위젯을 넣을 요소의 CSS 선택자. 대상이 없으면 스크립트 자리에 렌더.

• data-height

  필수

  선택

  기본값

  560

  설명

  위젯 로드 전 초기 높이(px, 최소 320). 로드 후엔 자동 동기화되므로 보통 불필요.

방문자에게 물어볼 항목을 줄일 수 있습니다. 감추려는 항목의 속성을 "false" 로 두면 됩니다 — 지정하지 않은 항목은 그대로 표시됩니다.

<!-- 필수 3개(생년월일·성별·양력/음력)만 받고 나머지 입력란은 감춘다 -->
<script
  src="https://www.sazu.app/embed.js"
  data-key="wgt_YOUR_KEY"
  data-field-birth-time="false"
  data-field-birth-city="false"
  async></script>

• data-field-birth-time

  입력 항목

  태어난 시간 (직접 입력 · 12지 시간)

  false 로 감췄을 때 쓰이는 값

  시간 모름 — 시주 없이 계산

• data-field-birth-city

  입력 항목

  출생도시

  false 로 감췄을 때 쓰이는 값

  data-default-birth-city 값 (기본 서울)

• data-field-options

  입력 항목

  서비스별 추가 선택 (대상 월·연도·대운 구간·고민 분야·관계 유형·추가 상황)

  false 로 감췄을 때 쓰이는 값

  data-option-* 로 지정한 값 (미지정 시 이번 달 · 올해 · 첫 항목)

• data-field-partner-details

  입력 항목

  상대 추가 입력 (별명·관계 상태·현재 상황)

  false 로 감췄을 때 쓰이는 값

  미입력

감춘 선택지의 값 정하기

data-field-options 로 선택지를 감추면 방문자가 고를 수 없으므로, 무엇으로 계산할지는 설치하시는 분이 정합니다. 아래 속성으로 지정하지 않으면 서비스 기본값(이번 달 · 올해 · 이번 대운 · 그 밖은 첫 항목)이 쓰입니다. 선택지를 감추지 않았다면 같은 값이 초기 선택으로 들어갑니다.

<!-- 연간 운세 — 선택지를 감추고 '항상 내년'으로 고정한다 -->
<script
  src="https://www.sazu.app/embed.js"
  data-key="wgt_YOUR_KEY"
  data-service="yearly"
  data-field-options="false"
  data-option-target-year="next"
  async></script>

• data-option-target-month

  허용 값

  previous | current | next | YYYY-MM (예: 2026-09)

• data-option-target-year

  허용 값

  current | next | YYYY (예: 2027)

• data-option-decade-selection

  허용 값

  previous | current | next

• data-option-category

  허용 값

  고민 분야 이름 (고민 맞춤분석의 선택지와 같은 문자열)

• data-option-relation-type

  허용 값

  관계 유형 (궁합의 선택지와 같은 문자열)

• data-option-user-context

  허용 값

  자유 문장 (최대 500자)

• 월·연은 리터럴(2026-09)보다 상대 토큰(current · next)을 권합니다 — 리터럴은 시간이 지나면 과거를 가리켜, 설치해 둔 위젯이 조용히 지난 달 운세를 뽑게 됩니다.
• 서비스가 쓰지 않는 속성은 무시됩니다(예: 오늘의 운세에 data-option-target-year). 허용 값이 아닌 값도 무시되고, 브라우저 콘솔에 [SAZU widget] 경고와 사유가 표시됩니다.
• data-option-user-context 는 위젯 주소에 실려 서버 접근 기록에 남습니다. 사이트가 고정으로 넣는 문장에만 쓰시고, 방문자의 개인정보는 담지 마세요.

감출 수 없는 필수 입력

아래 항목은 사주 계산의 입력 그 자체라 감출 수 없습니다. 폼에서 지우고 고정값을 쓰면 결과가 조용히 틀어지기 때문입니다 — 방문자는 그것이 자기 사주가 아니라는 사실을 알 방법이 없습니다.

• 생년월일

  감출 수 없는 이유

  사주 원국이 서지 않는다 — 위젯이 계산할 대상 자체가 사라진다.

• 성별

  감출 수 없는 이유

  대운의 순행·역행을 가른다. 고정하면 방문자 절반의 대운이 통째로 어긋난다.

• 양력/음력

  감출 수 없는 이유

  같은 날짜라도 음력이면 다른 사주가 된다. 고정하면 원국부터 틀린다.

• 고민 내용 (고민 맞춤분석)

  감출 수 없는 이유

  그 서비스의 유일한 질문이라 지우면 빈 폼이 된다.

이 항목들에 data-field-* 를 붙이면 무시되고, 브라우저 콘솔에 [SAZU embed] 경고와 사유가 표시됩니다.

data-service 에 넣는 코드입니다. 서비스에 따라 방문자 입력 폼이 자동으로 달라집니다 — 기본은 생년월일 8자리·성별·양력/음력·시간(직접 입력 또는 12지 시간)·출생도시이며, 항목을 줄이려면 위 입력 폼 커스터마이즈를 참고하세요.

• today

  서비스

  오늘의 운세

  차감 크레딧

  1

• monthly

  서비스

  월간 운세

  차감 크레딧

  2

• consult

  서비스

  고민 맞춤분석

  차감 크레딧

  2

• yearly

  서비스

  연간 운세

  차감 크레딧

  3

• compatibility

  서비스

  관계운 (궁합)

  차감 크레딧

  3

• love

  서비스

  연애 운 (다중궁합)

  차감 크레딧

  3

• decade

  서비스

  대운 (10년)

  차감 크레딧

  3

• life

  서비스

  인생흐름 (총운)

  차감 크레딧

  3

• food

  서비스

  명리 식단

  차감 크레딧

  2

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

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

1. 내 프로필 → 연동 키에서 보호를 켜고 서명 시크릿(wsk_...)을 발급받아 서버 환경변수(SAZU_WIDGET_SECRET)에 보관합니다. 시크릿은 서버 밖으로 내보내지 마세요.
2. 결제 완료 시점에 아래 산식으로 토큰을 만들어 위젯 스크립트의 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>

• 위젯 자리에 "허용되지 않은 도메인" 오류

  원인 · 해결

  설치한 사이트 주소가 허용 도메인에 없음 — 내 프로필 → 연동 키에서 사이트 origin(예: https://mysite.com)을 등록.

• 위젯 자리가 비어 있고 콘솔에 Content Security Policy 오류

  원인 · 해결

  사이트의 CSP 가 위젯을 막고 있습니다. script-src 와 frame-src 에 https://www.sazu.app 을 추가해 주세요.

• 위젯이 아예 표시되지 않음

  원인 · 해결

  data-key 누락/오타, 또는 컨테이너·스크립트가 모두 없는 경우. 브라우저 콘솔의 [SAZU embed] 경고를 확인.

• 결과에 SAMPLE 배지가 표시됨

  원인 · 해결

  무료 플랜(연동 테스트)이거나, 유료 페이백 보호가 켜진 키에 유효한 data-token 이 없는 경우, 또는 크레딧 소진.

• 위젯 아래 콘텐츠가 가려짐

  원인 · 해결

  컨테이너에 고정 높이 CSS 를 준 경우 — 제거하면 위젯이 내용에 맞춰 높이를 자동 조절.

• 결과 화면이 좁게 나옴

  원인 · 해결

  풀이 화면에서 위젯은 최대 800px 까지 자동 확장되지만 설치된 컨테이너 폭을 넘지 못합니다 — 위젯 자리를 800px 이상 확보하면 표·긴 문단이 넓게 표시됩니다.

• 분당 호출 한도 초과(429)

  원인 · 해결

  키 하나당 모든 운세 합산 분당 20회 한도. 잠시 후 재시도.

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