빠른 연동

프로젝트 생성 후 브라우저와 서버리스 route handler에 첫 이벤트를 붙이고, 수집 성공을 확인합니다.

이 문서는 리옵트 데이터를 처음 붙이는 개발자를 위한 빠른 연동 가이드예요. 브라우저 이벤트 하나와 서버리스 이벤트 하나를 보내고, 프로젝트 화면에서 수집 결과를 확인합니다.

시작하기 전에

다음 네 가지가 준비되어 있어야 합니다.

준비물	어디서 확인하나요?
조직	`/dashboard`에서 만들거나 선택합니다.
프로젝트	`/dashboard/[orgId]`에서 만듭니다.
브라우저용 `writeKey`	프로젝트 홈의 SDK snippet에서 확인합니다.
서버용 `clientId`, `serverSecret`	프로젝트 생성 직후 또는 client 설정에서 확인합니다.

serverSecret은 서버 전용 비밀값입니다. 브라우저 번들, HTML, client component, 공개 저장소에는 넣지 마세요. SDK 옵션과 환경변수 예시에서는 같은 값을 clientSecret이라는 이름으로 넣습니다.

1. 패키지 설치하기

pnpm add @reopt-ai/data-sdk

모노레포 안에서 특정 앱에만 설치한다면 해당 앱 디렉터리에서 실행하세요.

2. 환경변수 추가하기

브라우저에서 쓰는 값은 공개 환경변수로 둡니다. 서버에서 쓰는 값은 공개 prefix 없이 둡니다.

# Browser
NEXT_PUBLIC_REOPT_WRITE_KEY="wpk_..."
NEXT_PUBLIC_REOPT_API_URL="https://data.reopt.ai"

# Server
REOPT_CLIENT_ID="client_..."
REOPT_CLIENT_SECRET="sec_..."
REOPT_API_URL="https://data.reopt.ai"

로컬에서 리옵트 데이터 앱을 함께 띄운다면 REOPT_API_URL과 NEXT_PUBLIC_REOPT_API_URL을 http://localhost:4001로 바꿔도 됩니다.

3. 브라우저 이벤트 보내기

앱의 클라이언트 진입점에서 SDK를 초기화합니다. 초기화 뒤에는 track, identify, pageView를 사용할 수 있어요.

import { init, identify, pageView, track } from "@reopt-ai/data-sdk";

init({
  writeKey: process.env.NEXT_PUBLIC_REOPT_WRITE_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_REOPT_API_URL,
  debug: true,
});

pageView();

track("signup_clicked", {
  location: "header",
  plan: "starter",
});

identify("user_123", {
  plan: "starter",
});

debug: true는 로컬과 preview 환경에서 큐잉과 전송 상태를 확인할 때만 사용하세요. 운영 환경에서는 불필요한 로그가 남지 않도록 끄는 것이 좋습니다.

4. Next.js route handler에서 서버 이벤트 보내기

서버리스 route handler에서는 trackAndFlush를 사용하세요. 요청이 끝나기 전에 전송까지 완료할 수 있습니다.

import { Reopt } from "@reopt-ai/data-sdk/node";

const reopt = new Reopt({
  clientId: process.env.REOPT_CLIENT_ID!,
  clientSecret: process.env.REOPT_CLIENT_SECRET!,
  baseUrl: process.env.REOPT_API_URL,
});

export async function POST(request: Request) {
  const body = await request.json();

  const delivery = await reopt.trackAndFlush("checkout_completed", {
    orderId: body.orderId,
    amount: body.amount,
    currency: "KRW",
  });

  return Response.json({
    ok: delivery.queue.queued && delivery.flush?.status === "success",
    eventId: delivery.queue.eventId,
    delivery,
  });
}

긴 수명의 서버에서는 track()으로 큐에 넣고 주기적으로 flush()할 수 있습니다. 서버리스에서는 런타임이 타이머를 끝까지 보장하지 않을 수 있으므로 trackAndFlush 계열을 우선 사용하세요.

5. 수집 결과 확인하기

첫 이벤트를 보낸 뒤 아래 순서로 확인하세요.

브라우저 Network 탭에서 POST /api/track 응답이 200인지 봅니다.
응답의 accepted가 1 이상인지 봅니다.
프로젝트의 이벤트 카탈로그에서 이벤트 이름이 보이는지 확인합니다.
DevTools에서 materialization 상태와 최근 이벤트를 확인합니다.
로그인 직후 identify를 보냈다면 사용자 프로필에 profileId가 연결되는지 확인합니다.

수집된 이벤트 이름과 볼륨, 최근 수집 시각을 보여주는 이벤트 카탈로그 — 첫 이벤트가 정상 수집되면 이벤트 카탈로그에서 이름, 볼륨, 최근 수집 시각을 확인할 수 있어요.

데모 데이터와 추적 시나리오를 실행할 수 있는 DevTools 화면 — 로컬 검증에서는 DevTools의 시나리오를 사용해 이벤트 수집과 materialization 흐름을 빠르게 재현할 수 있습니다.

성공 응답은 보통 다음 형태입니다.

{
  "status": "ok",
  "requestId": "req_...",
  "accepted": 1,
  "duplicates": 0,
  "queued": true
}

accepted는 새 raw event로 저장된 수입니다. queued가 true이면 분석 테이블 반영을 위한 background task가 만들어졌다는 뜻이에요.

자주 막히는 지점

증상	확인할 것
401 응답	브라우저에는 `writeKey`, 서버에는 `clientId + serverSecret`을 썼는지 확인하세요.
400 validation failed	이벤트 타입, `eventId`, `timestamp`, payload 구조가 v2 계약에 맞는지 확인하세요.
429 응답	프로젝트 rate limit 또는 조직 quota를 확인하세요.
응답은 200인데 화면에 늦게 보임	queue consumer, ingest worker, materialization 상태를 확인하세요.
같은 이벤트가 duplicate 처리됨	같은 `eventId`를 재사용하고 있지 않은지 확인하세요.
사용자가 연결되지 않음	로그인 직후 `identify`를 보냈는지, 이후 이벤트에 `profileId`가 붙는지 확인하세요.

다음 단계

SDK 동작을 더 자세히 보려면 추적 설정
이벤트 의미를 정리하려면 이벤트 카탈로그
수집 파이프라인을 운영 관점에서 보려면 데이터 수집과 거버넌스

On this page