온길 — 에이전트 연동 가이드

온길(k-datafast)은 방문자의 최초 유입 채널에 결제 매출을 귀속시키는 웹 애널리틱스다. 이 문서는 AI 에이전트가 새 웹 프로젝트를 온길에 등록하고 트래킹을 붙이는 작업을 사람 도움 없이 끝낼 수 있도록 쓴 것이다. 서버 주소: https://analytics.stonkradar.io (이 문서: https://analytics.stonkradar.io/llms.txt · 사람이 읽는 판: https://analytics.stonkradar.io/docs)

작업 순서 요약

  1. kdf whoami 로 인증 확인 (안 되면 인증 — 토큰은 사람에게 요청)
  2. kdf sites ensure "<프로젝트 이름>" <배포 도메인> --json 으로 사이트 등록 → publicId 획득
  3. 모든 페이지 <head> 에 트래킹 스크립트 삽입 (스크립트 설치)
  4. (결제가 있으면) 서버에 결제 보고 연동, sk_ 키는 시크릿 저장소에만 (결제 연동)
  5. 배포 후 kdf overview <publicId> --days 1 로 수집 확인

지켜야 할 규칙

인증

CLI kdf (Node 24+, 의존성 없음) 가 기본 인터페이스다.

kdf whoami        # "이름 <이메일> · 역할" 과 서버 주소가 나오면 준비 완료

API 토큰(kpat_...) 은 발급한 조직의 사이트에만 접근하고, 실제 권한은 스코프 ∩ 발급자의 현재 조직 역할 이다.

스코프 허용
sites:read 사이트 목록
sites:write 사이트 생성(ensure)·수정
stats:read 통계·실시간·메트릭 조회
keys:read 기존 사이트의 sk_ 키 조회 (새로 만든 사이트의 키는 이 스코프 없이도 생성 응답에 온다)

사이트 등록

kdf sites ensure "내 프로젝트" my-project.com --json
{
  "created": true,
  "site": {
    "publicId": "kdf_1a2b3c4d5e6f",
    "name": "내 프로젝트",
    "domain": "https://my-project.com",
    "apiKey": "sk_...",
    "org": { "id": "...", "name": "..." },
    "role": "owner"
  }
}

CLI 를 쓸 수 없으면 REST 로 같은 일을 한다:

curl -X POST https://analytics.stonkradar.io/api/sites/ensure \
  -H "Authorization: Bearer $KDF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"내 프로젝트","domain":"my-project.com"}'

스크립트 설치

모든 페이지의 <head> 에 한 줄. SPA 라우팅(pushState/popstate)은 자동 추적된다.

<script defer src="https://analytics.stonkradar.io/k.js" data-site="kdf_1a2b3c4d5e6f"></script>
프레임워크 넣는 곳
정적 HTML · Vite · CRA index.html 의 <head>
Next.js App Router app/layout.tsx 의 <head> 에 next/script (strategy="afterInteractive", data-site 속성 그대로)
Next.js Pages Router pages/_document.tsx 의 <Head> 에 일반 <script defer ...>
Astro 공통 레이아웃(src/layouts/*.astro)의 <head> 에 <script is:inline defer ...>
SvelteKit src/app.html 의 <head>
Nuxt nuxt.config.ts 의 app.head.script 에 { src, defer: true, 'data-site': '...' }
Cloudflare Workers (HTML 응답) 정적 자산이면 HTML 파일의 <head>, 문자열로 HTML 을 만들면 그 템플릿의 <head>

선택 속성:

목표(전환) 이벤트

window.kdatafast?.goal('signup');                     // 코드에서
window.kdatafast?.goal('signup', { plan: 'pro' });    // 속성을 함께
<button data-kdf-goal="cta_click">시작하기</button>                        <!-- 속성만으로 -->
<button data-kdf-goal="checkout" data-kdf-goal-plan="pro">결제</button>    <!-- data-kdf-goal-<속성> -->

결제 연동

트래커가 발급한 방문자 ID(window.kdatafast.visitorId)를 주문과 연결해 두면 결제 시 그 방문자의 최초 유입 채널에 매출이 귀속된다. 서버 API 는 모두 헤더 x-api-key: sk_... 가 필요하므로 반드시 서버에서 호출한다.

  1. 주문 생성 시 프론트에서 window.kdatafast?.visitorId 를 받아 주문과 함께 저장한다.
  2. 결제가 확정되는 서버 코드에서 한 번 보고한다 (매핑이 없으면 생성까지 한다):
await fetch('https://analytics.stonkradar.io/api/payments/paid', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.ONGIL_API_KEY! },
  body: JSON.stringify({
    orderId: 'order-123',
    visitorId,          // 주문 시점에 저장해 둔 값
    amount: 15000,      // 정수. KRW 는 원 단위
    currency: 'KRW',
    provider: 'toss',   // 선택
  }),
});

전환 퍼널

방문자가 어디까지 오고 어디서 멈추는지 본다. 단계는 2~8개이고 방문자(브라우저) 단위로, 기간 안에서 순서대로 지난 경우만 센다. 단계마다 "이전 단계까지 왔지만 여기 오지 못한 방문자가 마지막으로 한 일"(페이지·목표, 또는 이후 활동 없음)을 함께 돌려준다.

단계 표기 뜻
/경로 페이지 조회. * 는 아무 문자열 (/order/*), 모든 페이지는 *
goal:이름 커스텀 목표 (kdatafast.goal('이름'))
payment_started 결제 시작 — 서버가 POST /api/payments/link 로 주문과 방문자를 이은 시점
payment 결제 완료
kdf funnels kdf_1a2b3c4d5e6f                 # 저장한 퍼널 + 단계로 쓸 수 있는 페이지·목표
kdf funnel kdf_1a2b3c4d5e6f --step / --step /pricing --step goal:checkout --step payment_started --step payment
kdf funnels create kdf_1a2b3c4d5e6f "결제 퍼널" --step / --step /pricing --step payment   # 저장 (조직 admin)
kdf funnel kdf_1a2b3c4d5e6f --funnel "결제 퍼널" --days 7

수집 확인

kdf overview kdf_1a2b3c4d5e6f --days 1      # 방문자·페이지뷰·방문·이탈률·평균 체류·채널
kdf overview kdf_1a2b3c4d5e6f --days 30 --filter channel=Threads --filter device=mobile   # 조건에 맞는 방문자만
kdf summary                                 # 전체 사이트 현재 접속자

방문(세션)·체류 시간은 트래커가 자동으로 잰다 (탭이 보이는 동안 1분마다 신호). 별도 설치 작업은 없다.

배포 직후 직접 한 번 방문하면 수 초 안에 잡힌다. 운영자 본인 방문을 빼려면 사이트를 https://my-project.com/#kdf_exclude 로 한 번 열면 그 브라우저가 제외된다.

방문했는데 방문자가 늘지 않고 봇 목록에 다른 도메인 (호스트) 가 보이면, 스크립트가 등록 도메인이 아닌 곳에 설치된 것이다. 등록 도메인을 고치거나(kdf sites update <publicId> --domain ...) 그 호스트를 추가 허용 도메인에 넣는다.

오류 대응

상태 의미 할 일
401 토큰 없음·만료·폐기 사람에게 새 토큰 요청
403 스코프 또는 조직 역할 부족 (예: sites:write 없음) 필요한 스코프를 알려 주고 사람에게 요청
404 그 사이트가 없거나 내 조직 것이 아님 kdf sites 로 publicId 확인
400 orgId 를 지정하세요 관리하는 조직이 여러 개 --org <orgId> 추가
409 sites create 중복 sites ensure 사용

API 요약 (토큰으로 호출 가능한 것)

메서드 경로 스코프
GET /api/sites sites:read
POST /api/sites/ensure sites:write
POST /api/sites sites:write
PATCH /api/sites/:publicId (본문 { name?, domain?, allowedHosts?: string[] }) sites:write
GET /api/stats/summary · /api/stats/overview?siteId=&days=[&f_<키>=<값>] · /api/stats/realtime?siteId= · /api/stats/journeys?siteId=&days=&goalType=&goal= stats:read
GET /api/metrics/latest?siteId= stats:read
GET /api/funnels?siteId= · /api/funnels/options?siteId=&days= stats:read
GET /api/funnels/report?siteId=&days=&funnelId= 또는 &step=/&step=goal:x&step=payment stats:read
POST · PATCH · DELETE /api/funnels · /api/funnels/:id (본문 { siteId, name, steps: [{ type, value? }] }) sites:write (조직 admin)
GET /api/users/me (없음)

개요의 채널 표(channels·channelGroups) 매출은 기본이 첫 유입 귀속이고, &attribution=last 면 결제 직전 마지막으로 출처가 있던 방문(직접 유입 제외)에 귀속한다 (kdf overview ... --attribution last).

개요 필터 f_<키> — 방문자 속성: channel(첫 유입)·channelGroup·referrer(호스트)·campaign·keyword·country·region·city·device·browser·os, 기간 안의 행동: page(본 페이지)·goal(달성한 목표)·visitChannel·visitChannelGroup(방문 경로). 여러 개면 모두 만족하는 방문자만 센다. 행동 필터를 쓰면 previous.complete 가 false 가 된다 (이전 기간과 방문자 집합이 달라 비교할 수 없다).

인증 헤더는 Authorization: Bearer kpat_.... 그 밖의 API(조직·멤버·토큰·사용자 관리, 사이트 삭제)는 토큰으로 호출할 수 없다.

같은 내용의 마크다운 원문: https://analytics.stonkradar.io/llms.txt