第三方函式庫

@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 匯入。

Google Tag Manager

GoogleTagManager 組件可用於將 Google Tag Manager 容器實例化到你的頁面。預設情況下，它會在頁面發生 hydration 後抓取原始的內嵌腳本。

若要為所有路由載入 Google Tag Manager，請將組件直接包含在你的根版面配置中，並傳入你的 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>
  )
}

若要為單一路由載入 Google Tag Manager，請將組件包含在你的頁面檔案中

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' })}
      >
        Send Event
      </button>
    </div>
  )
}

請參閱 Tag Manager 開發人員文件，以瞭解可以傳遞到函式中的不同變數和事件。

伺服器端標記

如果你正在使用伺服器端標記管理器，並從你的標記伺服器提供 gtm.js 腳本，你可以使用 gtmScriptUrl 選項來指定腳本的 URL。

選項

要傳遞給 Google Tag Manager 的選項。如需選項的完整清單，請閱讀 Google Tag Manager 文件。

名稱	類型	描述
`gtmId`	必填	你的 GTM 容器 ID。通常以 `GTM-` 開頭。
`gtmScriptUrl`	選填	GTM 腳本 URL。預設為 `https://127.0.0.1/gtm.js`。
`dataLayer`	選填	用於實例化容器的資料層物件。
`dataLayerName`	選填	資料層的名稱。預設為 `dataLayer`。
`auth`	選填	環境程式碼片段的驗證參數 (`gtm_auth`) 值。
`preview`	選填	環境程式碼片段的預覽參數 (`gtm_preview`) 值。

Google Analytics

GoogleAnalytics 組件可用於透過 Google 標籤 (gtag.js) 將 Google Analytics 4 新增到你的頁面。預設情況下，它會在頁面發生 hydration 後抓取原始腳本。

建議：如果你的應用程式中已包含 Google Tag Manager，你可以直接使用它來設定 Google Analytics，而不是將 Google Analytics 作為單獨的組件包含進來。請參閱文件以瞭解更多關於 Tag Manager 和 gtag.js 之間差異的資訊。

若要為所有路由載入 Google Analytics，請將組件直接包含在你的根版面配置中，並傳入你的評估 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>
  )
}

若要為單一路由載入 Google Analytics，請將組件包含在你的頁面檔案中

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' })}
      >
        Send Event
      </button>
    </div>
  )
}

請參閱 Google Analytics 開發人員文件，以瞭解更多關於事件參數的資訊。

追蹤頁面瀏覽量

當瀏覽器歷史記錄狀態變更時，Google Analytics 會自動追蹤頁面瀏覽量。這表示 Next.js 路由之間的用戶端導航將在沒有任何設定的情況下發送頁面瀏覽量資料。

為了確保正確衡量用戶端導航，請驗證你的管理員面板中是否已啟用「加強型衡量」屬性，並且已選取「依據瀏覽器歷史記錄事件的頁面變更」核取方塊。

注意：如果你決定手動發送頁面瀏覽量事件，請確保停用預設的頁面瀏覽量衡量，以避免重複資料。請參閱 Google Analytics 開發人員文件以瞭解更多資訊。

選項

要傳遞給 <GoogleAnalytics> 組件的選項。

名稱	類型	描述
`gaId`	必填	你的評估 ID。通常以 `G-` 開頭。
`dataLayerName`	選填	資料層的名稱。預設為 `dataLayer`。
`nonce`	選填	Nonce。

Google Maps 嵌入

GoogleMapsEmbed 組件可用於將 Google Maps 嵌入新增到你的頁面。預設情況下，它會使用 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 Maps 嵌入的選項。如需選項的完整清單，請閱讀 Google Map Embed 文件。

名稱	類型	描述
`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`	選填	此處定義的影片播放器參數 here。參數以查詢參數字串形式傳遞。例如：`params="controls=0&start=10&end=30"`
`style`	選填	用於將樣式套用到影片容器。