서드파티 라이브러리

@next/third-parties 는 Next.js 애플리케이션에서 인기 있는 서드파티 라이브러리를 로드할 때 성능과 개발자 경험을 향상시키는 컴포넌트와 유틸리티 모음을 제공하는 라이브러리입니다.

@next/third-parties가 제공하는 모든 서드파티 통합은 성능과 사용 용이성을 위해 최적화되었습니다.

시작하기

시작하려면 @next/third-parties 라이브러리를 설치하세요:

Terminal

npm install @next/third-parties@latest next@latest

@next/third-parties는 현재 활발히 개발 중인 실험적인 라이브러리입니다. 더 많은 서드파티 통합을 추가하는 동안 latest 또는 canary 플래그를 사용하여 설치하는 것을 권장합니다.

Google 서드파티

Google에서 지원하는 모든 서드파티 라이브러리는 @next/third-parties/google에서 임포트할 수 있습니다.

Google 태그 관리자

GoogleTagManager 컴포넌트를 사용하여 페이지에 Google 태그 관리자 컨테이너를 인스턴스화할 수 있습니다. 기본적으로 페이지에서 하이드레이션이 발생한 후 원본 인라인 스크립트를 가져옵니다.

모든 경로에 Google 태그 관리자를 로드하려면 루트 레이아웃에 직접 컴포넌트를 포함하고 GTM 컨테이너 ID를 전달하세요:

app/layout.tsx

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>
  );
}

app/layout.js

import { GoogleTagManager } from "@next/third-parties/google";
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  );
}

단일 경로에 Google 태그 관리자를 로드하려면 페이지 파일에 컴포넌트를 포함하세요:

app/page.js

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

이벤트 보내기

sendGTMEvent 함수를 사용하여 dataLayer 객체를 통해 이벤트를 보내 페이지에서 사용자 상호작용을 추적할 수 있습니다. 이 함수가 작동하려면 <GoogleTagManager /> 컴포넌트가 상위 레이아웃, 페이지, 컴포넌트에 포함되어 있거나 동일한 파일에 직접 포함되어 있어야 합니다.

app/page.js

"use client";
 
import { sendGTMEvent } from "@next/third-parties/google";
 
export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent("event", "buttonClicked", { value: "xyz" })}
      >
        이벤트 보내기
      </button>
    </div>
  );
}

함수에 전달할 수 있는 다양한 변수와 이벤트에 대해 알아보려면 태그 관리자 개발자 문서를 참조하세요.

옵션

Google 태그 관리자에 전달할 옵션입니다. 전체 옵션 목록은 Google 태그 관리자 문서를 참조하세요.

이름	타입	설명
`gtmId`	필수	GTM 컨테이너 ID입니다. 일반적으로 `GTM-`으로 시작합니다.
`dataLayer`	선택	컨테이너를 인스턴스화할 때 사용할 데이터 레이어 객체입니다.
`dataLayerName`	선택	데이터 레이어의 이름입니다. 기본값은 `dataLayer`입니다.
`auth`	선택	환경 스니펫의 인증 매개변수(`gtm_auth`) 값입니다.
`preview`	선택	환경 스니펫의 미리보기 매개변수(`gtm_preview`) 값입니다.

Google 애널리틱스

GoogleAnalytics 컴포넌트를 사용하여 Google 태그(gtag.js)를 통해 페이지에 Google 애널리틱스 4를 포함할 수 있습니다. 기본적으로 페이지에서 하이드레이션이 발생한 후 원본 스크립트를 가져옵니다.

권장사항: Google 태그 관리자가 이미 애플리케이션에 포함되어 있다면 Google 애널리틱스를 별도의 컴포넌트로 포함하는 대신 Google 태그 관리자를 직접 사용하여 Google 애널리틱스를 구성할 수 있습니다. 태그 관리자와 gtag.js의 차이점에 대해 자세히 알아보려면 문서를 참조하세요.

모든 경로에 Google 애널리틱스를 로드하려면 루트 레이아웃에 직접 컴포넌트를 포함하고 측정 ID를 전달하세요:

app/layout.tsx

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>
  );
}

app/layout.js

import { GoogleAnalytics } from "@next/third-parties/google";
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  );
}

단일 경로에 Google 애널리틱스를 로드하려면 페이지 파일에 컴포넌트를 포함하세요:

app/page.js

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

이벤트 보내기

sendGAEvent 함수를 사용하여 dataLayer 객체를 통해 이벤트를 보내 페이지에서 사용자 상호작용을 측정할 수 있습니다. 이 함수가 작동하려면 <GoogleAnalytics /> 컴포넌트가 상위 레이아웃, 페이지, 컴포넌트에 포함되어 있거나 동일한 파일에 직접 포함되어 있어야 합니다.

app/page.js

"use client";
 
import { sendGAEvent } from "@next/third-parties/google";
 
export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGAEvent("event", "buttonClicked", { value: "xyz" })}
      >
        이벤트 보내기
      </button>
    </div>
  );
}

이벤트 매개변수에 대해 자세히 알아보려면 Google 애널리틱스 개발자 문서를 참조하세요.

페이지뷰 추적

Google 애널리틱스는 브라우저 히스토리 상태가 변경될 때 자동으로 페이지뷰를 추적합니다. 이는 Next.js 경로 간의 클라이언트 측 탐색이 구성 없이 페이지뷰 데이터를 보낸다는 것을 의미합니다.

클라이언트 측 탐색이 올바르게 측정되고 있는지 확인하려면 관리자 패널에서 "향상된 측정" 속성이 활성화되어 있고 "브라우저 히스토리 이벤트 기반 페이지 변경" 확인란이 선택되어 있는지 확인하세요.

참고: 페이지뷰 이벤트를 수동으로 보내기로 결정한 경우, 중복 데이터를 방지하기 위해 기본 페이지뷰 측정을 비활성화해야 합니다. 자세한 내용은 Google 애널리틱스 개발자 문서를 참조하세요.

옵션

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

이름	타입	설명
`gaId`	필수	측정 ID입니다. 일반적으로 `G-`로 시작합니다.
`dataLayerName`	선택	데이터 레이어의 이름입니다. 기본값은 `dataLayer`입니다.

Google 지도 임베드

GoogleMapsEmbed 컴포넌트를 사용하여 페이지에 Google 지도 임베드를 추가할 수 있습니다. 기본적으로 loading 속성을 사용하여 화면 아래쪽에서 임베드를 지연 로드합니다.

app/page.js

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 지도 임베드에 전달할 옵션입니다. 전체 옵션 목록은 Google 지도 임베드 문서를 참조하세요.

이름	타입	설명
`apiKey`	필수	API 키입니다.
`mode`	필수	지도 모드
`height`	선택	임베드의 높이입니다. 기본값은 `auto`입니다.
`width`	선택	임베드의 너비입니다. 기본값은 `auto`입니다.
`style`	선택	iframe에 스타일을 전달합니다.
`allowfullscreen`	선택	특정 지도 부분을 전체 화면으로 볼 수 있도록 하는 속성입니다.
`loading`	선택	기본값은 lazy입니다. 임베드가 화면 상단에 있다는 것을 알고 있다면 변경을 고려하세요.
`q`	선택	지도 마커 위치를 정의합니다. 지도 모드에 따라 필수일 수 있습니다.
`center`	선택	지도 뷰의 중심을 정의합니다.
`zoom`	선택	지도의 초기 줌 레벨을 설정합니다.
`maptype`	선택	로드할 지도 타일의 유형을 정의합니다.
`language`	선택	UI 요소와 지도 타일 레이블 표시에 사용할 언어를 정의합니다.
`region`	선택	지정 정치적 민감성에 따라 표시할 적절한 경계와 레이블을 정의합니다.

YouTube 임베드

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

app/page.js

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`	선택	비디오 컨테이너에 스타일을 적용하는 데 사용됩니다.

정적 리소스 메모리 사용량