---
title: "React 환경 태깅 가이드 (개발자용)"
url: https://logger.co.kr/console/manual-stt/console-install-react.html
category: "설치 및 문제 해결 > 분석스크립트"
last_modified: 2026-10-30
console_screen: "서비스 관리 > 분석 스크립트 (https://logger.co.kr/console/services)"
keywords: ["React", "리액트", "GTM", "구글 태그 매니저", "dataLayer", "History Change", "기록 변경", "맞춤 HTML", "_trk_clickTrace", "_trk_flashEnvView", "개발자"]
source: LOGGER 사용자 매뉴얼 (BizSpring LOGGER)
---

# React 환경 태깅 가이드 (개발자용)

> React 로 만든 웹사이트에 GTM(Google Tag Manager)을 이용해 로거 기본 스크립트와 환경변수(전환·상품·회원 등)를 태깅하는 방법과, GTM 없이 직접 설치할 때의 주의점을 개발자용으로 정리한 문서입니다.

## 해당 제품(서비스)

웹사이트 서비스 전체 에디션(레벨).

## 문서 정의

React 로 만든 웹사이트에 GTM(Google Tag Manager)을 이용해 로거 기본 스크립트와 환경변수(전환·상품·회원 등)를 태깅하는 방법과, GTM 없이 직접 설치할 때의 주의점을 개발자용으로 정리한 문서입니다.

## 가이드 내려받기

- React 환경 태깅 가이드 (개발자용, PDF): [내려받기](https://logger.co.kr/manager_FR/scriptDown/BizSpring_Logger_React_tagging-guide_ver.1.0.pdf)
- 로거 자료실 2108번 글: [「가이드 — 로거 React 환경 스크립트 태깅 가이드(개발자용)」](https://logger.co.kr/support_FR/board_setView.tsp?catCode=files&id=2108) (로거 로그인 후 열람)
- SPA 환경 태깅 가이드 v2.1 (React · Vue, PDF): [내려받기](https://logger.co.kr/manager_FR/scriptDown/BizSpring_Logger_tagging-script_manual_%5BSPA%5D_ver.2.1.pdf) — GTM 없이 직접 설치하는 최신 방법

## 사전 준비

- 로거 계정과 서비스번호(서비스를 만들 때 자동 발급)
- GTM 계정과 웹사이트용 컨테이너, 기본 GTM 스니펫 설치
- 웹사이트 소스 코드 접근·수정 권한
- React 에서 GTM 으로 값을 넘기는 dataLayer 객체 사용법

## 1. 기본 스크립트 설치 (GTM 맞춤 HTML 태그)

1. GTM 작업 공간 > 태그 > 새로 만들기 > 태그 구성 > 맞춤 HTML 을 고릅니다.
2. 아래 스크립트를 붙여 넣고 「서비스번호」를 발급받은 서비스번호로 바꿉니다.
3. 태그 이름을 정해(예: HTML - Logger Base Script) 저장합니다.

```
<script id="pre_서비스번호_script">
  // 라우팅마다 다시 실행되도록 이전에 삽입된 로거 요소를 먼저 지운다
  ["logger_서비스번호_tracker_id", "logger_서비스번호_tracking_script",
   "logger_서비스번호_noscript_tracker", "pre_서비스번호_script"].forEach(function (id) {
    var el = document.getElementById(id); if (el) el.remove();
  });
  var old = document.querySelector('script[src="//fs.bizspring.net/fs4/bstrk.1.js"]'); if (old) old.remove();
</script>
<script id="logger_서비스번호_tracker_id" type="text/javascript">
  var _TRK_LID = "서비스번호";
  var _L_TD = "ssl.logger.co.kr";
  var _TRK_CDMN = "";
</script>
<script id="logger_서비스번호_tracking_script" type="text/javascript">
  if (typeof(_BSTRK_LOADED) != 'undefined') { _BSTRK_LOADED = undefined; }
  (function (b, s) {
    var f = b.getElementsByTagName(s)[0], j = b.createElement(s);
    j.async = true; j.src = "//fs.bizspring.net/fs4/bstrk.1.js";
    f.parentNode.insertBefore(j, f);
  })(document, "script");
</script>
<noscript id="logger_서비스번호_noscript_tracker">
  <img alt="Logger Script" width="1" height="1" src="//ssl.logger.co.kr/tracker.1.tsp?u=서비스번호&amp;js=N" />
</noscript>
```

원본 가이드는 기존에 삽입된 요소를 하나씩 지우는 형태로 작성되어 있으며, 위 코드는 같은 동작을 줄여 쓴 것입니다. 핵심은 이전 요소를 지우고 _BSTRK_LOADED 를 초기화한 뒤 bstrk.1.js 를 다시 불러오는 것입니다.

## 2. 트리거 설정 (History Change)

1. 변수 > 기본 제공 변수 > 구성에서 [페이지](Page URL·Page Hostname·Page Path)와 [기록](History Source, New History Fragment, New History State, Old History Fragment, Old History State)을 모두 켭니다.
2. 트리거 > 새로 만들기 > 기록 변경 > 모든 기록 변경 으로 트리거를 만듭니다(예: History Change - Page View).
3. 기본 스크립트 태그에 **History Change - Page View 와 All Pages 를 함께** 연결합니다. 초기 로드는 All Pages, 이후 화면 이동은 기록 변경이 담당합니다.
4. 컨테이너를 게시하면 초기 로드와 가상 페이지뷰가 모두 로거로 전송됩니다.

모든 SPA 구조에서 기록 변경 트리거가 동작하지는 않습니다. 미리보기 모드에서 동작을 확인하고, 동작하지 않으면 dataLayer 맞춤 이벤트로 페이지뷰를 보내도록 구성합니다.

## 3. 환경변수 전달 (React → dataLayer → GTM)

버튼 클릭·회원가입 완료·구매 완료 같은 행동은 React 컴포넌트에서 window.dataLayer.push() 로 GTM 에 값을 넘기고, GTM 에서 로거 환경변수로 옮겨 전송합니다. 환경변수는 값이 필요한 화면에만 선별적으로 보냅니다.

```
// 상품 상세 — 상품 정보가 준비되면 전송
useEffect(() => {
  if (!product) return;
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'loggerProductView',   // GTM 맞춤 이벤트 이름
    loggerPI: 'PDV',              // → _TRK_PI
    loggerPN: product.productId,  // → _TRK_PN
    loggerPND: product.productName // → _TRK_PND
  });
}, [product]);

// 주문 완료 — 여러 상품은 세미콜론(;)으로 이어서
window.dataLayer.push({
  event: 'loggerOrderResult',
  loggerPI: 'ODR',
  loggerOA: items.map(i => i.price * i.quantity).join(';'),
  loggerOE: items.map(i => i.quantity).join(';'),
  loggerOP: items.map(i => i.productId).join(';'),
});
```

## 4. GTM 변수·트리거·태그 설정

1. **데이터 영역 변수**: 변수 > 새로 만들기 > 데이터 영역 변수. 이름에 dataLayer 키(예: loggerPI)를 넣고 버전 2 를 고릅니다. 보내는 키마다 만듭니다.
2. **맞춤 이벤트 트리거**: 트리거 > 새로 만들기 > 맞춤 이벤트. 이벤트 이름에 dataLayer 의 event 값(예: loggerProductView)을 넣습니다. 이벤트마다 만듭니다.
3. **이벤트 전송 태그**: 맞춤 HTML 태그에 아래처럼 로거 환경변수를 설정하고, 해당 맞춤 이벤트 트리거에 연결합니다. 이벤트에 필요한 변수만 넣습니다.

```
<script type="text/javascript">
  _TRK_PI = "{{loggerPI}}";
  _TRK_OA = "{{loggerOA}}";
  _TRK_OE = "{{loggerOE}}";
  _TRK_OP = "{{loggerOP}}";
  // 값이 있을 때만 설정하려면: if ("{{loggerPI}}" && "{{loggerPI}}" !== "undefined") _TRK_PI = "{{loggerPI}}";
</script>
```

{{ }} 안에는 실제로 만든 데이터 영역 변수 이름을 넣고, 중괄호 안에 따옴표를 넣지 않습니다(_TRK_SX = "{{loggerSX}}"; 가 올바른 표기).

## 5. 주요 환경변수 대응표

| 로거 변수 | dataLayer 키(예) | 설명 |
| --- | --- | --- |
| _TRK_PI | loggerPI | 화면 성격·전환 유형(예: ODR 주문 완료, PDV 상품 상세, RGR 회원가입 결과, RES 문의 완료) |
| _TRK_PN / _TRK_PND | loggerPN / loggerPND | 상품 코드 / 상품명 |
| _TRK_OA / _TRK_OE / _TRK_OP | loggerOA / loggerOE / loggerOP | 상품별 주문 금액 / 수량 / 상품 코드(여러 상품은 ; 구분) |
| _TRK_CP | loggerCP | 페이지 카테고리(예: /회사소개/제휴안내) |
| _TRK_MF | loggerMF | 상품 브랜드(제조사)명 |
| _TRK_SX / _TRK_AG | loggerSX / loggerAG | 회원 성별 / 회원 특성 |
| _TRK_IK | loggerIK | 내부 검색어 |

원본 가이드에는 회원가입수·상담신청수·버튼 클릭 전환·인기 콘텐츠·회원 특성·내부 검색어·특정 링크 클릭·이동경로 시나리오 측정의 React 예시 코드가 모두 실려 있습니다. 변수별 상세 의미는 [환경변수 스크립트](https://logger.co.kr/console/manual/202) 이하 문서를 참고해 주십시오.

## 6. 버튼 클릭 측정

장바구니 담기처럼 클릭 자체를 측정할 때는 로거의 _trk_clickTrace() 를 직접 호출합니다. 인자는 클릭 유형(EVT 링크 클릭, DNL 다운로드, RFO 외부 사이트 연결, SCI 장바구니 담기, SCO 장바구니 삭제)과 대상 값입니다.

```
const handleAddToCart = () => {
  try {
    if (typeof _trk_clickTrace === 'function') _trk_clickTrace('SCI', productId);
  } catch (e) { console.error('Logger clickTrace error:', e); }
  // 실제 장바구니 로직
};
```

## 7. 테스트 및 디버깅

1. GTM 미리보기 모드로 사이트에 접속합니다.
2. Tag Assistant 에서 화면을 이동할 때 History 이벤트와 로거 기본 스크립트 태그가 실행되는지 확인합니다.
3. 버튼 클릭 등 이벤트를 발생시켜 event 이름이 이벤트 목록에 나타나고, 연결한 로거 이벤트 태그가 Tags Fired 에 표시되는지 확인합니다.
4. 실행된 태그의 Variables 탭에서 데이터 영역 변수 값이 React 에서 보낸 값으로 채워졌는지, Data Layer 탭에서 전송 구조를 확인합니다.
5. 리포트의 [데이터검증 TOOL™]에서 페이지뷰와 이벤트가 수집되는지 확인합니다. 모든 GTM 변경은 제출·게시해야 실제 사이트에 적용됩니다.

## 8. GTM 없이 직접 설치할 때

- **재실행 제한**: bstrk.1.js 는 window._BSTRK_LOADED 가 없을 때만 실행되므로, 라우팅이 바뀔 때마다 _BSTRK_LOADED 를 undefined 로 초기화하고 스크립트를 다시 삽입해야 합니다.
- **실행 순서**: 완료 페이지가 있으면 환경변수가 기본 스크립트보다 먼저 설정되어야 합니다. 완료 페이지가 없는 버튼 클릭·비동기 응답은 그 시점에 전환을 보냅니다.
- 직접 설치 코드는 useLocation() 구독 누락 등 실수를 바로잡은 [SPA 환경 분석스크립트 설치](https://logger.co.kr/console/manual-stt/console-install-spa.md.txt)의 「React에서 설치할 때」 코드를 사용해 주십시오. 이 문서 원본(PDF)의 직접 설치 예시는 이전 판이므로 SPA 가이드 v2.1을 기준으로 합니다.

## 유의사항

- 이 가이드는 일반적인 React + GTM 구성을 기준으로 합니다. 데이터 구조와 전송 방식은 사이트 구현에 따라 달라질 수 있으므로 미리보기 모드와 데이터검증 TOOL™ 로 반드시 확인합니다.
- 주문 금액 등 숫자 값은 문자열로 넘기는 편이 안전합니다(String(...)).
- GTM 태깅 지원·설치 대행이 필요하면 service@logger.co.kr 로 문의해 주십시오.

## 함께 보면 좋은 문서

- [SPA 환경 분석스크립트 설치 (React · Vue)](https://logger.co.kr/console/manual-stt/console-install-spa.md.txt)
- [환경변수 스크립트](https://logger.co.kr/console/manual/202)