Third Party Libraries

@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 Third-Parties

Google의 지원되는 모든 서드 파티 라이브러리는 @next/third-parties/google에서 가져올 수 있습니다.

Google Tag Manager

GoogleTagManager 컴포넌트는 페이지에 Google Tag Manager (opens in a new tab) 컨테이너를 인스턴스화하는 데 사용할 수 있습니다. 기본적으로 페이지가 하이드레이션된 후 원래 인라인 스크립트를 가져옵니다.

모든 라우트에 대해 Google Tag Manager를 로드하려면 컴포넌트를 커스텀 _app에 직접 포함하고 GTM 컨테이너 ID를 전달하세요:

import { GoogleTagManager } from '@next/third-parties/google'
 
export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleTagManager gtmId="GTM-XYZ" />
    </>
  )
}

단일 라우트에 대해 Google Tag Manager를 로드하려면 페이지 파일에 컴포넌트를 포함하세요:

import { GoogleTagManager } from '@next/third-parties/google'
 
export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

이벤트 전송

sendGTMEvent 함수는 dataLayer 객체를 사용하여 이벤트를 전송함으로써 페이지에서 사용자 상호작용을 추적하는 데 사용할 수 있습니다. 이 함수가 작동하려면 <GoogleTagManager /> 컴포넌트가 부모 레이아웃, 페이지 또는 컴포넌트에 포함되어 있어야 하거나 동일한 파일에 직접 포함되어 있어야 합니다.

import { sendGTMEvent } from '@next/third-parties/google'
 
export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent('event', 'buttonClicked', { value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}

Tag Manager 개발자 문서 (opens in a new tab)를 참조하여 함수에 전달할 수 있는 다양한 변수와 이벤트에 대해 알아보세요.

옵션

Google Tag Manager에 전달할 옵션입니다. 전체 옵션 목록은 Google Tag Manager 문서 (opens in a new tab)를 참조하세요.

Google Analytics

GoogleAnalytics 컴포넌트는 Google 태그(gtag.js)를 통해 Google Analytics 4 (opens in a new tab)를 페이지에 포함하는 데 사용할 수 있습니다. 기본적으로 페이지가 하이드레이션된 후 원래 스크립트를 가져옵니다.

권장 사항: 애플리케이션에 Google Tag Manager가 이미 포함되어 있는 경우, Google Analytics를 별도의 컴포넌트로 포함하는 것보다 Tag Manager를 사용하여 직접 구성할 수 있습니다. Tag Manager와 gtag.js의 차이점에 대해 자세히 알아보려면 문서 (opens in a new tab)를 참조하세요.

모든 라우트에 대해 Google Analytics를 로드하려면 컴포넌트를 커스텀 _app에 직접 포함하고 측정 ID를 전달하세요:

import { GoogleAnalytics } from '@next/third-parties/google'
 
export default function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <GoogleAnalytics gaId="G-XYZ" />
    </>
  )
}

단일 라우트에 대해 Google Analytics를 로드하려면 페이지 파일에 컴포넌트를 포함하세요:

import { GoogleAnalytics } from '@next/third-parties/google'
 
export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

이벤트 전송

sendGAEvent 함수는 dataLayer 객체를 사용하여 이벤트를

전송함으로써 페이지에서 사용자 상호작용을 측정하는 데 사용할 수 있습니다. 이 함수가 작동하려면 <GoogleAnalytics /> 컴포넌트가 부모 레이아웃, 페이지 또는 컴포넌트에 포함되어 있어야 하거나 동일한 파일에 직접 포함되어 있어야 합니다.

import { sendGAEvent } from '@next/third-parties/google'
 
export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
      >
        Send Event
      </button>
    </div>
  )
}

Google Analytics 개발자 문서 (opens in a new tab)를 참조하여 이벤트 매개변수에 대해 자세히 알아보세요.

페이지뷰 추적

Google Analytics는 브라우저 기록 상태가 변경될 때 자동으로 페이지뷰를 추적합니다. 이는 Next.js 라우트 간의 클라이언트 사이드 탐색이 구성 없이 페이지뷰 데이터를 전송함을 의미합니다.

클라이언트 사이드 탐색이 올바르게 측정되고 있는지 확인하려면 관리자 패널에서 “Enhanced Measurement” (opens in a new tab) 속성이 활성화되고 “Page changes based on browser history events” 체크박스가 선택되어 있는지 확인하세요.

참고: 페이지뷰 이벤트를 수동으로 전송하기로 결정한 경우 중복 데이터를 방지하기 위해 기본 페이지뷰 측정을 비활성화해야 합니다. Google Analytics 개발자 문서 (opens in a new tab)를 참조하여 자세히 알아보세요.

옵션

<GoogleAnalytics> 컴포넌트에 전달할 옵션입니다.

Google Maps Embed

GoogleMapsEmbed 컴포넌트는 페이지에 Google Maps Embed (opens in a new tab)를 추가하는 데 사용할 수 있습니다. 기본적으로 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 문서 (opens in a new tab)를 참조하세요.

YouTube Embed

YouTubeEmbed 컴포넌트는 YouTube 임베드를 로드하고 표시하는 데 사용할 수 있습니다. 이 컴포넌트는 내부적으로 lite-youtube-embed (opens in a new tab)를 사용하여 더 빠르게 로드됩니다.

import { YouTubeEmbed } from '@next/third-parties/google'
 
export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

옵션