← 홈으로 돌아가기
Integration Guide

Shadow Mode 도입 방법

결제 마찰 없이 백그라운드에서 악성 봇 트래픽을 측정합니다.
API 키 발급 없이 프론트엔드 코드 스니펫만으로 즉시 연동됩니다.

1. 섀도우 모드(Shadow Mode)란?

기존 결제 방어 솔루션(캡차 등)은 봇 검증이 끝날 때까지 유저를 대기(Block)시킵니다.
아킬레스 섀도우 모드는 비동기(Fire-and-forget) 방식으로 동작하여 결제 로직에 단 1ms의 딜레이도 주지 않으며, 봇 데이터만 수집하여 대시보드로 리포트를 제공하는 무상태 안전 모드입니다.

2. 가드버튼(Guard Button) 스니펫 복사하기 (Front-end)

귀사의 결제 버튼을 아킬레스 가드버튼으로 래핑(Wrapping)해 주십시오. 아래 코드를 복사하여 붙여넣으면 됩니다.

<!-- 1. 아킬레스 SDK 로드 (data-site-key = 발급받은 API 키) -->
<script src="https://lucid.hrmk.studio/sdk" data-site-key="YOUR_API_KEY"></script>

<script>
  // 2. 결제 버튼을 가드버튼으로 래핑 (섀도우: 결제는 지연 없이 그대로 진행)
  Lucid.guardButton(document.getElementById("checkout-btn"), function(token) {
    // 섀도우 트라이얼 — 여기선 아무것도 안 함: 기존 결제 프로세스가 그대로 실행됩니다.
  });
</script>

💡 유일한 연동 가이드라인 (중요)

아킬레스 물리 엔진은 단일 페이지 내에서도 오탐이 극히 드물게 발생하도록 고도화되어 있습니다. 다만, 오탐을 수학적 한계까지 극소화하기 위해 유저가 결제 버튼을 누르기 전 약 0.5초 ~ 0.8초 정도 자연스럽게 마우스 궤적을 수집할 수 있도록 설계해 주십시오. (예: 결제 버튼이 페이지 로딩 직후 곧바로 클릭되지 않고, 약간의 스크롤이나 마우스 이동이 필요한 위치에 배치)

3. 백엔드 스니펫 — 직접-API 봇까지 측정 (권장)

프론트엔드 가드버튼은 브라우저를 거치는 봇(자동화 툴·매크로)을 측정합니다. 하지만 일부 봇은 브라우저를 아예 건너뛰고 결제 API를 서버로 직접 호출합니다(직접-API 봇). 이 트래픽은 구조상 서버에서만 관측되므로, 결제 처리 핸들러 맨 앞에 아래 한 줄을 추가하면 대시보드에 함께 집계됩니다. 여전히 섀도우(Fire-and-forget)라 결제 흐름·속도에 영향이 없습니다.

// 결제 처리 핸들러 맨 앞 (Node.js 예시) — 섀도우: 로그만, 결제는 그대로 진행
fetch("https://lucid.hrmk.studio/observe", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Lucid-Secret": "YOUR_SECRET_KEY" },
  body: JSON.stringify({ token: req.body.token, ip: req.ip })
}).catch(() => {});   // fire-and-forget · 실패해도 결제 영향 0

// ↓ 기존 결제 로직 그대로 (차단 없음)

🔍 왜 백엔드까지 필요한가요?

브라우저를 건너뛰고 결제 엔드포인트를 직접 두드리는 봇은 프론트엔드 코드만으로는 구조적으로 관측되지 않습니다 (애초에 브라우저를 안 거치니까요). 이 한 줄은 서버로 들어온 요청의 정상 토큰 유무만 리포트하며(로그 전용, 판정·차단 없음), 정식 방어로 전환하실 땐 이 관측 호출을 검증(siteverify)으로 바꾸시면 실제 차단이 활성화됩니다. 프론트(클릭 봇) + 백엔드(직접-API 봇)를 함께 넣으셔야 전체 봇 트래픽이 대시보드에 온전히 잡힙니다.

4. 직접 눌러보기 — 오탐 테스트

백문이 불여일견입니다. 지금 이 페이지에서 마우스를 자연스럽게 움직인 뒤 아래 가드버튼을 눌러 보십시오. 사람의 손이라면 물리 엔진이 즉시 통과시킵니다. (실제 SDK가 로드된 라이브 데모입니다.)

여기에 오탐이 나는지 직접 확인해 보세요 👇

아직 검증되지 않음

API 키가 필요하신가요?

귀사 전용 트래픽 측정 및 리포트 생성을 위한 API 키를 요청하시면 즉시 무료로 발급해 드립니다.
연동 후 기존 방어망을 뚫고 들어온 악성 봇이 얼마나 되는지 두 눈으로 확인해 보십시오.

API 키 무료 발급 요청하기