# 온길 — 에이전트 연동 가이드 > 온길(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. 모든 페이지 `` 에 트래킹 스크립트 삽입 ([스크립트 설치](#스크립트-설치)) 4. (결제가 있으면) 서버에 결제 보고 연동, `sk_` 키는 시크릿 저장소에만 ([결제 연동](#결제-연동)) 5. 배포 후 `kdf overview --days 1` 로 수집 확인 ## 지켜야 할 규칙 - **등록은 `ensure` 로만 한다.** 같은 조직·같은 도메인이면 기존 사이트를 돌려주므로 몇 번 실행해도 안전하다. `sites create` 는 중복이면 409 로 실패한다. - **`sk_...` (서버 API 키) 는 시크릿이다.** 코드·커밋·프론트엔드 번들·로그에 남기지 말고 배포 플랫폼의 시크릿(예: `wrangler secret put`, Coolify 환경변수, Vercel env)에만 넣는다. `ensure --json` 출력에 키가 들어 있으니 출력을 그대로 로그에 찍지 않는다. - **`publicId` (`kdf_...`) 는 공개값이다.** 스크립트 태그에 그대로 넣어도 된다. - **사이트 삭제, 토큰 발급, 멤버 초대는 하지 않는다.** 토큰으로는 애초에 할 수 없고, 사람이 할 일이다. - 도메인은 실제 배포 도메인을 쓴다. `localhost` 는 트래커가 자동으로 수집하지 않는다. ## 인증 CLI `kdf` (Node 24+, 의존성 없음) 가 기본 인터페이스다. ```bash 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_` 키 조회 (새로 만든 사이트의 키는 이 스코프 없이도 생성 응답에 온다) | ## 사이트 등록 ```bash kdf sites ensure "내 프로젝트" my-project.com --json ``` ```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 ` 가 필요하다 (`kdf orgs` 로 확인). 토큰은 토큰의 조직이 자동 선택된다. CLI 를 쓸 수 없으면 REST 로 같은 일을 한다: ```bash 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"}' ``` ## 스크립트 설치 모든 페이지의 `` 에 한 줄. SPA 라우팅(pushState/popstate)은 자동 추적된다. ```html ``` | 프레임워크 | 넣는 곳 | |---|---| | 정적 HTML · Vite · CRA | `index.html` 의 `` | | Next.js App Router | `app/layout.tsx` 의 `` 에 `next/script` (`strategy="afterInteractive"`, `data-site` 속성 그대로) | | Next.js Pages Router | `pages/_document.tsx` 의 `` 에 일반 `