FlowWatch SDK 연동 가이드

FlowWatch는 트래픽 급증 시 가상 대기열을 통해 동시 접속을 제어하는 서비스입니다. 고객 사이트에 SDK를 연동하면, 대기열 오버레이가 자동으로 동작합니다.

1. SDK 설치

Script Tag 방식

별도 설치 없이 HTML에 스크립트 태그를 삽입합니다.

<script src="https://main.dke6twdfwchgf.amplifyapp.com/sdk.js" data-event-id="발급받은 이벤트 ID"></script>

페이지 로드 시 자동으로 대기열이 시작됩니다.

npm 방식

npm install flowwatch-sdk

const FlowWatch = require("flowwatch-sdk");

FlowWatch.init("발급받은 이벤트 ID");

• data-event-id / 첫 번째 인자: FlowWatch에서 발급받은 이벤트 ID (evt-xxxxxx 형식)
• apiBase: FlowWatch 서버 주소 (기본값 내장, 별도 설정 불필요)

2. SDK 동작

| 동작 | 설명 | |------|------| | 대기열 진입 | 페이지 로드 시 자동으로 대기열에 진입합니다 | | 오버레이 표시 | 대기 중일 때 전체 화면 오버레이로 현재 순번을 표시합니다 | | 순번 폴링 | 3초 간격으로 대기 순번을 갱신합니다 | | 입장 허용 | 차례가 되면 오버레이가 자동으로 해제됩니다 | | Heartbeat | 입장 후 30초 간격으로 활성 상태를 유지합니다 | | 자동 정리 | 유저가 이탈하면 120초 후 자동으로 자리가 반환됩니다 |

3. 클라이언트 API

FlowWatch.leave()

구매 완료, 로그아웃 등 유저가 떠나는 시점에 호출하면 즉시 자리가 반환됩니다.

// 예: 구매 완료 후
async function onPurchaseComplete() {
  await submitOrder();
  FlowWatch.leave(); // 즉시 자리 반환
}

호출하지 않아도 heartbeat 만료(120초) 후 자동 정리되지만, 호출하면 다음 대기자가 더 빠르게 입장할 수 있습니다.

FlowWatch.getToken()

입장이 허용된 유저의 JWT 액세스 토큰을 반환합니다. 서버 사이드 검증에 사용합니다.

const token = FlowWatch.getToken();
// 대기 중이거나 아직 입장 전이면 null

4. 서버 사이드 토큰 검증 (선택)

SDK만으로도 대기열은 동작하지만, 개발자 도구로 오버레이를 삭제하는 우회를 방지하려면 서버에서 토큰을 검증해야 합니다.

흐름

1. 유저 입장 허용 → SDK가 토큰 보유
2. 클라이언트에서 FlowWatch.getToken()으로 토큰 획득
3. 고객 서버로 토큰 전달 (헤더, 쿼리 등 자유)
4. 고객 서버에서 FlowWatch verify API 호출
5. 응답의 valid 값으로 요청 허용/차단

API

GET https://main.dke6twdfwchgf.amplifyapp.com/api/queue/verify?token={토큰}

응답

유효한 토큰 (200)

{
  "valid": true,
  "eventId": "evt-xxxxxx",
  "visitorId": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2026-07-30T15:30:00.000Z"
}

만료된 토큰 (401)

{
  "valid": false,
  "error": "Token expired"
}

잘못된 토큰 (401)

{
  "valid": false,
  "error": "Invalid token"
}

서버 연동 예시 (Node.js)

app.post("/api/purchase", async (req, res) => {
  const token = req.headers["x-flowwatch-token"];

  const result = await fetch(
    `https://main.dke6twdfwchgf.amplifyapp.com/api/queue/verify?token=${token}`
  ).then((r) => r.json());

  if (!result.valid) {
    return res.status(403).json({ error: "대기열 인증 실패" });
  }

  // 정상 유저 → 구매 로직 처리
});

클라이언트에서 토큰 전달 예시

fetch("/api/purchase", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-FlowWatch-Token": FlowWatch.getToken(),
  },
  body: JSON.stringify({ productId: "abc" }),
});