React · Vue SPA 환경의 웹로그 분석 설치: 가상 페이지뷰로 데이터 누락 막기

    갱신일 2026. 11. 16. · 작성 비즈스프링 LOGGER팀

    SPA(Single Page Application)는 화면을 이동해도 문서 전체를 다시 불러오지 않으므로, 일반 웹사이트처럼 공통 영역에 분석 스크립트만 넣으면 첫 화면만 집계되고 이후 화면 이동은 누락됩니다. LOGGER는 라우팅이 바뀔 때마다 스크립트를 다시 실행해 페이지뷰를 1건씩 전송하는 가상 페이지뷰 방식을 「SPA 환경 태깅 가이드 v2.1」로 제공합니다. 설치 뒤에는 데이터검증 TOOL로 이동마다 페이지뷰가 1건씩 늘고 첫 화면이 2건으로 집계되지 않는지 확인합니다.

    SPA에서 페이지뷰가 누락되는 이유

    React · Vue 같은 프레임워크로 만든 SPA는 첫 페이지를 불러온 뒤 전체 페이지를 새로 불러오지 않고 필요한 화면 부분만 바꿉니다. 웹분석 스크립트는 대개 문서를 불러올 때 한 번 실행되므로, 일반 웹사이트처럼 공통 영역(푸터)에 스크립트를 넣으면 첫 진입 화면만 집계됩니다. 방문자가 메뉴를 정상적으로 이동해도 그 이동이 수집되지 않아 페이지뷰, 이동 경로, 전환 단계가 실제보다 적게 나타납니다. 이는 스크립트 태깅 방식의 웹분석 도구에 공통으로 나타나는 현상입니다.

    일반 웹사이트와 SPA의 스크립트 동작 차이
    구분일반 웹사이트SPA(React · Vue)
    화면 이동 방식페이지마다 문서를 새로 불러옵니다문서는 그대로 두고 화면 부분만 바꿉니다
    분석 스크립트 실행페이지를 열 때마다 실행됩니다첫 진입 때 한 번만 실행됩니다
    기본 설치 결과모든 페이지뷰가 집계됩니다첫 화면만 집계되고 이후 이동은 누락됩니다
    필요한 처리공통 영역에 기본 스크립트 설치라우팅마다 가상 페이지뷰 전송

    설치 원리: 반드시 처리할 네 가지

    SPA에서 따로 처리할 항목(LOGGER 매뉴얼 「SPA 환경 분석스크립트 설치」 기준)
    구분발생하는 문제처리 방법
    1회만 실행bstrk.1.js는 window._BSTRK_LOADED가 없을 때만 동작하므로 이후 라우팅에서는 아무 일도 일어나지 않습니다.라우팅마다 _BSTRK_LOADED를 undefined로 초기화하고 추적 스크립트를 다시 삽입합니다(가상 페이지뷰).
    첫 화면 중복 집계스크립트는 로드 즉시 페이지뷰 1건을 전송하는데, 라우터 훅도 최초 진입에 실행됩니다.라우터 훅에서 최초 이동 1건은 건너뜁니다.
    환경변수 순서완료 화면의 전환 정보(_TRK_PI 등)는 스크립트 로드 시점에 설정되어 있어야 수집됩니다.window 환경변수를 먼저 설정한 뒤 스크립트를 다시 삽입합니다.
    비동기 로딩스크립트가 로드되기 전에 발생한 전환 호출은 버려집니다.로드 전 호출을 보관했다가 순서대로 실행하는 호출 큐를 둡니다.
    라우팅이 바뀔 때 가상 페이지뷰가 전송되는 순서
    1. 단계 1
      라우팅 변경
      afterEach · useLocation
    2. 단계 2
      최초 이동 여부 확인
      최초 1건은 건너뜀
    3. 단계 3
      _BSTRK_LOADED 초기화
      undefined로 설정
    4. 단계 4
      bstrk.1.js 재삽입
      이전 스크립트 제거 후 삽입
    5. 단계 5
      페이지뷰 1건 전송
      새 경로와 제목으로 집계

    bstrk.1.js에는 가상 페이지뷰를 보내는 공개 함수와 공식 커맨드 큐가 없습니다. 매뉴얼은 스크립트 재삽입과 자체 호출 큐 구현을 현재의 방법으로 안내하며, 실데이터 수집 시험에서 세션 연속성이 정상으로 확인되었다고 밝히고 있습니다.

    설치 단계: Vue · React

    파일별 역할(Vue 3 + Vue Router 4 기준, React도 같은 모듈 사용)
    파일역할
    index.html전역 설정 변수(_TRK_LID 등)와 noscript 이미지만 둡니다. 추적 스크립트 자체는 넣지 않습니다.
    src/analytics/logger.js스크립트 로딩, 호출 큐, 가상 페이지뷰 전송, 전환 전송 함수를 모은 모듈입니다.
    src/router/index.js라우터 훅(afterEach)을 등록합니다.
    src/main.js라우터가 준비된 뒤 로거를 로드합니다.
    각 화면 컴포넌트전환이 필요한 화면에서만 전환 전송 함수를 호출합니다.
    1. 1

      전역 설정 변수 선언

      index.html에 서비스번호를 넣은 전역 설정 블록과 noscript 이미지를 둡니다. 서비스번호는 콘솔 「서비스 관리 > 분석 스크립트」에서 확인합니다. noscript 이미지 주소는 https 사이트에서 차단되지 않도록 프로토콜 상대 경로(//)로 씁니다.

    2. 2

      로거 모듈 추가

      추적 스크립트를 모듈에서 동적으로 불러오고, 로드 전 호출을 보관하는 큐와 가상 페이지뷰 · 전환 전송 함수를 구현합니다.

    3. 3

      라우터 연결

      Vue는 router.afterEach()에서, React는 Router 안에 한 번 배치한 컴포넌트에서 경로 변화를 구독해 가상 페이지뷰를 보냅니다. 최초 이동 1건은 건너뜁니다.

    4. 4

      로드 시점 조정

      라우터가 준비된 뒤(router.isReady()) 로거를 로드해 최초 페이지뷰가 확정된 경로로 전송되도록 합니다.

    5. 5

      전환 연결

      주문완료 · 신청완료 같은 완료 지점에서 전환 전송 함수를 호출합니다.

    GTM을 사용하는 경우

    • 태그: 맞춤 HTML 태그에 LOGGER 기본 스크립트를 넣고 서비스번호를 바꿉니다. 이전에 삽입된 로거 요소를 지우고 _BSTRK_LOADED를 초기화한 뒤 bstrk.1.js를 다시 불러오는 구조입니다.
    • 트리거: All Pages와 기록 변경(History Change) 두 개를 함께 연결합니다. 초기 로드는 All Pages가, 이후 라우팅은 기록 변경이 담당합니다. 기본 제공 변수의 [기록] 항목을 모두 켭니다.
    • 모든 SPA 구조에서 기록 변경 트리거가 동작하지는 않습니다. 미리보기 모드에서 확인하고, 동작하지 않으면 dataLayer 맞춤 이벤트로 대체합니다.
    • 전환은 애플리케이션에서 dataLayer.push()로 이벤트와 값을 보내고, 맞춤 이벤트 트리거에 연결한 맞춤 HTML 태그에서 _TRK_PI 등 환경변수를 설정합니다.

    CTS(기여 및 전환 분석) 서비스의 스크립트는 커맨드 큐를 내장하고 있어 큐를 따로 만들 필요가 없습니다. 라우팅마다 _tcts_m(서비스번호, 매체코드)를 호출하면 되며, LOGGER와 CTS를 함께 쓰는 사이트는 「CTS SPA 환경 태깅 가이드 v1.0」을 함께 참고합니다.

    전환 전송과 설치 후 검증

    주요 환경변수와 _TRK_PI 코드(LOGGER 매뉴얼 기준)
    변수용도예시 · 비고
    _TRK_PI웹페이지 성격 · 전환 유형RGR 회원가입 결과, LIR 로그인 결과, PDV 상품 상세, ODF 주문 입력, ODR 주문 완료, RES 문의 완료
    _TRK_PN · _TRK_PND상품(항목) 코드 · 상품(항목) 명상품 상세 화면
    _TRK_OA · _TRK_OE · _TRK_OP주문 금액 · 수량 · 상품 코드여러 항목은 세미콜론(;)으로 구분
    _TRK_CP카테고리예: /회사소개/제휴안내/
    _TRK_IK내부 검색어사이트 안 검색 결과 화면
    • 완료 화면이 별도 라우트이면 화면이 표시된 뒤(onMounted · useEffect) 전환 전송 함수를 호출합니다. 같은 라우팅의 페이지뷰는 한 번만 전송되도록 처리합니다.
    • 완료 화면 없이 응답만 받는 경우(버튼 클릭, fetch 응답)는 응답이 성공한 시점에 호출합니다. 실패하거나 저장하기 전에는 호출하지 않습니다.
    • 링크 · 버튼 클릭은 _trk_clickTrace(유형, 이름)로 보냅니다. 유형은 EVT(링크 클릭), DNL(다운로드), RFO(외부 사이트 연결), SCI(장바구니 담기), SCO(장바구니 삭제)입니다.
    1. 1

      검증 준비

      시크릿 모드를 쓰거나 쿠키를 지운 뒤, 리포트의 [데이터검증 TOOL]에서 대상 사이트를 고르고 [조회]를 누릅니다. 이 도구는 본인 IP에서만 실시간 검증할 수 있습니다.

    2. 2

      페이지뷰 확인

      첫 진입 1건이 기록되는지, 메뉴를 이동할 때마다 페이지뷰가 1건씩 늘어나는지, 첫 화면이 2건으로 중복 집계되지 않는지 확인합니다.

    3. 3

      전환 확인

      전환이 완료될 때 _TRK_PI 값이 의도한 코드로 들어오는지 확인합니다.

    4. 4

      표시되지 않을 때

      스크립트 설치 상태와 [분석제외 IP] 등록 여부를 확인합니다. History Mode 사이트는 서버가 모든 경로를 index.html로 응답하도록 rewrite가 설정되어 있는지도 확인합니다.

    자주 묻는 질문

    Q. SPA 사이트에서 첫 화면만 집계되는 이유는 무엇인가요?

    SPA는 화면을 이동해도 문서를 다시 불러오지 않아 분석 스크립트가 첫 진입 때 한 번만 실행되기 때문입니다. 라우팅마다 _BSTRK_LOADED를 초기화하고 스크립트를 다시 삽입하는 가상 페이지뷰 방식으로 설치해야 합니다.

    Q. GTM으로 설치하는 방법과 코드에 직접 설치하는 방법 중 무엇이 낫나요?

    이미 GTM을 운영한다면 All Pages와 기록 변경 트리거로 설치할 수 있습니다. 다만 모든 SPA 구조에서 기록 변경 트리거가 동작하지는 않으므로, 미리보기에서 확인되지 않으면 코드에 직접 설치하는 최신 가이드(v2.1) 방식을 권장합니다.

    Q. Nuxt 같은 SSR 환경에서는 무엇을 주의해야 하나요?

    로거 스크립트가 서버에서 실행되지 않도록 클라이언트 전용 플러그인으로 분리하고, 라우팅 훅도 클라이언트에서만 등록합니다. 전환 호출은 화면이 표시된 이후(onMounted)에 둡니다.

    Q. 주소로 직접 들어오면 404가 표시되고 페이지뷰가 집계되지 않습니다.

    History Mode SPA는 서버가 모든 경로를 index.html로 응답하도록 rewrite를 설정해야 합니다(예: Nginx try_files $uri $uri/ /index.html;). 설정이 없으면 직접 접속한 경로에서 404가 발생하고 그 페이지뷰가 수집되지 않습니다.

    FAQ 100개 전체 보기

    참고 자료

    LOGGER로 직접 확인해 보십시오

    14일 무료체험을 제공하며, 기본 스크립트 설치를 무상으로 대행합니다.