Quickstart (5분)

1. API Keys 페이지에서 키를 발급합니다.
   • 키 이름 — 어떤 앱에서 쓰는 키인지 알아볼 수 있게. 예: web-prod, web-staging, inflearn-prod.
   • 허용 도메인 (강력 권장) — 이 키로 SDK를 호출할 수 있는 사이트 주소(origin) 목록입니다. 여기 등록되지 않은 사이트에서 호출하면 브라우저가 CORS 에러로 막아요.
     여러 개 등록 — 콤마(,), 공백, 또는 줄바꿈으로 구분해서 한 번에 여러 주소를 적을 수 있습니다.
     예: http://localhost:3000, https://staging.example.com, https://www.example.com
     로컬 개발 시 주의 — 개발 PC(http://localhost:3000 등)에서 테스트하려면 그 주소를 반드시 추가해야 합니다. 비워두면 자동으로 다 허용되는 게 아니라, 운영 기본 도메인(인프런 계열)만 허용됩니다.
     형식 주의 — http:///https:// 스킴 필수, 끝에 / 금지, 포트가 다르면 다른 주소, www.example.com과example.com도 별개라 둘 다 쓰면 둘 다 등록.
     자세히는 /docs/security.
   • 일일 한도 — 이 키가 하루에 우리 서버를 몇 번 부를 수 있는지 정합니다. 외부 사이트(예: 인프런)에 발급하는 키는 꼭 설정해주세요.
     계산 예: DAU × 사용자당 하루 평균 호출 × 여유 3배
     DAU 5만, 평균 40회 폴링 → 5만 × 40 × 3 ≈ 600만. 안전 시작값은 2,000,000 정도.
     한도를 넘어도 SDK는 마지막에 저장된 플래그 값으로 약 5분간 계속 동작합니다. 비워두면 제한 없음(어드민 내부용에만 권장).
   • 즉시 반영 (옵션 키: realtime) — 기본 OFF, 권장 OFF.
     켜면: 어드민에서 플래그를 바꾸는 순간(약 1초) 사용자 화면에 반영됩니다. 대신 사용자 한 명당 우리 서버 연결을 계속 열어둬서, 사용자가 많을수록 비용이 크게 늘어요.
     끄면: SDK가 60초마다 변경을 확인합니다. 평균 30~60초 안에 반영. 사용자 수와 무관하게 비용이 안정적입니다.
     외부 사이트에 발급하는 키는 무조건 OFF로 두세요. 어드민 미리보기처럼 1~2명만 쓰는 내부 키만 ON을 고려합니다.
2. 호스트 프로젝트에서 설치:

pnpm add @taekcle/web@^0.2.0

혹은 npm:

npm i @taekcle/web@^0.2.0

v0.2 이상을 쓰세요. 이전 버전은 사용자가 많아질수록 우리 서버 호출이 비례해서 늘어났는데, v0.2부터는 사용자 수와 무관하게 비용이 안정적입니다.

1) Provider 셋업 (Next.js App Router 예시)

'use client';
import { createClient, TaekcleProvider } from '@taekcle/web';
import { useMemo } from 'react';

export function Providers({ children, deviceId, userId }) {
  const client = useMemo(
    () =>
      createClient({
        apiKey: process.env.NEXT_PUBLIC_TAEKCLE_KEY!,
        apiUrl: process.env.NEXT_PUBLIC_TAEKCLE_URL!,
        identity: { deviceId, userId },
      }),
    [deviceId, userId],
  );
  return <TaekcleProvider client={client}>{children}</TaekcleProvider>;
}

2) Variant 사용

'use client';
import { useVariant } from '@taekcle/web';

export function CheckoutCTA() {
  const variant = useVariant('checkout-redesign', 'control');
  // 호스트 앱이 직접 이벤트 발화
  // mixpanel.track('experiment_started', { experiment: 'checkout-redesign', variant });
  return variant === 'B' ? <NewCTA /> : <OldCTA />;
}

3) 플래그 사용

import { useFlag } from '@taekcle/web';

const showBanner = useFlag('promo-banner', false);
if (showBanner) return <Banner />;

4) 로그인 시 identity 매핑

import { identify, useTaekcle } from '@taekcle/web';

const client = useTaekcle();
await identify(client, {
  deviceId: getDeviceId(),
  userId: currentUser.id,
  apiKey: process.env.NEXT_PUBLIC_TAEKCLE_KEY!,
  apiUrl: process.env.NEXT_PUBLIC_TAEKCLE_URL!,
});

5) 권장 옵션 (외부 사이트에 부착할 때)

createClient({
  apiKey: process.env.NEXT_PUBLIC_TAEKCLE_KEY!,
  apiUrl: process.env.NEXT_PUBLIC_TAEKCLE_URL!,
  identity: { deviceId, userId },
  pollIntervalMs: 60_000,   // 60초마다 변경 확인 (권장)
  realtime: false,          // 즉시 반영 OFF (외부 사이트는 무조건 OFF)
});

• 변경 확인 주기 (pollIntervalMs) — 기본 web 30초 / node 60초. 늘리면 우리 서버 호출이 줄어 더 적은 일일 한도로도 충분합니다. 플래그를 바꾼 뒤 사용자 화면에 반영되는 시간은 평균 이 값의 절반 + 약 30초.
• 즉시 반영 (realtime) — 외부 사이트에서는 절대 켜지 마세요. 키에 권한이 없으면 서버가 거절합니다. 정말 1초 안에 반영이 필요하면 운영자에게 권한을 요청하세요.

6) 서버가 에러를 응답할 때 (드뭄)

SDK는 마지막에 받은 플래그 값을 디스크에 저장해두고, 서버가 일시적으로 응답하지 않아도 그 값으로 약 5분 동안 계속 동작합니다. 그래서 아래 에러가 잠깐 발생해도 호스트 앱은 멈추지 않아요. 다만 같은 에러가 반복되면 운영자에게 연락이 필요합니다.

SDK 동작이 더 궁금하면 SDK Reference 마지막 섹션을 보세요.

Playground에서 바로 테스트