Studio Hirameki · Integration Guide Rev. 2026.04

Hirameki Lucid
— 통합 가이드.

물리 법칙 기반 매크로 탐지 SaaS. 스크립트 한 줄, 함수 한 번으로 결제 플로우를 보호합니다.

ProductHirameki Lucid
AudienceIntegrating Engineers
Issued2026 · Studio Hirameki
Contents
  1. 01가장 빠른 통합
  2. 08Timeout & Fallback
  3. 02필수 통합 코드
  4. 09SPA 통합
  5. 03서버사이드 검증
  6. 10iframe · 새 창
  7. 03a백엔드 샘플 (10언어)
  8. 11모바일 WebView
  9. 04MACRO 처리 패턴
  10. 12비동기 로드
  11. 04averify 호출 시점 선택
  12. 13개발자 도구
  13. 05전송 데이터
  14. 14Best Practices
  15. 06API 엔드포인트
  16. 15Limitation of Liability
  17. 07CSP 설정
  18. 16Support
01

가장 빠른 통합

Copy · Paste

데모 사이트의 코드를 그대로 복사해서 쓰시면 됩니다.

Demo https://luciddemo.hrmk.studio/

real1.html ~ real4.html + lucid-sdk.js 가 그대로 동작하는 통합 예시입니다. 필요한 부분만 복사해서 귀사 결제 플로우에 붙이세요.

Session —
Points 0
02

필수 통합 코드

Required template

모든 페이지 <head> 에 SDK를 로드합니다. 발급받은 data-site-key 필수.

HTML<script src="https://lucid.hrmk.studio/sdk.js" data-site-key="pk_live_xxx"></script>

결제·주요 행동의 클릭 핸들러는 아래 템플릿을 그대로 사용해 주십시오. isTrusted 가드 · payInFlight 중복 차단 · token 백엔드 전달 · clearSession() — 모두 필수입니다.

JS · REQUIREDlet payInFlight = false; // 중복 클릭 차단 document.getElementById('pay').onclick = async (e) => { if (!e.isTrusted) return; // 사람 클릭만 통과 if (payInFlight) return; payInFlight = true; try { const { verdict, token } = await Lucid.verify(); if (verdict === 'MACRO') return; await fetch('/api/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ lucid_token: token }), }); Lucid.clearSession(); } finally { /* 재시도 허용 시 payInFlight = false */ } };
Required

다음 네 가지는 누락 금지. 하나라도 빠지면 §15 책임 제한의 공식 미지원 통합으로 간주됩니다.

  • payInFlight 플래그 — 중복 클릭 차단
  • !e.isTrusted 조기 반환 — 합성 이벤트 차단
  • token 백엔드 전달 — 서버 재검증 가능
  • Lucid.clearSession() 호출 — 세션 재사용 방지
호출 시점

위 템플릿의 'pay' 는 예시입니다. Lucid.verify() 는 자원 점유가 발생하는 모든 버튼에 적용 가능합니다 — 좌석 선택 · 응모 제출 · 쿠폰 등록 등. 업종별 권장 시점은 §04a 참고.

Dwell Time

SDK 로드부터 Lucid.verify() 호출까지 10초 이상 권장 (최소 5초). 좌석 선택·폼 입력 등 자연스러운 상호작용으로 확보하세요. 너무 짧으면 표본 부족으로 판정 정확도 저하.

Checklist
  • SDK 로드 위치 — 모든 페이지 <head>. 결제 페이지만 로드하면 Dwell Time 부족.
  • verify 호출 시점 — 결제·예매·응모 버튼 클릭 핸들러 내부. 페이지 진입 시점 X.
  • token 전달 — 귀사 백엔드로 반드시. 클라 verdict 만으로 결제 진행 금지.
  • clearSession() — 결제 완료·취소 후 호출. 세션 재사용 방지.
03

서버사이드 검증

Required · Backend

클라이언트 판정 결과는 참고용입니다. 귀사 백엔드가 /siteverify 로 토큰을 재검증해야만 신뢰 가능한 판정이 됩니다.

검증 플로우는 언어·프레임워크와 무관하게 동일합니다:

  1. 클라이언트가 Lucid.verify() 로 받은 token 을 /api/checkout 바디에 포함해 귀사 백엔드로 전송.
  2. 백엔드는 X-Lucid-Secret 헤더와 함께 https://lucid.hrmk.studio/siteverify 로 POST.
  3. 응답의 valid === true 이고 verdict === "HUMAN" 일 때만 결제 진행. 그 외에는 403.
Warning

이 검증 없이 /api/checkout 을 진행하면 클라이언트 조작(Lucid.verify 오버라이드, fetch 가로채기, 임의 토큰 주입 등)으로 우회 가능합니다. 서버사이드 검증이 누락된 통합은 §15 책임 제한 조항의 공식 미지원 통합 방식에 해당합니다.

Token

HMAC-SHA256 서명 · TTL 2분 · 1회 소비. 동일 토큰을 두 번 /siteverify 에 제출하면 두 번째는 valid: false 로 거절됩니다. 재시도 플로우가 필요한 경우 클라이언트에서 Lucid.verify() 를 다시 호출하여 새 토큰을 발급받으십시오.

PG 플로우 타이밍

/siteverify 는 PG 결제창 오픈 이전 에 1회 호출하고, PG 콜백 복귀 시점에는 재호출하지 않습니다. 토큰 TTL(2분) 이 PG 결제 소요 시간과 겹치지 않도록 주의.

  1. 사용자가 결제하기 클릭
  2. 프론트: Lucid.verify() → 토큰 발급
  3. 백엔드: /siteverify 호출 → HUMAN 확인
  4. HUMAN 확정 시 PG 결제창 오픈
  5. 사용자 PG 결제 완료
  6. 백엔드: PG 서명 검증 (siteverify 재호출 X)
  7. 주문 확정
Samples

다음 페이지부터 TypeScript · Java · Python(FastAPI/Django) · Kotlin · Go · PHP · Rust · Ruby · C# 샘플을 제공합니다. 모두 동일한 로직(토큰 전달 → siteverify → HUMAN 확인 → 결제)이므로 귀사 스택에 맞춰 한 개만 사용하십시오.

03a

백엔드 샘플

10 languages

언어를 선택하면 해당 샘플만 표시됩니다. PDF 인쇄 시 전체 표시.

— TypeScript · Node.js / Express

TSapp.post('/api/checkout', async (req, res) => { const r = await fetch('https://lucid.hrmk.studio/siteverify', { method: 'POST', headers: { 'X-Lucid-Secret': process.env.LUCID_SECRET!, 'Content-Type': 'application/json', }, body: JSON.stringify({ token: req.body.lucid_token }), }); const { valid, verdict } = await r.json(); if (!valid || verdict !== 'HUMAN') return res.status(403).end(); // 정상 결제 로직 res.json({ ok: true }); });

— Java · Spring Boot

JAVA@PostMapping("/api/checkout") public ResponseEntity<?> checkout(@RequestBody CheckoutReq req) { var headers = new HttpHeaders(); headers.set("X-Lucid-Secret", System.getenv("LUCID_SECRET")); headers.setContentType(MediaType.APPLICATION_JSON); var body = Map.of("token", req.getLucidToken()); var resp = new RestTemplate().postForObject( "https://lucid.hrmk.studio/siteverify", new HttpEntity<>(body, headers), SiteverifyResp.class ); if (resp == null || !resp.isValid() || !"HUMAN".equals(resp.getVerdict())) { return ResponseEntity.status(403).build(); } // 정상 결제 로직 return ResponseEntity.ok().build(); }

— Python · FastAPI

PYimport os, httpx from fastapi import FastAPI, HTTPException @app.post("/api/checkout") async def checkout(req: CheckoutReq): async with httpx.AsyncClient() as client: r = await client.post( "https://lucid.hrmk.studio/siteverify", headers={"X-Lucid-Secret": os.environ["LUCID_SECRET"]}, json={"token": req.lucid_token}, ) data = r.json() if not data.get("valid") or data.get("verdict") != "HUMAN": raise HTTPException(status_code=403) # 정상 결제 로직 return {"ok": True}

— Python · Django

PYimport os, json, requests from django.http import JsonResponse, HttpResponse from django.views.decorators.csrf import csrf_exempt @csrf_exempt def checkout(request): token = json.loads(request.body)["lucid_token"] r = requests.post( "https://lucid.hrmk.studio/siteverify", headers={"X-Lucid-Secret": os.environ["LUCID_SECRET"]}, json={"token": token}, timeout=5, ) data = r.json() if not data.get("valid") or data.get("verdict") != "HUMAN": return HttpResponse(status=403) # 정상 결제 로직 return JsonResponse({"ok": True})

— Kotlin · Spring Boot

KT@PostMapping("/api/checkout") fun checkout(@RequestBody req: CheckoutReq): ResponseEntity<Any> { val headers = HttpHeaders().apply { set("X-Lucid-Secret", System.getenv("LUCID_SECRET")) contentType = MediaType.APPLICATION_JSON } val resp = RestTemplate().postForObject( "https://lucid.hrmk.studio/siteverify", HttpEntity(mapOf("token" to req.lucidToken), headers), SiteverifyResp::class.java ) if (resp?.valid != true || resp.verdict != "HUMAN") { return ResponseEntity.status(403).build() } // 정상 결제 로직 return ResponseEntity.ok().build() }

— Go

GOfunc checkoutHandler(w http.ResponseWriter, r *http.Request) { var req struct{ LucidToken string `json:"lucid_token"` } json.NewDecoder(r.Body).Decode(&req) payload, _ := json.Marshal(map[string]string{"token": req.LucidToken}) hr, _ := http.NewRequest("POST", "https://lucid.hrmk.studio/siteverify", bytes.NewReader(payload)) hr.Header.Set("X-Lucid-Secret", os.Getenv("LUCID_SECRET")) hr.Header.Set("Content-Type", "application/json") resp, err := http.DefaultClient.Do(hr) if err != nil { http.Error(w, "upstream", 502); return } defer resp.Body.Close() var result struct{ Valid bool `json:"valid"`; Verdict string `json:"verdict"` } json.NewDecoder(resp.Body).Decode(&result) if !result.Valid || result.Verdict != "HUMAN" { http.Error(w, "forbidden", 403); return } // 정상 결제 로직 json.NewEncoder(w).Encode(map[string]bool{"ok": true}) }

— PHP

PHP<?php $body = json_decode(file_get_contents('php://input'), true); $token = $body['lucid_token'] ?? ''; $ch = curl_init('https://lucid.hrmk.studio/siteverify'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['token' => $token]), CURLOPT_HTTPHEADER => [ 'X-Lucid-Secret: ' . getenv('LUCID_SECRET'), 'Content-Type: application/json', ], CURLOPT_RETURNTRANSFER => true, ]); $resp = json_decode(curl_exec($ch), true); curl_close($ch); if (empty($resp['valid']) || ($resp['verdict'] ?? '') !== 'HUMAN') { http_response_code(403); exit; } // 정상 결제 로직 echo json_encode(['ok' => true]);

— Rust · axum + reqwest

RSasync fn checkout(Json(req): Json<CheckoutReq>) -> impl IntoResponse { let secret = std::env::var("LUCID_SECRET").unwrap(); let client = reqwest::Client::new(); let resp: SiteverifyResp = client .post("https://lucid.hrmk.studio/siteverify") .header("X-Lucid-Secret", secret) .json(&serde_json::json!({ "token": req.lucid_token })) .send().await.unwrap() .json().await.unwrap(); if !resp.valid || resp.verdict != "HUMAN" { return StatusCode::FORBIDDEN.into_response(); } // 정상 결제 로직 (StatusCode::OK, Json(serde_json::json!({ "ok": true }))).into_response() }

— Ruby · Rails

RBclass CheckoutController < ApplicationController skip_before_action :verify_authenticity_token def create uri = URI('https://lucid.hrmk.studio/siteverify') req = Net::HTTP::Post.new(uri, { 'X-Lucid-Secret' => ENV['LUCID_SECRET'], 'Content-Type' => 'application/json', }) req.body = { token: params[:lucid_token] }.to_json resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) } data = JSON.parse(resp.body) return head 403 unless data['valid'] && data['verdict'] == 'HUMAN' # 정상 결제 로직 render json: { ok: true } end end

— C# · ASP.NET Core

C#[ApiController, Route("api/[controller]")] public class CheckoutController : ControllerBase { private static readonly HttpClient http = new(); [HttpPost] public async Task<IActionResult> Create([FromBody] CheckoutReq req) { var payload = JsonContent.Create(new { token = req.LucidToken }); var httpReq = new HttpRequestMessage(HttpMethod.Post, "https://lucid.hrmk.studio/siteverify") { Content = payload }; httpReq.Headers.Add("X-Lucid-Secret", Environment.GetEnvironmentVariable("LUCID_SECRET")); var resp = await http.SendAsync(httpReq); var result = await resp.Content.ReadFromJsonAsync<SiteverifyResp>(); if (result is null || !result.Valid || result.Verdict != "HUMAN") return StatusCode(403); // 정상 결제 로직 return Ok(new { ok = true }); } }
04

MACRO 처리 패턴

A · B · C

판정이 MACRO 인 경우, 고객사가 자유롭게 차단 방식을 선택할 수 있습니다.

A즉시 차단

JSif (verdict === 'MACRO') { alert('비정상 접근'); return; }

B추가 인증

JSif (verdict === 'MACRO') { showSmsVerification(); return; }

C조용한 차단 권장 — 핑거프린팅 방지

JSif (verdict === 'MACRO') { await fakeLoadingDelay(); showFakeSuccess(); // 봇에게는 성공처럼 보이게 notifyAdmin(session); // 관리자 큐에 적재 return; }
Why C

C 패턴이 봇 운영자가 차단을 인지 못 하게 만들어 우회 시도를 억제합니다. 티켓팅의 경우 "좌석이 방금 매진되었습니다" · "매진된 좌석입니다" 로 연출하면 봇은 정상 판정으로 오인하고 다른 좌석 시도 → 시간 낭비 → 자동화 경제성 붕괴.

04a

verify 호출 시점 선택

Integration Point

Lucid.verify() 는 자원 점유·커밋이 발생하는 순간에 호출합니다. 업종에 따라 최적 시점이 다릅니다.

업종권장 호출 시점차단 효과
티켓팅 · 예매 좌석 선택 확정 인벤토리 점유 이전 차단
일반 커머스 결제하기 클릭 결제 진행 차단
한정 이벤트 · 응모 응모 제출 응모 등록 이전 차단
쿠폰 · 선착순 쿠폰 등록 버튼 쿠폰 지급 이전 차단
회원가입 제출 버튼 프로필 생성 이전 차단
가격 스크래핑 방어 상세 페이지 진입 데이터 노출 이전 차단
티켓팅 특화

티켓팅은 좌석 선택 시점이 최적입니다. 결제 단계에서 막으면 이미 좌석이 10분간 홀드되어 정상 유저에게 기회가 가지 않습니다. 좌석 선택 확정 버튼에 Lucid.verify() 를 적용하면 봇이 인벤토리 자체를 점유하지 못합니다.

다단계 검증

여러 단계에서 검증이 필요한 경우 각 버튼마다 Lucid.verify() 를 별도로 호출할 수 있습니다. 각 호출은 독립 토큰을 발급하므로 백엔드에서 각각 /siteverify 재검증. 예: 좌석 선택 (1차 검증) → 결제하기 (2차 검증).

Dwell Time 조심

호출 시점이 너무 이르면 궤적 표본이 부족하여 판정 정확도가 떨어집니다 (§02 Dwell Time 참고). 좌석 선택 시점 기준이면 공연 탐색·회차 선택 등 자연스러운 인터랙션으로 10초 이상 확보 가능.

05

전송 데이터

개인정보 감사용
서버로 보내는 것
  • 포인터 좌표 x, y (뷰포트 픽셀)
  • 타임스탬프 t (Unix epoch ms)
  • (터치 기기만) 접촉 반경 r, 압력 f
보내지 않는 것
  • 키보드 입력 내용
  • 폼 필드 값
  • URL · Referrer
  • 쿠키 · 로그인 세션
  • 디바이스 지문 · 브라우저 핑거프린팅
Session TTL

세션 ID는 SDK 로드 시 임의 생성 (32-hex), TTL 10분 후 서버에서 자동 삭제됩니다.

06

API 엔드포인트

4 endpoints

기본 URL: https://lucid.hrmk.studio

Endpoint호출용도
POST/initiate SDK 자동 세션 시작
POST/stack SDK 자동 이벤트 누적
POST/verify Lucid.verify() 클라 판정 + 토큰 발급
POST/siteverify 귀사 백엔드 서버 검증 (1회용)

Lucid.verify() 가 발급한 token(HMAC-SHA256, TTL 2분, 1회 소비)을 귀사 백엔드가 /siteverify로 재검증해야 신뢰 가능한 판정이 성립합니다.

/verify 응답:

JSON{ "verdict": "HUMAN", "token": "eyJ..." } { "verdict": "MACRO", "token": "eyJ..." }

/siteverify 응답:

JSON{ "valid": true, "verdict": "HUMAN" } { "valid": false, "reason": "invalid_secret" | "missing_token" | "invalid_or_expired" | "already_consumed" }
07

CSP 설정

Enterprise Security

엄격한 Content Security Policy 를 운영 중이라면 SDK 로드 · API 통신 도메인을 사전 허용해야 합니다.

귀사 웹 서버의 CSP 헤더에 다음을 추가:

HTTP · CSPContent-Security-Policy: script-src https://lucid.hrmk.studio; connect-src https://lucid.hrmk.studio;
Required

이 지시문 없이 엄격한 CSP 환경에서 SDK 를 로드하면 브라우저가 스크립트 자체를 차단합니다. 연동 전 귀사 보안팀과 사전 협의를 권장합니다. Nonce 기반 CSP 운영 중인 경우 별도 문의 주십시오.

Report-Only 모드로 먼저 테스트 권장:

HTTPContent-Security-Policy-Report-Only: script-src 'self' https://lucid.hrmk.studio; connect-src 'self' https://lucid.hrmk.studio; report-uri /csp-report;
08

Timeout & Fallback

Resilience

Lucid.verify() 는 네트워크·서버 오류 가능성을 고려해 기본 8초 타임아웃으로 동작합니다. 실패 시 정책은 고객사가 선택하세요.

타임아웃 커스터마이징:

JSconst result = await Lucid.verify({ timeout: 5000 }); // 5초

타임아웃 시 Error('LUCID_TIMEOUT'), 서버 오류 시 Error('verify NNN') throw.

AFail-Closed 권장 — 금융 · 티켓팅 · 결제

JStry { const { verdict, token } = await Lucid.verify(); if (verdict === 'MACRO') return block(); await checkout(token); } catch (e) { // 검증 실패 = 차단 return block(); }

BFail-Open 일반 커머스 · 회원가입 · 저위험

JStry { const { verdict, token } = await Lucid.verify(); if (verdict === 'MACRO') return block(); await checkout(token); } catch (e) { // 검증 불가 시 통과 — 가용성 우선 console.warn('Lucid unavailable', e); await checkout(); // 토큰 없이 진행. 백엔드가 토큰 미존재 허용 처리 }
Policy

기본값 권장은 Fail-Closed. 결제·티켓팅·예매·응모처럼 금전적·희소 자산이 걸린 플로우에서는 Lucid 가 죽었을 때 결제가 막히는 편이 낫습니다. 일반 회원가입·검색·뉴스레터는 Fail-Open 이 가용성 측면에서 합리적입니다.

09

SPA 통합

React · Vue · Next.js

React · Vue · Next.js 같은 Single Page Application 환경에서는 라우트 전환 시 HTML 이 리로드되지 않습니다. Lucid.pageView() 를 라우트 이벤트에 연결하세요.

pageView() 는 세션 만료 (발급 후 9분) 체크 후 필요 시 재발급 · 프리워밍을 자동 수행합니다.

REACTReact Router v6+

JSXimport { useEffect } from 'react'; import { useLocation } from 'react-router-dom'; function LucidTracker() { const location = useLocation(); useEffect(() => { window.Lucid?.pageView(); }, [location.pathname]); return null; } // App 최상위에 <LucidTracker /> 배치

VUEVue Router 4

JSrouter.afterEach((to, from) => { window.Lucid?.pageView(); });

NEXTNext.js App Router

TSX'use client'; import { useEffect } from 'react'; import { usePathname } from 'next/navigation'; export function LucidTracker() { const pathname = usePathname(); useEffect(() => { window.Lucid?.pageView(); }, [pathname]); return null; } // layout.tsx 에 배치
Note

SPA 라우터 없이 Lucid.init() 만 호출하면 10분 후 세션이 만료되어 수집이 중단됩니다. SPA 환경에서 장시간 체류 가능한 플로우 (장바구니 → 결제 등) 는 pageView() 연결이 필수입니다.

10

iframe · 새 창

Edge Cases

대부분 통합에서 신경 쓸 필요 없습니다. SDK 는 각 페이지 · iframe 에서 독립 동작하며, Lucid.verify() 는 PG 결제창 오픈 이전 에 귀사 부모 창에서 호출되므로 PG 의 iframe · 팝업 구조와 무관합니다.

표준 플로우

좌석 선택 → 예매자 정보 → 결제하기 클릭 시점에 Lucid.verify() → 토큰을 백엔드 전송 → /siteverify 통과 후 PG 창 오픈. 판정 근거가 되는 사용자 궤적은 전부 귀사 도메인에 누적되어 있습니다.

예외 — 결제 버튼이 동일 오리진 iframe 내부에 있는 경우 (드묾): 해당 iframe 내부 HTML 에도 SDK 를 로드하세요.

HTML · iframe<script src="https://lucid.hrmk.studio/sdk.js" data-site-key="pk_live_xxx"></script>
11

모바일 WebView

iOS · Android

네이티브 앱의 WebView 에서 SDK 가 로드되는 경우, OS 가 백그라운드 진입 시 JavaScript 타이머·fetch 를 동결시킬 수 있습니다. SDK 는 visibilitychange 이벤트로 자동 방어합니다.

SDK 내부 자동 처리:

WebView 고려사항

iOS WKWebView, Android WebView 에서 기본 동작. 단, 앱이 백그라운드 진입 시 WebView 를 완전 종료하는 경우 (메모리 부족 등) 세션 재개 불가 — 새 세션으로 시작됨. 이는 보안상 바람직한 동작입니다.

네이티브 앱 개발자 추가 권장:

12

비동기 로드

async · defer

프론트엔드 최적화를 위해 SDK 를 async·defer 로 로드하는 경우, 스크립트 로드 완료 전에 Lucid.verify() 호출 시 ReferenceError 위험이 있습니다.

A안전한 방법 — Command Queue 권장

SDK 스크립트 태그 이전 에 부트스트랩 스니펫을 삽입:

HTML<script> window.Lucid = window.Lucid || {}; window.LucidQueue = window.LucidQueue || []; ['init', 'verify', 'pageView', 'clearSession', 'debug'].forEach(fn => { window.Lucid[fn] = window.Lucid[fn] || function(...args) { return new Promise((resolve, reject) => { window.LucidQueue.push([fn, args, resolve, reject]); }); }; }); </script> <script src="https://lucid.hrmk.studio/sdk.js" data-site-key="pk_live_xxx" async></script>

이 패턴이면 SDK 로드 전에 await Lucid.verify() 호출해도 큐에 쌓였다가 SDK 로드 후 순차 실행됩니다. Google Analytics dataLayer 와 동일 개념.

B간단한 방법 — 동기 로드

위 부트스트랩이 부담스러우면 async·defer 를 쓰지 않는 기본 로드:

HTML<script src="https://lucid.hrmk.studio/sdk.js" data-site-key="pk_live_xxx"></script>

동기 로드 지연은 약 5~15ms 수준. LCP · FCP 측정에 유의미한 영향 없음.

주의

async · defer 를 사용하면서 부트스트랩 스니펫 없이 Lucid.verify() 를 호출하면 결제 플로우가 ReferenceError 로 멈출 수 있습니다. 두 옵션 중 하나 반드시 선택.

13

개발자 도구

Debug · Types

통합 단계에서 SDK 내부 동작을 확인하거나, TypeScript 자동완성을 받을 수 있습니다.

A콘솔 배너

SDK 로드 시 브라우저 개발자 콘솔에 Lucid 정상 작동 여부를 확인할 수 있는 배너가 출력됩니다. 통합 초기 디버깅 시 이 배너가 보이면 SDK 가 정상 로드된 것입니다.

출력 예시 (F12 → Console):

CONSOLE██╗ ██╗ ██╗ ██████╗██╗██████╗ ██║ ██║ ██║██╔════╝██║██╔══██╗ ██║ ██║ ██║██║ ██║██║ ██║ ██║ ██║ ██║██║ ██║██║ ██║ ███████╗╚██████╔╝╚██████╗██║██████╔╝ ╚══════╝ ╚═════╝ ╚═════╝╚═╝╚═════╝ ✓ Lucid is running. This console is a space for developers. Overwhelming Working Code Only. Studio Hirameki · https://hrmk.studio

배너를 끄려면 스크립트 태그에 data-quiet 추가, 또는 로드 전 window.LUCID_QUIET = true 선언:

HTML<script src="https://lucid.hrmk.studio/sdk.js" data-site-key="pk_live_xxx" data-quiet></script>

BDebug 모드

Lucid.debug(true) 호출 시 SDK 내부 이벤트를 콘솔에 상세 출력합니다. localhost · 127.0.0.1 · *.local · staging · dev 호스트에서만 작동하며, 프로덕션 호스트에서는 호출해도 무시됩니다.

JSLucid.debug(true); Lucid.init();

출력 예시:

CONSOLE[Lucid] debug mode on. host=localhost [Lucid] init called, requesting new session [Lucid] new session issued: a1b2c3d4... [Lucid] flush: 50 points → /stack (total 127) [Lucid] verify called. sid=a1b2c3d4..., points=287 [Lucid] verify response (212ms): verdict=HUMAN, token=eyJzaWQi... [Lucid] clearSession called

출력 제외 항목 (프라이버시 · 보안):

CTypeScript 타입 정의

TypeScript 프로젝트에서는 lucid-sdk.d.ts 를 포함하여 자동완성·타입 체크를 받을 수 있습니다.

Type Def https://lucid.hrmk.studio/sdk.d.ts

사용 예 (프로젝트 루트에 lucid-sdk.d.ts 배치 후):

TS// 자동완성 + 타입 체크 활성화 const { verdict, token } = await Lucid.verify(); if (verdict === 'HUMAN') { // verdict 는 'HUMAN' | 'MACRO' 로 자동 추론됨 await fetch('/api/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ lucid_token: token }), }); }
효과

오타 방지 ('HUMEN' 같은 실수 컴파일 시 차단) · 함수 시그니처 자동완성 · JSDoc 주석이 IDE 툴팁으로 표시. 매뉴얼 재참조 없이 IDE 에서 바로 가이드.

14

Best Practices

3 rules
15

Limitation of Liability

Legal

15.1 서비스 보장 범위. 본 매뉴얼에 명시된 통합 방식을 전부 준수한 경우에 한해 서비스 수준 협약(SLA) 및 탐지 정확도가 보장됩니다. 탐지 정확도는 개별 고객사 트래픽 특성에 따라 변동 가능하며, 구체 수치는 개별 계약서에 명시된 조건을 따릅니다.

15.2 책임 배제. 다음의 경우 발생한 매크로 미탐지·오탐지 및 이로 인한 직접·간접·파생·결과적 손해에 대해 Studio Hirameki 는 계약상·불법행위상·기타 어떠한 법리에 근거하여도 일체 책임지지 않습니다:

15.3 책임 상한. Studio Hirameki 의 누적 배상 책임은, 어떠한 경우에도 직전 12개월간 고객사가 실제로 지급한 서비스 이용료 총액을 초과하지 않습니다. 이는 계약 · 불법행위 · 보증 · 엄격책임 등 모든 법리에 공통 적용됩니다.

15.4 배제 손해 항목. Studio Hirameki 는 다음 유형의 손해에 대해서는 책임지지 않습니다: 매출 손실, 이익 상실, 데이터 손실, 영업권 손상, 대체 서비스 구입 비용, 징벌적 손해, 특별 손해, 결과적 손해.

15.5 통지 의무. 고객사는 SLA 위반을 주장하는 경우 사안 인지 후 7일 이내 서면 통지해야 하며, 통지에는 발생 시점, 영향 범위, 관련 세션 ID 및 로그를 포함해야 합니다. 이 기간 경과 시 해당 사안에 대한 청구권을 상실합니다.

15.6 우선 조항. 본 §15 조항은 개별 계약서의 명시적 다른 합의에 의해서만 변경됩니다. 구두 합의, 영업 프레젠테이션, 이메일 교신 등은 본 조항을 변경하지 않습니다.

※ 본 조항은 표준 계약 조건입니다. 개별 계약 체결 시 법률 자문을 거친 최종 약관이 우선 적용됩니다.

16

Support

Contact

(기술 문의 채널은 계약 시 안내)

Session —
Points 0
Elapsed —
—