https://nextjs.org/docs/app/guides/third-party-libraries#google-analytics 페이지를 번역
서드파티 라이브러리 가이드
서드파티 라이브러리를 최적화하는 방법
@next/third-parties
@next/third-parties는 Next.js 애플리케이션에서 인기있는 서드파티 라이브러리를 로드할 때 성능과 개발자 경험을 개선하는 컴포넌트와 유틸리티 모음을 제공하는 라이브러리입니다.
@next/third-parties가 제공하는 모든 서드파티 통합은 성능과 사용 편의성을 위해 최적화되어 있습니다.
시작하기
시작하려면 @next/third-parties 라이브러리를 설치하세요:
npm install @next/third-parties@latest next@latest
@next/third-parties는 현재 활발하게 개발 중인 실험적 라이브러리입니다. 더 많은 서드파티 통합을 추가하는 작업을 진행하고 있으므로 latest 또는 canary 플래그와 함께 설치하는 것을 권장합니다.
Google 서드파티
Google에서 지원하는 모든 서드파티 라이브러리는 @next/third-parties/google에서 import할 수 있습니다.
Google Tag Manager
GoogleTagManager 컴포넌트는 페이지에 Google Tag Manager 컨테이너를 인스턴스화하는 데 사용할 수 있습니다. 기본적으로 페이지에서 하이드레이션이 발생한 후 원본 인라인 스크립트를 가져옵니다.
모든 라우트에 Google Tag Manager를 로드하려면, 루트 레이아웃에 컴포넌트를 직접 포함하고 GTM 컨테이너 ID를 전달하세요:
import { GoogleTagManager } from '@next/third-parties/google'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<GoogleTagManager gtmId="GTM-XYZ" />
<body>{children}</body>
</html>
)
}
단일 라우트에 Google Tag Manager를 로드하려면, 페이지 파일에 컴포넌트를 포함하세요:
import { GoogleTagManager } from '@next/third-parties/google'
export default function Page() {
return <GoogleTagManager gtmId="GTM-XYZ" />
}
이벤트 전송
sendGTMEvent 함수는 dataLayer 객체를 사용하여 이벤트를 보내는 방식으로 페이지에서 사용자 상호작용을 추적하는 데 사용할 수 있습니다. 이 함수가 작동하려면 <GoogleTagManager /> 컴포넌트가 상위 레이아웃, 페이지, 컴포넌트 또는 동일한 파일에 직접 포함되어야 합니다.
'use client'
import { sendGTMEvent } from '@next/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
>
이벤트 전송
</button>
</div>
)
}
함수에 전달할 수 있는 다양한 변수와 이벤트에 대해 알아보려면 Tag Manager 개발자 문서를 참조하세요.
서버 사이드 태깅
서버 사이드 태그 매니저를 사용하고 태깅 서버에서 gtm.js 스크립트를 제공하는 경우, gtmScriptUrl 옵션을 사용하여 스크립트의 URL을 지정할 수 있습니다.
옵션
Google Tag Manager에 전달할 옵션입니다. 전체 옵션 목록은 Google Tag Manager 문서를 읽어보세요.
이름 타입 설명
| gtmId | 필수 | GTM 컨테이너 ID. 일반적으로 GTM-으로 시작합니다. |
| gtmScriptUrl | 선택 | GTM 스크립트 URL. 기본값은 https://www.googletagmanager.com/gtm.js입니다. |
| dataLayer | 선택 | 컨테이너를 인스턴스화할 데이터 레이어 객체. |
| dataLayerName | 선택 | 데이터 레이어의 이름. 기본값은 dataLayer입니다. |
| auth | 선택 | 환경 스니펫의 인증 매개변수(gtm_auth) 값. |
| preview | 선택 | 환경 스니펫의 미리보기 매개변수(gtm_preview) 값. |
Google Analytics
GoogleAnalytics 컴포넌트는 Google 태그(gtag.js)를 통해 페이지에 Google Analytics 4를 포함하는 데 사용할 수 있습니다. 기본적으로 페이지에서 하이드레이션이 발생한 후 원본 스크립트를 가져옵니다.
권장사항: 애플리케이션에 Google Tag Manager가 이미 포함되어 있는 경우, Google Analytics를 별도의 컴포넌트로 포함하는 대신 Google Tag Manager를 사용하여 Google Analytics를 직접 구성할 수 있습니다. Tag Manager와 gtag.js의 차이점에 대해 자세히 알아보려면 문서를 참조하세요.
모든 라우트에 Google Analytics를 로드하려면, 루트 레이아웃에 컴포넌트를 직접 포함하고 측정 ID를 전달하세요:
import { GoogleAnalytics } from '@next/third-parties/google'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
<GoogleAnalytics gaId="G-XYZ" />
</html>
)
}
단일 라우트에 Google Analytics를 로드하려면, 페이지 파일에 컴포넌트를 포함하세요:
import { GoogleAnalytics } from '@next/third-parties/google'
export default function Page() {
return <GoogleAnalytics gaId="G-XYZ" />
}
이벤트 전송
sendGAEvent 함수는 dataLayer 객체를 사용하여 이벤트를 보내는 방식으로 페이지에서 사용자 상호작용을 측정하는 데 사용할 수 있습니다. 이 함수가 작동하려면 <GoogleAnalytics /> 컴포넌트가 상위 레이아웃, 페이지, 컴포넌트 또는 동일한 파일에 직접 포함되어야 합니다.
'use client'
import { sendGAEvent } from '@next/third-parties/google'
export function EventButton() {
return (
<div>
<button
onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
>
이벤트 전송
</button>
</div>
)
}
이벤트 매개변수에 대해 자세히 알아보려면 Google Analytics 개발자 문서를 참조하세요.
페이지뷰 추적
Google Analytics는 브라우저 히스토리 상태가 변경될 때 자동으로 페이지뷰를 추적합니다. 이는 Next.js 라우트 간의 클라이언트 사이드 탐색이 별도의 구성 없이 페이지뷰 데이터를 전송한다는 의미입니다.
클라이언트 사이드 탐색이 올바르게 측정되고 있는지 확인하려면, 관리자 패널에서 "향상된 측정" 속성이 활성화되어 있고 "브라우저 히스토리 이벤트 기반 페이지 변경" 체크박스가 선택되어 있는지 확인하세요.
참고: 페이지뷰 이벤트를 수동으로 전송하기로 결정한 경우, 중복 데이터를 방지하기 위해 기본 페이지뷰 측정을 비활성화해야 합니다. 자세한 내용은 Google Analytics 개발자 문서를 참조하세요.
옵션
<GoogleAnalytics> 컴포넌트에 전달할 옵션입니다.
이름 타입 설명
| gaId | 필수 | 측정 ID. 일반적으로 G-로 시작합니다. |
| dataLayerName | 선택 | 데이터 레이어의 이름. 기본값은 dataLayer입니다. |
| nonce | 선택 | 인라인 스크립트에 대한 nonce. |
Google Maps Embed
GoogleMapsEmbed 컴포넌트는 페이지에 Google Maps Embed를 추가하는 데 사용할 수 있습니다. 기본적으로 loading 속성을 사용하여 페이지 하단에서 임베드를 지연 로드합니다.
import { GoogleMapsEmbed } from '@next/third-parties/google'
export default function Page() {
return (
<GoogleMapsEmbed
apiKey="XYZ"
height={200}
width="100%"
mode="place"
q="Brooklyn+Bridge,New+York,NY"
/>
)
}
옵션
Google Maps Embed에 전달할 옵션입니다. 전체 옵션 목록은 Google Map Embed 문서를 읽어보세요.
이름 타입 설명
| apiKey | 필수 | API 키. |
| mode | 필수 | 맵 모드. |
| height | 선택 | 임베드의 높이. 기본값은 auto입니다. |
| width | 선택 | 임베드의 너비. 기본값은 auto입니다. |
| style | 선택 | 임베드에 적용할 스타일. |
| allowfullscreen | 선택 | 전체 화면 허용 여부. |
| loading | 선택 | 기본값은 lazy입니다. |
| q | 선택 | 맵 마커 위치를 정의합니다. |
| center | 선택 | 맵 뷰의 중심을 정의합니다. |
| zoom | 선택 | 맵의 초기 줌 레벨을 설정합니다. |
| maptype | 선택 | 로드할 맵 타일의 유형을 정의합니다. |
| language | 선택 | UI 요소와 맵 타일의 레이블 표시에 사용할 언어를 정의합니다. |
| region | 선택 | 지정학적 민감성에 따라 표시할 적절한 경계와 레이블을 정의합니다. |
YouTube Embed
YouTubeEmbed 컴포넌트는 YouTube 임베드를 로드하고 표시하는 데 사용할 수 있습니다. 이 컴포넌트는 내부적으로 lite-youtube-embed를 사용하여 더 빠르게 로드됩니다.
import { YouTubeEmbed } from '@next/third-parties/google'
export default function Page() {
return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}
옵션
이름 타입 설명
| videoid | 필수 | YouTube 비디오 ID. |
| width | 선택 | 비디오 컨테이너의 너비. 기본값은 auto입니다. |
| height | 선택 | 비디오 컨테이너의 높이. 기본값은 auto입니다. |
| playlabel | 선택 | 접근성을 위한 재생 버튼의 시각적으로 숨겨진 레이블. |
| params | 선택 | 비디오 플레이어 매개변수. 쿼리 매개변수 문자열로 전달됩니다. 예: params="controls=0&start=10&end=30" |
| style | 선택 | 컴포넌트에 적용할 스타일. |
