온길 — 에이전트 연동 가이드
온길(k-datafast)은 방문자의 최초 유입 채널에 결제 매출을 귀속시키는 웹 애널리틱스다. 이 문서는 AI 에이전트가 새 웹 프로젝트를 온길에 등록하고 트래킹을 붙이는 작업을 사람 도움 없이 끝낼 수 있도록 쓴 것이다. 서버 주소:
https://analytics.stonkradar.io(이 문서:https://analytics.stonkradar.io/llms.txt· 사람이 읽는 판:https://analytics.stonkradar.io/docs)
작업 순서 요약
kdf whoami로 인증 확인 (안 되면 인증 — 토큰은 사람에게 요청)kdf sites ensure "<프로젝트 이름>" <배포 도메인> --json으로 사이트 등록 →publicId획득- 모든 페이지
<head>에 트래킹 스크립트 삽입 (스크립트 설치) - (결제가 있으면) 서버에 결제 보고 연동,
sk_키는 시크릿 저장소에만 (결제 연동) - 배포 후
kdf overview <publicId> --days 1로 수집 확인
지켜야 할 규칙
- 등록은
ensure로만 한다. 같은 조직·같은 도메인이면 기존 사이트를 돌려주므로 몇 번 실행해도 안전하다.sites create는 중복이면 409 로 실패한다. sk_...(서버 API 키) 는 시크릿이다. 코드·커밋·프론트엔드 번들·로그에 남기지 말고 배포 플랫폼의 시크릿(예:wrangler secret put, Coolify 환경변수, Vercel env)에만 넣는다.ensure --json출력에 키가 들어 있으니 출력을 그대로 로그에 찍지 않는다.publicId(kdf_...) 는 공개값이다. 스크립트 태그에 그대로 넣어도 된다.- 사이트 삭제, 토큰 발급, 멤버 초대는 하지 않는다. 토큰으로는 애초에 할 수 없고, 사람이 할 일이다.
- 도메인은 실제 배포 도메인을 쓴다.
localhost는 트래커가 자동으로 수집하지 않는다.
인증
CLI kdf (Node 24+, 의존성 없음) 가 기본 인터페이스다.
kdf whoami # "이름 <이메일> · 역할" 과 서버 주소가 나오면 준비 완료
- 설치: 온길 저장소에서
npm install -g ./cli - 인증 정보는
~/.config/kdf/config.json또는 환경변수KDF_URL,KDF_TOKEN에서 읽는다. - 토큰이 없거나 401 이 나면 사람에게 조직 API 토큰을 요청한다.
사람은 대시보드
https://analytics.stonkradar.io/orgs→ 조직 → API 토큰에서sites:write를 포함해 발급한 뒤kdf login --token kpat_... --url https://analytics.stonkradar.io로 저장한다.
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"
}
}
created: false면 이미 있던 사이트다. 이때apiKey는keys:read스코프가 있을 때만 들어 있다. 결제 연동에 키가 필요한데 없으면 사람에게 대시보드의 사이트 → 연동 정보에서 복사해 달라고 요청한다.- 도메인은 정규화된다: 스킴이 없으면
https://, 호스트 소문자, 끝 슬래시 제거.www.는 별개 도메인으로 취급한다. - 사용자가 여러 조직에 속해 있으면
--org <orgId>가 필요하다 (kdf orgs로 확인). 토큰은 토큰의 조직이 자동 선택된다.
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> |
선택 속성:
data-track-params="user,tab"— 쿼리 파라미터로 페이지를 구분하는 사이트에서 지정한 파라미터만 경로에 포함data-allow-localhost— 로컬에서 수집을 시험할 때만 (배포본에는 넣지 않는다)
목표(전환) 이벤트
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-<속성> -->
- 속성 이름은 소문자·숫자·
_·-32자, 값은 문자열(숫자·불리언은 문자열로 바뀜) 255자, 최대 10개. 규칙에 맞지 않는 속성은 버려진다. - 속성은 여정·실시간 피드에
signup (plan=pro)처럼 붙어 보인다. 이메일·전화번호 같은 개인정보는 넣지 않는다.
결제 연동
트래커가 발급한 방문자 ID(window.kdatafast.visitorId)를 주문과 연결해 두면 결제 시 그 방문자의 최초 유입 채널에 매출이 귀속된다.
서버 API 는 모두 헤더 x-api-key: sk_... 가 필요하므로 반드시 서버에서 호출한다.
- 주문 생성 시 프론트에서
window.kdatafast?.visitorId를 받아 주문과 함께 저장한다. - 결제가 확정되는 서버 코드에서 한 번 보고한다 (매핑이 없으면 생성까지 한다):
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', // 선택
}),
});
- 환불(부분 취소 포함)은
POST https://analytics.stonkradar.io/api/payments/refund본문{ orderId, provider?, refundedAmount }.refundedAmount는 지금까지의 누적 환불액이다 (이번 환불액이 아님 — 재시도해도 두 번 빠지지 않는다). 매출은 결제 금액 − 누적 환불액으로 집계되고, 누적 환불액이 결제 금액 이상이면 결제 건수에서도 빠진다. - 결제 전에 매핑만 먼저 등록하려면
POST /api/payments/link(같은 본문,orderId·visitorId필수). 결제 화면을 여는 시점에 부르면 퍼널의payment_started(결제 시작) 단계가 되어, 결제하지 않고 나간 사람도 센다. 나중에paid를 부를 때orderId·provider를 같게 보내야 한 건으로 이어진다. - PG 웹훅으로 자동 연동도 된다: 포트원 V2
https://analytics.stonkradar.io/api/webhooks/portone/<publicId>, Stripehttps://analytics.stonkradar.io/api/webhooks/stripe/<publicId>(Stripe 는 Checkoutmetadata.kdf_visitor_id또는client_reference_id에 방문자 ID). - Stripe 결제 링크(
https://buy.stripe.com/...)는 코드를 고칠 필요가 없다. 링크를 누르는 순간 트래커가 방문자 ID 를client_reference_id로 붙인다 (이미 값이 있으면 건드리지 않는다). Stripe 웹훅만 등록하면 된다. JS 로location.href = 'https://buy.stripe.com/...'처럼 이동시키면 자동으로 붙지 않으니?client_reference_id=${window.kdatafast.visitorId}를 직접 붙인다. - 랜딩과 앱 도메인이 다르면 이동할 때
location.href = window.kdatafast.decorate(url)로 방문자를 이어 준다. 붙는 ID는 2분 뒤 만료되므로 페이지 로드 때 링크를 미리 바꿔 두지 말고 클릭 시점에 호출한다. 같은 등록 도메인의 서브도메인(www·app 등)끼리는 쿠키가 공유돼 decorate 가 필요 없다. 두 도메인이 같은publicId로 수집한다면 앱 쪽 도메인을 사이트의 추가 허용 도메인에 넣어야 한다 (kdf sites update <publicId> --allowed-hosts app.other-domain.com). 등록 도메인·그 하위 도메인이 아닌 곳에서 온 브라우저 수집은 '다른 도메인' 봇으로 분류돼 지표에서 빠진다 — 남의 사이트에 스크립트 태그가 복사돼도 숫자가 오염되지 않게 하려는 것이다. - 유입 채널은 출처(Naver Search, Threads …)와 그룹(검색·소셜·커뮤니티·AI·이메일·광고·링크·직접 유입)으로 자동 분류된다. 자기 도메인·서브도메인, 로그인·결제를 마치고 돌아온 레퍼러는 유입으로 치지 않는다.
전환 퍼널
방문자가 어디까지 오고 어디서 멈추는지 본다. 단계는 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
- 중간 단계가 페이지 이동 없이 일어나면(검색 결과 없음, 옵션 선택 등) 단계마다
goal()을 하나씩 보내 둔다.replaceState로만 URL 을 바꾸는 이동은 페이지뷰로 잡히지 않는다. - 목표 이름에는 이메일·주소·검색어처럼 사용자가 입력한 값을 넣지 않는다.
수집 확인
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