리액트(React) 환경에서 GA4 데이터 수집 안 됨 및 디버그 모드 설정(GA4 React Tracking)

by꿈꾸는자 -
0

리액트(React)와 같은 싱글 페이지 애플리케이션(SPA) 환경에서 구글 애널리틱스 4(GA4)를 구축하다 보면, 분명히 추적 코드를 심었는데도 실시간 보고서에 데이터가 잡히지 않거나 페이지 전환이 추적되지 않는 고질적인 문제를 겪게 됩니다. 일반적인 정적 웹사이트와 달리 리액트는 브라우저의 URL은 바뀌지만 실제 페이지 로딩은 일어나지 않기 때문에 발생하는 현상입니다.

이 포스팅에서는 리액트의 생명주기와 라우팅 시스템을 고려하여 GA4 데이터를 정확하게 수집하는 기술적 방법과, 데이터가 서버로 잘 전송되고 있는지 실시간으로 검증할 수 있는 디버그 모드(DebugView) 설정법을 심도 있게 다룹니다. 마케팅 지표의 신뢰도를 높이고 싶은 프론트엔드 개발자라면 반드시 체크해야 할 필수 가이드입니다.

React GA4 트래킹 핵심 요약 가이드
1. react-ga4 라이브러리를 사용하여 초기화(initialize)를 수행해야 합니다.
2. useEffect와 useLocation 훅을 결합해 가상 페이지뷰(Virtual Pageview)를 전송하세요.
3. 크롬 확장 프로그램 GA Debugger를 활성화하여 실시간 전송 상태를 확인하세요.
4. GA4 콘솔의 DebugView 메뉴에서 데이터 수집 여부를 최종 검증합니다.

원인 분석

리액트 앱에서 데이터 수집이 누락되는 대표적인 기술적 이유는 다음과 같습니다.

  • SPA의 비연속성: 리액트 라우터(React Router)를 통한 페이지 이동은 브라우저의 '새로고침'을 동반하지 않습니다. 따라서 기본 GA4 스크립트는 최초 접속 시에만 실행되고 이후의 이동은 인식하지 못합니다.
  • 초기화 시점 오류: index.js나 App.js 외부에서 초기화 코드가 실행되거나, 컴포넌트 마운트 전에 이벤트를 전송하려고 할 때 오류가 발생합니다.
  • 광고 차단 도구(AdBlock): 개발 환경이나 사용자 브라우저에 설치된 광고 차단 확장 프로그램이 GA4 스크립트의 로딩을 차단하는 경우입니다.
  • 측정 ID(Measurement ID) 누락: 환경 변수(env) 설정 과정에서 G-XXXXXXXXXX 형식이 누락되었거나 오타가 있는 경우입니다.

해결 방법

1. react-ga4 라이브러리 설치 및 초기화

가장 먼저 리액트 전용 GA4 라이브러리를 설치하여 환경을 구축합니다. 기존의 react-ga는 이전 버전인 UA용이므로 반드시 최신 라이브러리를 사용해야 합니다.

npm install react-ga4

이후 App.js나 최상위 컴포넌트에서 초기화를 진행합니다.

import ReactGA from "react-ga4";

const GA_TRACKING_ID = "G-XXXXXXXXXX"; // 본인의 측정 ID 입력
ReactGA.initialize(GA_TRACKING_ID);

2. useLocation을 활용한 페이지뷰 추적 자동화

리액트 라우터를 사용 중이라면 URL 변경을 감지하여 수동으로 페이지뷰를 전송해야 합니다. 별도의 컴포넌트를 만들어 모든 페이지 변화를 추적하게 설정합니다.

import { useEffect } from "react";
import { useLocation } from "react-router-dom";
import ReactGA from "react-ga4";

const RouteChangeTracker = () => {
  const location = useLocation();

  useEffect(() => {
    // 현재 경로를 GA4로 전송
    ReactGA.send({
      hitType: "pageview",
      page: location.pathname + location.search,
    });
  }, [location]);

  return null;
};

export default RouteChangeTracker;

이 컴포넌트를 BrowserRouter 내부 상단에 배치하면 모든 라우팅 경로를 정확하게 수집할 수 있습니다.

3. GA4 DebugView 활성화 및 검증

코드를 작성한 후 데이터가 실제로 전송되는지 확인해야 합니다. GA4의 '관리 > DebugView' 메뉴를 활용하세요.

  1. 크롬 웹스토어에서 Google Analytics Debugger 확장 프로그램을 설치하고 활성화합니다.
  2. 개발 중인 리액트 사이트에 접속하여 페이지를 클릭하거나 이동합니다.
  3. GA4 속성 설정의 DebugView 탭으로 이동하여 내 기기의 활동이 타임라인에 실시간으로 찍히는지 확인합니다.

그래도 해결되지 않을 때

만약 데이터가 여전히 보이지 않는다면, Content Security Policy(CSP) 설정을 확인해야 합니다. 보안 정책이 www.google-analytics.com 도메인으로의 데이터 전송을 차단하고 있을 수 있습니다. 브라우저 개발자 도구(F12)의 'Console' 탭에서 Refused to connect...와 같은 에러 메시지가 있는지 확인해 보세요.

문제 예방 방법

  • 환경 변수 사용: 개발 서버(Localhost)와 운영 서버의 트래픽을 분리하기 위해 .env 파일에 측정 ID를 관리하고, 개발 환경에서는 GA를 비활성화하는 조건을 추가하세요.
  • 커스텀 이벤트 관리: 버튼 클릭이나 폼 제출 등 중요한 사용자 행동은 ReactGA.event()를 통해 별도로 트래킹하여 단순 페이지뷰 이상의 데이터를 확보하세요.
  • Strict Mode 확인: React 18의 Strict Mode에서는 useEffect가 두 번 실행되어 데이터가 중복 수집될 수 있으므로, 초기화 로직이 중복 실행되지 않게 플래그 처리를 고려하세요.

FAQ

Q. 로컬호스트(localhost)에서도 데이터가 수집되나요?

A. 네, 기본적으로 수집됩니다. 하지만 정확한 통계를 위해 필터 설정을 통해 개발 트래픽을 제외하거나, 디버그 모드에서만 작동하게 하는 것이 좋습니다.

Q. 이벤트를 보냈는데 실시간 보고서에 바로 안 떠요.

A. GA4의 일반 보고서는 데이터 반영에 최대 24~48시간이 걸립니다. 즉각적인 확인은 반드시 실시간(Real-time) 보고서 또는 DebugView를 사용해야 합니다.

마무리 요약

리액트 환경에서 GA4 데이터 수집 문제는 SPA의 라우팅 특성을 이해하고 가상 페이지뷰를 수동으로 전송함으로써 대부분 해결됩니다. react-ga4 라이브러리를 통해 초기화하고, useLocation 훅으로 경로 변경을 추적하며, 마지막으로 DebugView로 최종 검증하는 3단계 프로세스를 잊지 마세요. 이제 정확한 데이터 분석을 기반으로 웹 서비스를 성장시킬 준비가 되었습니다!

Tags

관심 있을 만한 글

댓글 쓰기

다음 이전