第三方函式庫

@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 代碼管理工具 (Google Tag Manager)

GoogleTagManager 元件可用於在頁面上初始化 Google 代碼管理工具容器。預設情況下，它會在頁面水合 (hydration) 完成後載入原始內嵌指令碼。

若要為所有路由載入 Google 代碼管理工具，請直接將元件包含在根佈局中並傳入您的 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 代碼管理工具，請將元件包含在頁面檔案中：

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 Analytics (Google 分析)

GoogleAnalytics 元件可用於透過 Google 代碼 (gtag.js) 將 Google Analytics 4 加入頁面。預設情況下，它會在頁面水合完成後載入原始指令碼。

建議：如果您的應用程式中已包含 Google 代碼管理工具，可以直接透過它設定 Google Analytics，而不需另外加入 Google Analytics 元件。請參閱文件了解代碼管理工具與 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，請將元件包含在頁面檔案中：

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 Analytics 開發者文件以了解事件參數的更多資訊。

追蹤頁面瀏覽

當瀏覽器歷史狀態變更時，Google Analytics 會自動追蹤頁面瀏覽。這表示 Next.js 路由之間的用戶端導航將無需任何設定即可傳送頁面瀏覽資料。

為確保正確測量用戶端導航，請在管理面板中確認已啟用「增強型評估」屬性，並選中_「基於瀏覽器歷史事件的頁面變更」_核取方塊。

注意：如果您決定手動傳送頁面瀏覽事件，請務必停用預設的頁面瀏覽評估以避免資料重複。請參閱 Google Analytics 開發者文件以了解更多。

選項

傳遞給 <GoogleAnalytics> 元件的選項。

名稱	類型	說明
`gaId`	必填	您的評估 ID。通常以 `G-` 開頭。
`dataLayerName`	選填	資料層名稱。預設為 `dataLayer`。

Google 地圖嵌入 (Google Maps Embed)

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`	選填	預設為延遲載入。如果您知道嵌入內容會位於摺疊上方，可以考慮變更此設定。
`q`	選填	定義地圖標記位置。根據地圖模式可能需要此參數。
`center`	選填	定義地圖視圖的中心點。
`zoom`	選填	設定地圖的初始縮放級別。
`maptype`	選填	定義要載入的地圖圖塊類型。
`language`	選填	定義用於 UI 元素和地圖圖塊標籤顯示的語言。
`region`	選填	根據地理政治敏感性定義要顯示的適當邊界和標籤。

YouTube 嵌入 (YouTube Embed)

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`	選填	用於套用樣式至影片容器。

On this page