第三方函式庫

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

所有由 @next/third-parties 提供的第三方整合都已針對效能和易用性進行了最佳化。

開始使用

開始使用前，請先安裝 @next/third-parties 函式庫

終端機

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

@next/third-parties 目前是一個實驗性的函式庫，仍在積極開發中。我們建議在我們新增更多第三方整合的過程中，使用最新版或canary 旗標進行安裝。

Google 第三方服務

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

Google 代碼管理工具

可以使用 GoogleTagManager 元件將 Google 代碼管理工具容器實例化到您的頁面。預設情況下，它會在頁面上完成水合作用後擷取原始的內嵌程式碼。

要載入所有路由的 Google 代碼管理工具，請直接在您的自訂 _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 代碼管理工具，請在您的頁面檔案中加入元件

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

請參考代碼管理工具的開發人員文件，以瞭解可以傳入函式的不同變數和事件。

伺服器端標記

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

選項

傳遞給 Google 代碼管理工具的選項。如需完整選項列表，請閱讀 Google 代碼管理工具文件。

名稱	類型	說明
`gtmId`	必填	您的 GTM 容器 ID。通常以 `GTM-` 開頭。
`gtmScriptUrl`	選填	GTM 腳本網址。預設為 `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 納入您的網頁。根據預設，它會在頁面上完成水合作用後擷取原始腳本。

建議：如果您的應用程式已包含 Google 代碼管理工具，您可以直接使用它來設定 Google Analytics，而不是將 Google Analytics 作為單獨的元件包含在內。請參閱說明文件，進一步瞭解代碼管理工具和 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 地圖

GoogleMapsEmbed 元件可用於將嵌入的 Google 地圖新增至您的頁面。預設情況下，它使用 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 地圖的選項。如需完整的選項清單，請閱讀 Google 地圖嵌入文件。

名稱	類型	說明
`API 金鑰 (apiKey)`	必填	您的 API 金鑰。
`模式 (mode)`	必填	地圖模式
`高度 (height)`	選填	嵌入內容的高度。預設為 `auto`（自動）。
`寬度 (width)`	選填	嵌入內容的寬度。預設為 `auto`（自動）。
`樣式 (style)`	選填	將樣式傳遞給 iframe。
`允許全螢幕 (allowfullscreen)`	選填	允許地圖的某些部分進入全螢幕模式的屬性。
`載入方式 (loading)`	選填	預設為延遲載入。如果您知道嵌入內容會在畫面摺疊以上，請考慮更改此設定。
`查詢 (q)`	選填	定義地圖標記位置。根據地圖模式，這可能是必需的。
`中心點 (center)`	選填	定義地圖視圖的中心點。
`縮放級別 (zoom)`	選填	設定地圖的初始縮放級別。
`地圖類型 (maptype)`	選填	定義要載入的地圖圖塊類型。
`語言 (language)`	選填	定義用於 UI 元素和地圖圖塊上標籤顯示的語言。
`地區 (region)`	選填	根據地緣政治敏感性，定義要顯示的適當邊界和標籤。

YouTube 嵌入

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" />
}

選項

名稱	類型	說明
`影片 ID (videoid)`	必填	YouTube 影片 ID。
`寬度 (width)`	選填	影片容器的寬度。預設為 `auto`（自動）。
`高度 (height)`	選填	影片容器的高度。預設為 `auto`（自動）。
`播放標籤 (playlabel)`	選填	為了方便存取，播放按鈕的隱藏標籤。
`參數 (params)`	選填	影片播放器參數定義於此處。參數以查詢參數字串的形式傳遞。例如：`params="controls=0&start=10&end=30"`
`樣式 (style)`	選填	用於套用樣式到影片容器。