Logo
The Bason

[GA4] "왜 과거 데이터에 매개변수가 안 보이지?" 노가다 없는 API 일괄 등록 자동화 (Node.js/TS)

좋은 기술이나 삽질 해결법을 찾았을 때 바로 개발 블로그 써두는 게 국룰이죠! 개발자분들이 딱 좋아할 만한 깔끔하고 핵심 위주의 기술 블로그 포맷으로 짜왔습니다.

kaen
kaenJuly 25, 2026 · 2 views

좋은 기술이나 삽질 해결법을 찾았을 때 바로 개발 블로그 써두는 게 국룰이죠! 개발자분들이 딱 좋아할 만한 깔끔하고 핵심 위주의 기술 블로그 포맷으로 짜왔습니다.

이대로 복사해서 벨로그(velog)나 티스토리, 개인 블로그(Hexo/Next.js)에 마크다운으로 슥 올리시면 됩니다. 🚀

Markdown

## [GA4] "왜 과거 데이터에 매개변수가 안 보이지?" 노가다 없는 API 일괄 등록 자동화 (Node.js/TS)

구글 애널리틱스(GA4)로 이벤트를 심고 심혈을 기울여 데이터를 쌓았는데, 막상 탐색(Explore) 보고서에서 파라미터(Parameter)를 보려고 하니 **최근 30분(실시간) 데이터만 보이고 과거 데이터는 통째로 날아간 것처럼 안 보이는 현상**을 겪으신 분들이 많을 겁니다.

결론부터 말하면 GA4는 코드로 아무리 매개변수를 쏴줘도, **어드민 페이지에서 "이 매개변수 쓸 거니까 등록해 줘"라고 맞춤 측정기준(Custom Dimension)을 매핑해주지 않으면 과거 데이터용으로 저장하지 않고 버립니다.** (심지어 등록 전 데이터는 소급 적용도 안 됩니다... 🤦‍♂️)

게다가 최악인 건, **이벤트 하나에 파라미터가 5개 붙어있으면 UI에서 노가다로 5번을 따로 등록해야 합니다.** 개발자로서 이런 단순 반복 노가다는 참을 수 없죠.

GCP와 GA4 Admin API를 활용해 이 작업을 **Node.js(TypeScript) 스크립트 한 방으로 일괄 자동화하는 방법**을 공유합니다.

---

### 1. 사전 작업 (GCP & GA4 권한 세팅)

스크립트를 돌리기 전 구글 API를 호출할 수 있는 권한 작업이 필요합니다.

1. **GCP 콘솔 가기:** Google Cloud Console에 접속합니다.
2. **API 활성화:** 프로젝트를 선택하고 `Google Analytics Admin API`를 검색해 **[사용]** 버튼을 누릅니다.
3. **서비스 계정 생성:** `IAM 및 관리자` -> `서비스 계정`에서 봇 계정을 하나 생성하고, **JSON 타입의 키(Key)**를 생성해 다운로드합니다. (파일명: `credentials.json`)
4. **GA4 권한 부여:** 다운로드한 JSON 파일 안에 있는 `client_email` 주소를 복사합니다. 그 후 GA4 어드민 페이지의 `속성 액세스 관리`로 이동해 이 이메일을 **[편집자(Editor)]** 권한으로 추가해 줍니다.

---

### 2. 프로젝트 세팅 & 패키지 설치

구글에서 공식 제공하는 GA4 어드민 라이브러리를 설치합니다.

```bash
npm install @google-analytics/admin
# 또는
yarn add @google-analytics/admin

3. 일괄 등록 자동화 스크립트 작성

이제 등록해야 할 파라미터들을 배열로 쭉 말아서 한 번에 API로 쏴버리는 코드입니다.

TypeScript

import { AnalyticsAdminServiceClient } from '@google-analytics/admin';

// 1. 클라이언트 초기화 (다운로드한 GCP 인증 JSON 파일 경로)
const analyticsAdminClient = new AnalyticsAdminServiceClient({
  keyFilename: './credentials.json',
});

// 본인의 GA4 속성 ID (GA4 설정 -> 속성 세부정보에서 확인 가능)
const propertyId = 'YOUR_GA4_PROPERTY_ID';

// 2. 귀찮게 UI에서 하나씩 등록할 파라미터들을 배열로 리스트업!
const parametersToRegister = [
  { parameterName: 'keyword', displayName: '검색어' },
  { parameterName: 'category', displayName: '검색 카테고리' },
  { parameterName: 'user_level', displayName: '유저 등급' },
  { parameterName: 'skin_type', displayName: '피부 타입' },
  { parameterName: 'brand_filter', displayName: '선택 브랜드' }
];

async function createCustomDimensions(){
  console.log('🚀 GA4 맞춤 측정기준 일괄 등록 시작...');

  for (const param of parametersToRegister) {
    try {
      const [response] = await analyticsAdminClient.createCustomDimension({
        parent: `properties/${propertyId}`,
        customDimension: {
          parameterName: param.parameterName,  // 코드/GTM에서 쏘는 실제 key 값
          displayName: param.displayName,      // GA4 UI 보고서에 노출될 이름
          scope: 'EVENT',                      // 이벤트 범위 고정
          description: `자동 등록된 ${param.displayName} 파라미터`,
        },
      });

      console.log(`✅ 등록 성공: ${response.displayName} (${response.parameterName})`);
    } catch (error) {
      console.error(`❌ 등록 실패 [${param.parameterName}]:`, error);
    }
  }
  console.log('✨ 모든 작업이 완료되었습니다.');
}

createCustomDimensions();

💡 마치며 (주의할 점)

  • 소급 적용 불가: 앞서 말했듯 GA4는 아쉽게도 등록한 시점 이후의 데이터부터만 정식 기록을 시작합니다. (과거 데이터를 억지로 파내야 한다면 BigQuery 연동 외엔 답이 없습니다.) 그러니 새 이벤트를 기획했다면 이 스크립트로 미리 파라미터들을 싹 밀어 넣고 시작하는 걸 추천합니다.
  • 반영 시간: 스크립트가 성공적으로 끝나면 GA4 관리자 페이지의 맞춤 정의 메뉴에 바로 꽂힙니다. 하지만 실제 탐색 보고서에서 이 측정기준들을 조합해 데이터를 보려면 약 24시간 ~ 최대 48시간의 동기화 시간이 걸리니, 스크립트 돌려두고 마음 편히 이틀 뒤에 확인해 보세요!

네, 맞습니다! 이제 스크립트로 맞춤 측정기준 등록을 완료한 시점부터는 데이터가 증발하지 않고 GA4에 계속 안전하게 누적됩니다. 이제 안심하셔도 됩니다. 🎉

등록된 매개변수를 기반으로 과거 데이터(최대 1년치 포함)를 확인하는 방법과 주의하셔야 할 세팅을 정리해 드릴게요.

1. 어디서 보는 건데? (탐색 보고서에서 확인하기)

가장 정석적이고 강력한 방법은 [탐색] 메뉴를 사용하는 것입니다.

  1. GA4 좌측 메뉴에서 [탐색 (Explore)] ➔ [비어 있음 (Blank)]을 눌러 새 보고서를 만듭니다.
  2. 변수(Variables) 패널 (첫 번째 열) 세팅:
    • 기간 설정: 우측 상단 날짜를 클릭해서 원하시는 기간(예: 지난 1년)으로 늘려줍니다.
    • 측정기준(Dimension) + 버튼 클릭: 이벤트 이름과 함께, 이번에 API로 등록한 맞춤 측정기준 이름(예: 검색어, 검색 카테고리 등)을 찾아서 체크하고 [가져오기] 합니다.
    • 측정항목(Metric) + 버튼 클릭: 이벤트 수를 찾아서 체크하고 [가져오기] 합니다.
  3. 탭 설정(Tab Settings) 패널 (두 번째 열) 세팅:
    • 가져온 맞춤 측정기준(예: 검색어)을 행(Rows) 영역으로 드래그합니다.
    • 가져온 이벤트 수를 값(Values) 영역으로 드래그합니다.
  4. 필터(Filters) 설정 (가장 아래):
    • 특정 이벤트만 깨끗하게 보기 위해 이벤트 이름을 필터에 넣고 '다음과 정확하게 일치함' ➔ k_beauty_db_search 입력 후 적용합니다.

이렇게 하면 테이블에 내가 원했던 매개변수 값들이 이벤트 수와 함께 리스트로 쭉 뽑힙니다.

2. ⚠️ 중요: 1년치 데이터를 보려면 '이 설정'을 꼭 바꾸셔야 합니다!

GA4는 기본적으로 기본 데이터 보존 기간이 2달로 세팅되어 있어서, 아무리 이벤트를 오래 쌓아도 2달이 지나면 탐색 보고서에서 유저 단위의 세부 매개변수 데이터가 조회되지 않는 대참사가 일어날 수 있습니다. 1년치를 보려면 지금 당장 이걸 14개월로 늘려놓으셔야 합니다.

🛠️ 데이터 보존 기간 변경 방법 (지금 바로 하세요!)

  1. GA4 왼쪽 아래 ⚙️ [관리 (Admin)]로 들어갑니다.
  2. 데이터 수집 및 수정 항목에서 [데이터 보존 (Data retention)]을 클릭합니다.
  3. 이벤트 데이터 보존(Event data retention) 항목이 기본값인 2개월로 되어 있다면, 드롭다운을 눌러 14개월로 변경합니다.
  4. 우측 상단의 [저장]을 누릅니다.

💡 주의: 14개월로 늘려두시면 앞으로 최대 14개월까지의 과거 데이터를 탐색 보고서에서 자유롭게 조회할 수 있습니다. (GA4 일반 계정의 최대 한도가 14개월입니다. 만약 2년, 3년 치 이상의 원시 데이터를 제한 없이 보고 싶다면 그때는 BigQuery(빅쿼리) 연동을 걸어두셔야 합니다.)

요약하자면!

  1. 지금 이후 데이터부터 매개변수가 차곡차곡 남기 시작합니다.
  2. 보고서에 반영되기까지 24~48시간 걸리니 내일이나 모레 확인해 보세요.
  3. 과거 1년치를 보려면 데이터 보존 기간을 '14개월'로 변경하는 것을 절대 잊지 마세요!
Contact support