SDK Reference

@taekcle/web

v0.2.0에서 바뀐 점 — 기본 realtime이 false로 바뀌었어요. 내부적으로도 더 가벼운 방식으로 동작해서 사용자가 아무리 많아도 우리 서버 호출이 거의 늘지 않습니다. 외부 사이트에는 v0.2 이상을 꼭 사용하세요.

createClient(options)

type CreateClientOptions = {
  apiKey: string;
  apiUrl?: string;            // 기본: http://localhost:3000
  identity: { deviceId: string; userId?: string | null };
  pollIntervalMs?: number;    // 변경 확인 주기. 기본 web 30s / node 60s
  realtime?: boolean;         // 즉시 반영 모드. 기본 false (외부 사이트 권장)
};

즉시 반영(realtime) 옵션 — 외부 사이트에 발급하는 키에는 항상 false로 두세요. 켜면 사용자 한 명당 우리 서버 연결을 계속 열어둬서 비용이 사용자 수에 비례합니다. 정말 1초 안에 반영이 필요한 어드민 미리보기 같은 내부 키만 운영자가 권한을 따로 부여합니다. 권한이 없는 키가 켜고 시도하면 서버가 거절합니다.

<TaekcleProvider client={client} />

useFlag(key, fallback?)

useVariant(key, fallback?)

useTaekcle()

identify(client, { deviceId, userId, apiKey, apiUrl })

실시간 노출 (Exposure) 이벤트

SDK는 getVariant() 또는 getVariantWithReason()을 호출할 때마다 자동으로 노출 이벤트를 서버로 보냅니다. 같은 (실험 키, 사용자) 조합은 30초 윈도우 내에서 중복 발사되지 않으며, 최대 2초 debounce 또는 10개 도달 시 batch flush됩니다. 페이지 이탈 시 sendBeacon으로 마지막 배치를 보냅니다.

// Returns the resolved variant.
const variant = client.getVariant('exp-key', 'control');

// Same, but with the assignment reason ('cookie_override' | 'hash_bucket' | 'fallback').
const { variant, reason } = client.getVariantWithReason('exp-key', 'control');

// 노출 기록을 끄려면 (예: 테스트):
createClient({ ..., recordExposures: false });

어드민이 /experiments/<key> 상세 페이지에서 최근 30분 분배 현황을 5초마다 폴링하여 확인할 수 있습니다. 카운트는 (userId가 있으면 userId, 없으면 deviceId 기준) 고유 사용자 수입니다.

@taekcle/node (서버)

import { createClient } from '@taekcle/node';

const client = createClient({
  apiKey: process.env.TAEKCLE_KEY!,
  apiUrl: process.env.TAEKCLE_URL,
  identity: { deviceId: 'server', userId: req.user?.id },
  cachePath: '/tmp/taekcle.json',     // optional
  pollIntervalMs: 60_000,             // v0.2+ default (was 15s)
});

const variant = client.getVariant('experiment-key');

v0.2 동작 방식 (비용·반영 속도)

SDK는 두 단계로 변경을 감지합니다:

변경 확인 — 매우 가벼운 "버전 번호" 조회. 사용자 근처 캐시가 약 2초 동안 응답을 보관해서 같은 시간에 여러 사용자가 물어와도 서버까지 도달하지 않습니다.
정의 가져오기 — 버전이 바뀌었을 때만 전체 플래그 정의를 가져옵니다. 이 응답도 근처 캐시가 약 30초 동안 보관해서 사용자가 많을수록 캐시가 더 잘 흡수해요.

핵심: 사용자가 늘어도 우리 서버 호출이 그만큼 비례해서 늘지 않습니다 (DAU 10만이어도 분당 1~2회 수준). 플래그를 바꾼 뒤 사용자 화면에 반영되는 시간은 변경 확인 주기 + 약 30초 정도. 어떤 사고가 나서 서버 응답이 안 와도 SDK는 마지막에 저장한 값으로 약 5분간 정상 동작합니다.

서버가 에러를 응답할 때

SDK는 마지막에 받은 플래그 값을 디스크에 저장해두기 때문에 아래 에러가 잠깐 발생해도 호스트 앱은 약 5분간 그 값으로 정상 동작합니다. 같은 에러가 반복되면 운영자에게 키 상태나 한도를 확인해달라고 요청하세요.

응답	무슨 뜻인가요	어떻게 하면 되나요
키 인증 실패 `401`	키가 잘못됐거나 만료/회수/일시정지된 상태입니다.	운영자에게 키 상태를 확인해달라고 하세요. 재발급이 필요할 수 있어요.
권한 없음 `403`	이 도메인에서는 키를 못 쓰거나, 즉시 반영 권한 없는 키가 즉시 반영을 켰어요.	호출 도메인이 허용 목록에 있는지 확인. `realtime: false`로 두세요.
호출 한도 초과 `429`	하루 또는 분당 호출 한도를 넘었어요.	`X-RateLimit-Reset` 헤더의 시각까지 기다리면 자동 해제. 자주 반복되면 변경 확인 주기를 늘리거나 한도 상향을 요청하세요.
서버 일시 장애 `5xx`	우리 서버가 잠깐 응답하지 못했어요.	SDK가 1.5초 안에 호출을 끊고, 5회 연속 실패하면 30초간 호출을 자동 멈춰서 서버 부담을 줄입니다.

서버가 다운돼도 안전합니다

SDK는 마지막에 성공적으로 받은 플래그 값을 디스크(서버) 또는 로컬스토리지(브라우저)에 저장합니다. 서버가 응답을 못 해도 SDK는 그 값으로 계속 동작합니다. 호스트 앱이 다운되는 일은 없습니다.

SDK 안전장치 4가지 (자동 적용)

호스트 앱이 별도로 설정하지 않아도 모든 SDK 호출에는 아래 안전장치가 자동으로 켜져 있습니다.

1.5초 안에 끊기 — 우리 서버가 응답을 안 보내고 멈춰 있으면 SDK가 1.5초 안에 호출을 강제로 끊습니다. 호스트 앱은 즉시 폴백 값으로 진행해서 화면이 멈추지 않습니다.
5회 연속 실패하면 30초 자동 멈춤 — 우리 서버가 계속 실패할 때 SDK가 30초간 호출을 건너뜁니다. 서버에 추가 부담을 주지 않고, 한 번이라도 성공하면 자동으로 다시 호출을 시작합니다.
즉시 반영 재연결을 점점 늦추기 — 즉시 반영 연결이 끊겼을 때 0.5초 → 1초 → 2초 → 4초처럼 재시도 간격을 점점 늘려갑니다. 동시에 여러 사용자가 한꺼번에 몰려서 서버를 덮치는 일을 막아요.
embed.js 노출 차단 3초 안전 한도 — 사이트에 임베드한 스크립트가 플래그를 받기 전까지 콘텐츠를 숨기는 모드가 있는데, 우리 서버가 응답하지 않아도 최대 3초 뒤에는 원본 콘텐츠가 자동으로 보입니다.

상세 회귀 테스트: packages/sdk-core/src/resilience.test.ts + fallback-safety.test.ts. 전체 보안·폴백 정책은 /docs/security.