GA 분석 리포트 가이드

조직의 GA4+Search Console 통합 AI 분석 리포트(핵심)와, 선택한 속성/사이트의 최신 지표·이력(보조)을 함께 조회합니다.

🔗 GA 분석 리포트 열기 →

📋 개요

이 페이지는 두 계층으로 구성됩니다.

• 종합 리포트(핵심) — GA4+Search Console 데이터를 함께 본 AI 분석. 우측 이력 리스트에서 지난 날짜를 클릭하면 그 시점 리포트를 다시 볼 수 있고, 마음에 드는 제안은 "이 제안을 이슈로 등록" 버튼으로 바로 giip 이슈로 등록할 수 있습니다. 그 아래 "리포트 생성 시 자동으로 이슈 등록" 토글을 켜 두면, 이후 종합 리포트가 새로 만들어질 때마다 그 제안이 자동으로 giip 이슈로 등록됩니다(토글을 켜는 순간 화면에 표시 중인 최신 리포트가 아직 미등록이면 그 1건도 바로 등록됩니다). 토글이 꺼져 있을 때는 기존 수동 등록 버튼을 그대로 쓸 수 있습니다.
• 개별 GA4 / GSC 패널(보조) — 종합 리포트 아래에 속성별 최신 지표(KPI 카드)와 최근 일별 이력 테이블, GSC 상위 검색어를 각각 별도 패널로 보여줍니다. 개별 AI 분석은 더 이상 여기서 생성되지 않으며(위 종합 리포트가 유일한 최종 분석), 이 패널들은 숫자를 직접 확인하고 싶을 때 참고용으로만 씁니다.

✅ 전제 조건

1. GA4 속성과(선택) Search Console 사이트가 조직에 등록되어 있어야 함 — GA 속성 관리, GSC 사이트 참고. 종합 리포트는 등록되지 않은 소스가 있으면 그 항목을 "설정 필요" 링크로 안내합니다.
2. 수집이 동작 중이어서 데이터가 있어야 함(아래 "수집 설정" 참고).

🔎 리포트 조회

1. 페이지에 들어가면 종합 리포트가 자동으로 로드됩니다. 우측 이력 리스트에서 날짜를 클릭하면 해당 시점 리포트로 전환되고, "최신으로" 버튼으로 다시 최신 리포트로 돌아올 수 있습니다.
2. 개별 지표를 보고 싶으면 아래 GA4/GSC 패널에서 등록된 속성·사이트를 드롭다운으로 선택(또는 수동 입력)하세요.

📊 지표

지표	의미
활성 사용자	순 활성 사용자
세션	세션 수
페이지뷰	화면/페이지 조회수
이탈률	단일 상호작용 세션 비율(% 표시)
전환수	전환 이벤트
평균 세션(초)	평균 세션 시간(초)
클릭수 / 노출수 (GSC)	Search Console 검색 결과 클릭·노출
CTR / 평균 순위 (GSC)	클릭률(%) / 평균 검색 순위

🤖 AI 분석은 어떻게 페이지를 구분하나

종합 리포트의 AI는 사이트의 각 경로(URL)를 보고 마케팅/공개 페이지(방문자가 로그인 없이 보는 랜딩·블로그 등)와 로그인 후 제품/관리 화면(예: 대시보드, 관리자 전용 화면)을 자동으로 구분해서 분석합니다. 후자는 "전환 유입" 관점의 지적 대상에서 자동으로 빠집니다.

자동 분류가 우리 조직 상황과 다르거나(예: 일부 공개 페이지를 예외적으로 로그인 없이 운영), 우리 서비스만의 방향성·타겟 고객을 AI가 더 잘 반영하게 하고 싶다면 **관리자 > Gareport AI 커스텀 프롬프트**에서 우리 조직(csn)에만 적용되는 추가 지침을 직접 입력할 수 있습니다. 전역 규칙을 대체하지 않고 그 뒤에 덧붙는 방식입니다.

⚙️ 수집 설정 (관리자)

지표는 GIIP 에이전트/서버가 수집하고 정기적으로 AI가 통합 분석합니다. 최초 설정:

1. GA4 속성 등록(GA 속성 관리) 및 GSC 사이트 등록(GSC 사이트) — 두 소스를 모두 등록해야 종합 리포트가 완전해집니다.
2. 서비스계정 키 — GA4 읽기 권한의 Google 서비스계정을 만들어 속성에 공유. 키 JSON은 giipdb mgmt/ga-collector.config.json.sample의 serviceAccountKeyFile 경로에 배치(실제 경로: giipdb/.secrets/ga-service-account.json, gitignore). giipfaw의 ProcessGaCollect가 이 파일을 읽어 Google Data API를 직접 호출합니다.
3. 수집 잡 — giipfaw의 타이머 함수(ProcessGaCollect)가 DB(tGaConfig)에 등록된 활성 속성 목록을 읽고 자동으로 수집을 실행합니다. 별도 PC/에이전트 배포가 필요하지 않습니다. CQE 가이드 및 giipdb docs/30_Specs/CQE_SPECIFICATION.md는 기존 에이전트 기반 수집 설정에만 적용됩니다(구방식).
4. AI 분석(종합) — giipfaw의 ProcessComboReport가 GA4+GSC 데이터를 함께 읽어 통합 리포트를 생성합니다. 표본이 너무 적으면(예: 방문자 수 부족) 그 사실을 리포트에 함께 표시합니다.

수집이 돌기 시작하면 이 페이지가 자동으로 채워집니다.

문제 해결

증상	원인	해결
"아직 리포트가 없습니다"	종합 리포트 배치가 아직 실행되지 않음	수집·설정 여부를 확인하고 다음 실행을 기다리세요.
"설정 필요" 링크가 뜸	GA4 속성 또는 GSC 사이트 중 하나가 미등록	안내된 링크(GA 속성 관리 / GSC 사이트)에서 등록.
속성/사이트 드롭다운이 비어 있음	이 조직에 등록된 속성·사이트 없음	각 관리 화면에서 등록.
403 / 접근 거부	속성 조직에 대한 권한 없음	소속 조직으로 사용.
AI 분석이 우리 서비스 구조를 잘못 이해함	자동 페이지 분류가 우리 조직의 예외 상황을 반영 못함	Gareport AI 커스텀 프롬프트에서 추가 지침 입력.

🔌 AI용 최신 데이터 조회 API

외부 AI가 화면을 해석하거나 Google 계정에 로그인하지 않고, 조직 식별값(csn)과 그 조직의 비밀 키(SK)만으로 GIIP가 이미 수집한 GA4/GSC 최신 스냅샷과 통합 리포트를 한 번에 읽을 수 있는 읽기 전용 API입니다. 데이터 재수집·재분석·설정 변경 기능은 포함하지 않습니다.

⚠️ 범위 한계: 이 API는 최신 스냅샷 1건만 제공하며, 화면의 이력 리스트(과거 날짜별 리포트)나 일별 히스토리 테이블 전체는 포함하지 않습니다 — 오직 가장 최근 수집/생성된 데이터만 조회됩니다.

요청

항목	값
메서드	GET
URL	https://giipfaw.azurewebsites.net/api/giipGareportSnapshot?csn={CSN}
헤더	x-api-key: {SK}
파라미터	양의 정수 csn 하나만

성공 응답 (HTTP 200)

{
  "csn": 47,
  "retrievedAt": "2026-09-01T00:00:00Z",
  "sources": {
    "gsc": { "status": "READY", "siteCount": 1 },
    "ga4": { "status": "READY", "propertyCount": 1 },
    "combinedReport": { "status": "READY" }
  },
  "gscSites": [ { "siteUrl": "...", "label": "...", "collectedAt": "...", "data": { } } ],
  "ga4Properties": [ { "propertyId": "...", "label": "...", "collectedAt": "...", "data": { } } ],
  "combinedReport": { "reportId": 0, "generatedAt": "...", "dataSources": "ga+gsc", "missingConfig": null, "language": "ko", "content": "## 1. 현재 상황 (Current Situation)\n최근 28일간 활성 사용자는 전 28일 대비 12% 증가...\n\n## 2. 오늘의 핵심 병목 (Today's Core Bottleneck)\n랜딩 페이지 A의 이탈률이 78%로 유입 대비 전환이 막혀 있음...\n\n## 3. 근거 (Evidence)\n[MEASURED] ...\n\n## 4. 지금 실행할 작업 (Actions To Execute Now)\n대상: /pricing ...\n\n## 5. 보류할 판단 (Judgments On Hold)\n..." }
}

• gscSites[].data 는 그 사이트의 최신 GSC 원시 JSON(totals, topQueries, topPageQueries, date, range, collectedAt, source)을 원형 그대로 담습니다.
• ga4Properties[].data 는 그 속성의 최신 GA4 원시 JSON 객체로, 다음 필드를 포함합니다(giipfaw ProcessGaCollect 수집 스키마 기준):
  • propertyId, range(수집 대상일), collectedAt, source
  • metrics: activeUsers, sessions, screenPageViews, bounceRate, conversions, averageSessionDuration
  • topPages: 페이지별 조회수 상위 10건 배열 — 각 항목 pagePath, screenPageViews, bounceRate, averageSessionDuration
  • landingPages: 랜딩 페이지별 세션 상위 10건 배열 — 각 항목 landingPage, sessions, bounceRate
  • events: 이벤트별 발생 건수 상위 20건 배열 — 각 항목 eventName, eventCount
  • coreWebVitals: 사이트 URL과 조직 자체 PageSpeed API 키가 모두 설정된 경우만 값이 있으며, 그 외에는 null. 값이 있으면 mobile/desktop 각각에 performanceScore, lcpMs, clsScore, inpMs, fcpMs, ttfbMs
  • periods: 비교 기간별(current_3d, current_7d, current_28d, previous_28d, current_90d) startDate/endDate/metrics(수집 실패 시 null)
• combinedReport 는 최신 통합 리포트 한 건(없으면 null)입니다. content는 위와 같이 5개 섹션(현재 상황/오늘의 핵심 병목/근거/지금 실행할 작업/보류할 판단)으로 구성된 마크다운 문자열입니다 — 위 예시는 구조를 보여주기 위한 것이며 실제 값은 조직·기간마다 다릅니다.
• gscKeyJson, gaKeyJson, Google 서비스계정 키, SK, AK, DB 연결정보는 어떤 응답에도 포함되지 않습니다.

오류 응답

오류 본문은 항상 { "error": { "code": "...", "message": "..." } } 형식입니다.

조건	HTTP	error.code
SK 누락 또는 유효하지 않음	401	UNAUTHENTICATED
SK가 요청 csn에 접근 불가	403	FORBIDDEN_CSN
csn 누락·숫자 아님·0 이하	400	INVALID_CSN
서버 또는 DB 오류	500	INTERNAL_ERROR

호출 예시 (실제 비밀값 없이 환경변수로)

export GIIP_API_BASE_URL="https://giipfaw.azurewebsites.net"
export GIIP_CSN="47"
export GIIP_SK="런타임에만_설정"

curl --fail-with-body \
  -H "x-api-key: ${GIIP_SK}" \
  "${GIIP_API_BASE_URL}/api/giipGareportSnapshot?csn=${GIIP_CSN}"

⚠️ 보안: SK를 URL, 이슈, 저장소, 프롬프트 본문, 로그에 넣지 마세요. 실행 환경변수 또는 비밀 저장소에서만 전달합니다.

상태값과 AI가 취할 행동

GSC 데이터는 보통 이틀에서 사흘 지연됩니다(구글 확정 지연).

상태	의미	AI가 취할 행동
READY	활성 속성이 있고 최신 수집 원시 데이터가 있음	그 데이터를 사실로 요약
NOT_CONFIGURED	해당 csn에 활성 속성이 없음	추정하지 말고 "설정 안 됨"으로 그대로 보고
NO_DATA	활성 속성은 있으나 최신 수집 데이터가 없음	추정하지 말고 "데이터 없음"으로 그대로 보고

AI 호출 고정 절차

1. 스냅샷을 한 번만 조회한다.
2. sources의 각 상태를 먼저 확인한다.
3. READY인 데이터만 사실로 요약하고, NOT_CONFIGURED/NO_DATA는 추정하지 않고 그대로 보고한다.
4. 통합 리포트의 content는 제안이고, GSC/GA4 data의 수치는 사실 데이터로 구분해 다룬다.
5. 과거 리포트나 일별 히스토리가 필요해도 이 API로는 조회할 수 없다 — 최신 스냅샷만 사실로 취급하고, 과거 데이터가 필요하다는 요청을 받으면 "이 API는 최신 데이터만 제공한다"고 명시적으로 알린다.

---

버전: 1.5 최종 업데이트: 2026-09-18 변경 이력: giip 2709 — 종합 리포트 "생성 시 자동 이슈 등록" 토글 추가(수동 등록 버튼은 토글 OFF 시 유지). / giip #2068 — API가 최신 스냅샷 1건만 제공한다는 한계 명시, ga4Properties[].data 실측 필드 스키마 추가, combinedReport.content 예시 보강. 소스 파일: giipv3/public/help/gareport.ko.md