跳至內容
建置您的應用程式 (Building Your Application)...優化 (Optimizing)...第三方程式庫 (Third Party Libraries)

第三方函式庫

@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 代碼管理工具，請將元件直接包含在您的根佈局中，並傳入您的 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 代碼管理工具，請將元件包含在您的頁面檔案中

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

發送事件
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>
  )
}

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

伺服器端標記

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

選項 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，請直接在您的根佈局中包含該元件，並傳入您的評估 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" />
}

發送事件
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 開發人員文件，以瞭解更多資訊。

選項
名稱類型說明
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 地圖文件。

名稱類型說明
apiKey必填您的 API 金鑰。
mode必填地圖模式
height選用嵌入內容的高度。預設為 auto（自動）。
width選用嵌入內容的寬度。預設為 auto（自動）。
style選用將樣式傳遞給 iframe。
allowfullscreen選用允許地圖的某些部分全螢幕顯示的屬性。
loading選用預設為延遲載入。如果您知道嵌入內容會在螢幕上方顯示，請考慮更改此設定。
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選用用於套用影片容器的樣式。