구글 애널리틱스 API 연동을 위한 방법이 다양해서 오히려 헷갈리더라구요.
제가 연동한 방법을 소개합니다!
먼저 프로젝트에서 구글 애널리틱스 API로 데이터를 받아보기 위해서는 3가지 선행 작업이 필요합니다.
GA API를 사용하기 위해서는 GCP 콘솔에서 서비스 계정을 추가하고, API를 호출할 때 필요한 키를 JSON 형태로 다운로드 받아야 합니다.
사전 준비
1.구글 클라우드 콘솔에서 서비스 계정을 추가
https://console.cloud.google.com
- 구글 클라우드 콘솔에 접속하여 해당 프로젝트 내용으로 새로 생성하기
- 대시보드를 눌러서 프로젝트 설정으로 이동
- 좌측 메뉴에서 서비스 계정을 선택하고 상단에 서비스 계정 만들기 클릭
- 작업 … 를 눌러 키관리 선택 후 새 키 만들기
- 다운받은 JSON 파일을 열어 client_email라는 키의 값을 복사합니다.
- 이후 구글 애널리틱스 사이트로 이동합니다.
(사진 추가 예정)
2. 구글 애널리틱스 사이트에서 계정 엑세스 관리로 사용자 추가
구글 애널리틱스 사이트에서 1번의 서비스 계정을 추가해서 얻은 JSON 파일의 이메일 값을 써야한다.
- 홈의 속성 설정 계속 진행하기 의 설정 어시스턴트로 이동하기 클릭
- 왼쪽 메뉴 탭의 톱니바퀴 모양의 설정에 들어가서 계정 → 계정 액세스 관리 클릭도 가능
- 계정 액세스 관리에서
+버튼을 눌러 사용자 추가 클릭 - 이메일 주소에 아까 다운로드 받은 JSON의 client_email 입력하고, 표준 역할은 뷰어로 선택
- client_email는
AAAA예시@AAAAAAA예시.iam.gserviceaccount.com형태이다.
3. 구글 클라우드 콘솔에서 API 및 서비스에서 GA API 사용하기
- API 및 서비스 → 라이브러리
- Google Analytics 를 검색 후 Google Analytics Data API를 선택합니다.
- 사용하기를 누릅니다.
라이브러리 검색 시 Google Analytics의 API가 3종류가 있으며 간략한 소개를 덧붙입니다.
1) Google Analytics API (Universal Analytics)
- Google Analytics의 구버전(UA) 데이터를 추출하는 데 사용됩니다.
- Universal Analytics 계정을 사용하고 있다면 이 API를 사용해야 합니다.
2023년 7월 1일 이후, 새로운 Universal Analytics 프로퍼티의 데이터 처리가 중단되므로, 기존 UA 프로퍼티를 사용 중이 아니라면 이 API를 사용하는 것은 추천되지 않습니다. (gpt의 설명으로 부정확할 수 있습니다.)
2) Google Analytics Reporting API v4
Google Analytics의 Universal Analytics와 GA4 데이터를 보고하는 데 사용됩니다.
3) Google Analytics Data API (GA4) - 이번에 사용하는 라이브러리
Google Analytics 4(GA4) 데이터를 추출하는 데 사용됩니다.
프로젝트에 API 연결하기
사전 작업을 마치고 프로젝트에서 구글 API를 호출하는 방법입니다.
1. Google API Client 설정
Google API Client 라이브러리 설치가 필요합니다. Node.js 환경에서 호출하는 경우, 먼저 googleapis 라이브러리를 설치해야 합니다.
속성ID(숫자)
npm install googleapis2. 서비스 계정 키 파일 준비
서비스 계정 키는 이미 JSON 형식으로 받았으므로, 해당 파일을 프로젝트에 안전하게 보관합니다.
저는 루트 디렉토리 secrets 폴더에 해당 JSON 파일을 넣었습니다.
secrets/service-account-key.json
그리고 .env.local 에서 해당 파일경로를 환경변수로 등록했습니다.
GOOGLE_SERVICE_KEY_PATH=secrets/service-account-key.json잊지말고 .gitlgnore에 해당 파일경로를 등록해주세요!
# 구글 애널리틱스 서비스 키
/secrets/service-account-key.json3. Google Analytics Data API 클라이언트 설정
API 호출을 위한 코드입니다. getAnalyticsData 함수의 requestBody에서 dateRanges와 metrics는 필요한 데이터에 따라 변경하시면 됩니다.
저는 누적 방문객을 얻고싶어서 totalUsers으로 했습니다.
reponse의 property: 'properties/속성ID(숫자)'에서 속성 ID는 구글 애널리틱스 설정 -> 속성 설정 -> 속성 -> 속성 세부정보에서 확인할 수 있습니다.
lib/getAnalyticsData.ts
import { google } from 'googleapis'
import path from 'path'
// 서비스 계정 키 파일 경로 설정
const keyFilePath = path.join(process.cwd(), process.env.GOOGLE_SERVICE_KEY_PATH!)
// 인증 클라이언트 생성
const auth = new google.auth.GoogleAuth({
keyFile: keyFilePath,
scopes: ['https://www.googleapis.com/auth/analytics.readonly'],
})
const analyticsData = google.analyticsdata('v1beta')
export async function getAnalyticsData() {
try {
const authClient = await auth.getClient()
const response = await analyticsData.properties.runReport({
auth: authClient,
properties/YOUR_PROPERTY_ID,
// 속성 ID를 직접 파라미터로 전달
requestBody: {
dateRanges: [
{
startDate: '7daysAgo',
endDate: 'today',
},
],
metrics: [
{
name: 'totalUsers',
},
],
},
})
return response.data
} catch (error) {
console.error('Error fetching Analytics Data:', error)
throw error
}
}
// app/page.tsx
export default async function Start() {
try {
const data = await getAnalyticsData()
console.log('Analytics Data:', data)
return (
<div>
{/* data를 사용하여 UI 렌더링 */}
<pre>{JSON.stringify(data, null, 2)}</pre>
</div>
)
} catch (error) {
console.error('Error in page:', error)
return <div>Error loading analytics data</div>
}
}호출한 결과를 보면 다음과 같습니다.
4. API 호출 시 필요한 주요 값
YOUR_PROPERTY_ID: GA4의 속성 ID. GA4 계정에서 찾을 수 있습니다. 보통properties/XXXXXX형태입니다.activeUsers: 요청하려는 데이터의 메트릭입니다. 다른 메트릭도 사용 가능합니다. 예:sessions,users등.dateRanges: 데이터를 요청할 날짜 범위입니다. 예: 최근 7일('7daysAgo')부터 오늘까지('today').
GA4의 메트릭 설명
- activeUsers: 현재 활성 사용자 수 (지정된 기간 동안 실제로 사이트와 상호작용한 사용자 수)
- totalUsers: 지정된 기간 동안의 총 방문자 수 (중복 제외)
주요 메트릭 활용
- totalUsers와 activeUsers를 비교하여 사이트의 전반적인 활성도 파악
- sessions와 totalUsers를 비교하여 재방문율 추정
- averageSessionDuration으로 사용자 참여도 측정
- screenPageViews로 전체적인 사이트 트래픽 파악
여러 메트릭 동시 조회와 사용 예시
export async function getAnalyticsData() {
try {
const authClient = await auth.getClient()
const response = await analyticsData.properties.runReport({
auth: authClient,
property: 'properties/466314451',
requestBody: {
dateRanges: [
{
startDate: '2024-01-01',
endDate: 'today',
},
],
metrics: [
{ name: 'totalUsers' },
{ name: 'activeUsers' },
// 추가로 유용한 메트릭들
{ name: 'sessions' }, // 세션 수
{ name: 'averageSessionDuration' }, // 평균 세션 지속 시간
{ name: 'screenPageViews' } // 총 페이지뷰 수
],
},
})
// 응답 데이터 처리 예시
const metrics = response.data.rows[0].metricValues
const analyticsData = {
totalUsers: metrics[0].value,
activeUsers: metrics[1].value,
sessions: metrics[2].value,
avgSessionDuration: metrics[3].value,
pageViews: metrics[4].value,
}
return analyticsData
} catch (error) {
console.error('Error fetching Analytics Data:', error)
throw error
}
}// 서버 컴포넌트
export default async function Start() {
const data = await getAnalyticsData()
return <Analytics analyticsData={data} />
}
// 클라이언트 컴포넌트
'use client'
type AnalyticsData = {
totalUsers: string
activeUsers: string
sessions: string
avgSessionDuration: string
pageViews: string
}
export function Analytics({ analyticsData }: { analyticsData: AnalyticsData }) {
return (
<div className="space-y-4">
<div>총 방문자 수: {analyticsData.totalUsers}명</div>
<div>현재 활성 사용자: {analyticsData.activeUsers}명</div>
<div>총 세션 수: {analyticsData.sessions}</div>
<div>평균 세션 시간: {Math.round(Number(analyticsData.avgSessionDuration) / 60)}분</div>
<div>총 페이지뷰: {analyticsData.pageViews}</div>
</div>
)
}