第三方函式庫

@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，請將組件直接包含在你的自訂 _app 中，並傳入你的 GTM 容器 ID

pages/_app.js

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

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

pages/index.js

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

發送事件

sendGTMEvent 函式可用於追蹤使用者在你頁面上的互動，方法是使用 dataLayer 物件發送事件。為了使此函式運作，<GoogleTagManager /> 組件必須包含在父版面配置、頁面或組件中，或直接包含在同一個檔案中。

pages/index.js

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，請將組件直接包含在你的自訂 _app 中，並傳入你的評估 ID

pages/_app.js

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

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

pages/index.js

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

發送事件

sendGAEvent 函式可用於評估使用者在你頁面上的互動，方法是使用 dataLayer 物件發送事件。為了使此函式運作，<GoogleAnalytics /> 組件必須包含在父版面配置、頁面或組件中，或直接包含在同一個檔案中。

pages/index.js

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 Embed

GoogleMapsEmbed 組件可用於將 Google Maps Embed 新增到你的頁面。預設情況下，它會使用 loading 屬性來延遲載入摺疊下方的嵌入。

pages/index.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 Embed 的選項。如需完整選項列表，請閱讀 Google Map Embed 文件。

名稱	類型	描述
`apiKey`	必填	你的 API 金鑰。
`mode`	必填	地圖模式
`height`	選填	嵌入的高度。預設為 `auto`。
`width`	選填	嵌入的寬度。預設為 `auto`。
`style`	選填	將樣式傳遞到 iframe。
`allowfullscreen`	選填	屬性，允許某些地圖部分進入全螢幕模式。
`loading`	選填	預設為 lazy。如果你知道你的嵌入將在首屏之上，請考慮變更。
`q`	選填	定義地圖標記位置。這可能會根據地圖模式而成為必要項目。
`center`	選填	定義地圖檢視的中心。
`zoom`	選填	設定地圖的初始縮放層級。
`maptype`	選填	定義要載入的地圖圖磚類型。
`language`	選填	定義用於 UI 元素和地圖圖磚標籤顯示的語言。
`region`	選填	根據地緣政治敏感性，定義要顯示的適當邊界和標籤。

YouTube Embed

YouTubeEmbed 組件可用於載入和顯示 YouTube 嵌入。此組件透過在底層使用 lite-youtube-embed 來加快載入速度。

pages/index.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`	選填	用於將樣式套用到影片容器。