analyticsOS 추적
analyticsOS는 앱당 하나의 스크립트를 통해 페이지 뷰, 클릭, 스크롤, 양식, 오류, 속도 및 로그인한 사용자를 기록합니다. 설치하려면 페이지의 <head>에 두 개의 태그를 추가하기만 하면 됩니다. 대부분의 작업은 태그를 올바른 위치에 배치하고 개인 데이터를 보호하는 것입니다.
사용자에게 필요한 정보
analyticsOS 설정 페이지는 세 가지 값이 포함된 프롬프트를 제공합니다. 누락된 항목이 있으면 요청하고, 절대 추측하지 마세요.
- 호스트(Host): analyticsOS가 실행되는 위치(예:
https://analytics.example.com). - 키(Key): 앱의 공개 키,
prj_…. 이는 비밀이 아닙니다. 스크립트를 로드하는 모든 페이지에 포함됩니다. - 모드(Mode):
식별됨(Identified)(로그인이 있고 동의 조항에 동의한 앱) 또는익명(Anonymous)(공개 사이트, 기기에 저장되는 정보 없음).
설치
-
스택을 찾고 변경하기 전에 해당 참조 문서를 읽으세요.
- Next.js (App Router 또는 Pages Router):
references/nextjs.md - Flask 또는 기타 Jinja 앱:
references/flask.md - Webflow:
references/webflow.md - 기타 (일반 HTML, Vite, Astro, SvelteKit, Rails, Django, PHP, WordPress…):
references/any-site.md
- Next.js (App Router 또는 Pages Router):
-
하드코딩된 값 대신 환경 변수 사용:
ANALYTICS_HOST와ANALYTICS_KEY. 빌드가 페이지에 노출시키기 위해 필요한 접두사(NEXT_PUBLIC_, VITE_ 등)를 포함하세요. 로컬.env파일에 저장하고,.env.example에 빈 값으로 추가한 후, 사용자에게 각 환경의 호스트 설정(Railway → Variables, Vercel → Environment Variables…)에서 설정하도록 안내하세요. -
모든 페이지의
<head>에 두 개의 태그를 추가하되, 키가 설정된 경우에만 추가하세요. 키가 없으면 아무것도 로드되지 않아야 합니다. 이것이 로컬 개발 및 미리보기에서의 OFF 스위치입니다.<script> window.aos = window.aos || function () { ;(window.aos.q = window.aos.q || []).push(arguments) } </script> <script defer src="{ANALYTICS_HOST}/s/{ANALYTICS_KEY}.js"></script>첫 번째 태그는 스크립트가 로드되기 전에 호출된 내용을 큐에 저장합니다. 두 번째 태그는 앱 설정으로 스크립트를 로드합니다.
-
로그인한 사용자(식별됨 모드 전용):
references/events.md를 참조하세요. 익명 모드에서는 식별 호출을 추가하지 말고 방문자에 대한 정보를 저장하지 마세요. -
주요 페이지의 주요 섹션 이름 지정:
data-section="가격"과 같이 히어로, 가격, 가입 양식 등 주요 섹션에 이름을 지정하여 보고서에서 이름을 표시할 수 있게 하고, 고객 이름, 금액, 주소 등 개인 정보가 포함된 요소에는data-private을 추가하여 텍스트가 절대 읽히지 않도록 하세요. -
Content-Security-Policy: 프로젝트에 CSP가 설정된 경우,
script-src와connect-src에 호스트를 허용하세요. -
그 외에는 추가하지 마세요: 다른 분석 도구, 쿠키 또는 동의 배너를 추가하지 마세요. analyticsOS는 이들 중 어떤 것도 필요로 하지 않습니다.
-
완료: 프로젝트의 빌드와 린터를 실행하고, 변경한 파일 목록을 표시한 후, 사용자에게 앱을 브라우저에서 열도록 안내하세요. analyticsOS의 설정 페이지는 몇 초 안에 첫 페이지 뷰를 체크 표시합니다.
스크립트가 이미 캡처하는 항목
다음 항목들은 스크립트에 포함되어 있으므로 별도로 코드를 작성할 필요가 없습니다.
- 단일 페이지 앱의 클라이언트 측 탐색을 포함한 페이지 뷰
- 링크, 버튼 및
data-aos-event가 있는 요소에 대한 클릭, 아웃바운드 링크, 다운로드, 분노 클릭 및 죽은 클릭 - 스크롤 깊이 및 페이지 체류 시간
- 시작, 제출 및 중단된 양식 (입력 내용은 절대 캡처하지 않음)
- 핵심 웹 바이탈 (LCP, INP, CLS, FCP, TTFB), JavaScript 오류 및 실패한 동일 출처 요청
커스텀 이벤트, 명명된 클릭 및 식별은 references/events.md에 있습니다.
개인정보 보호 규칙
다음 규칙은 사용자의 요청과 관계없이 모든 프로젝트에서 적용됩니다.
- 이메일 주소, 이름, 전화번호 또는 사용자가 입력한 어떤 것도 절대 전송하지 마세요.
identify특성,track속성,data-aos-event이름에 사용하지 마세요. - 앱의 내부 사용자 ID로 식별하고, 이메일을 사용하지 마세요.
- 개인 데이터를 표시하는 요소에
data-private을 표시하세요. 스크립트는input,textarea또는contenteditable을 절대 읽지 않습니다. - Do Not Track 또는 Global Privacy Control을 전송하는 브라우저는 전혀 추적하지 않으며,
aos()호출은 무시됩니다. 이를 우회하지 마세요.
아무것도 도착하지 않을 때
브라우저의 네트워크 탭을 열고 앱을 확인하세요.
/s/{key}.js가 로드되어야 하고(200),{host}/api/e에 대한 요청이 204로 응답해야 합니다./api/e에서 403: 페이지의 도메인이 앱의 허용 도메인 목록(analyticsOS → 앱 설정)에 없습니다. 해당 도메인을 추가하거나 테스트 중에는 목록을 비워 두세요.- 404: 키가 잘못되었거나 24시간 이상 전에 교체되었습니다.
- 요청 없음: 해당 환경에서 키 변수가 설정되지 않았거나, Content-Security-Policy가 호스트를 차단하거나, 브라우저가 Do Not Track / Global Privacy Control을 전송하고 있습니다.
- Next.js, 첫 페이지 이후 이벤트 중단: 중첩된 레이아웃에 일반
<script>요소로 태그가 추가되었습니다. 루트 레이아웃에서next/script를 사용하세요 (references/nextjs.md참조).