如何優化第三方函式庫

@next/third-parties 是一個提供元件與工具的函式庫，能提升在 Next.js 應用程式中載入熱門第三方函式庫的效能與開發者體驗。

@next/third-parties 提供的所有第三方整合都經過效能與易用性優化。

開始使用

首先安裝 @next/third-parties 函式庫：

Terminal

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

@next/third-parties 目前是一個處於積極開發階段的實驗性函式庫。在我們持續新增更多第三方整合時，建議安裝最新版或canary標記版本。

Google 第三方服務

所有支援的 Google 第三方函式庫都可從 @next/third-parties/google 匯入。

Google 標籤管理工具

GoogleTagManager 元件可用於在頁面上初始化 Google 標籤管理工具容器。預設情況下，它會在頁面水合後取得原始內嵌腳本。

若要為所有路由載入 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>
  )
}

請參閱標籤管理工具的開發者文件以了解可傳入函式的不同變數與事件。

伺服器端標籤

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

選項

傳遞給 Google 標籤管理工具的選項。完整選項清單請參閱 Google 標籤管理工具文件。

名稱	類型	描述
`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 標籤管理工具，可以直接透過它來設定 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`。
`nonce`	選填	nonce。

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

On this page