Nuxt Plausible module

Nuxt Plausible

功能特色

🌻 無需配置
📯 使用 composables 手動追蹤事件和頁面瀏覽
🔀 可選的 API 代理，以避免廣告阻擋器
📂 .env 檔案支援
🧺 合理的預設選項
🦾 支援 SSR

設定

npx nuxi@latest module add plausible

基本用法

將 @nuxtjs/plausible 添加到 Nuxt 設定的 modules 區段

// `nuxt.config.ts`
export default defineNuxtConfig({
  modules: ['@nuxtjs/plausible'],
})

完成！Plausible 現在將在您的應用程式客戶端中執行。

!提示預設情況下，@nuxtjs/plausible 將使用 window.location.hostname 作為 Plausible domain 配置鍵，這應該適用於大多數使用案例。如果您需要自訂網域，可以在模組選項中進行設定。

配置

所有支援的模組選項都可以使用 Nuxt 設定中的 plausible 鍵進行配置

export default defineNuxtConfig({
  modules: ['@nuxtjs/plausible'],

  plausible: {
    // Prevent tracking on localhost
    ignoredHostnames: ['localhost'],
  },
})

!提示要允許在 localhost 上追蹤事件，請將 ignoredHostnames 選項設定為空陣列。

執行時配置

或者，利用自動替換的公開執行時配置值，方法是在執行時匹配環境變數，在您的專案 .env 檔案中設定您想要的選項

# Sets the `plausible.domain` option to `example.com`
NUXT_PUBLIC_PLAUSIBLE_DOMAIN=example.com

透過此設定，您可以省略 Nuxt 設定中的 plausible 鍵。

代理配置

該模組提供了一個代理 API 功能，允許您透過您的 Nitro 伺服器路由 Plausible 事件，而不是將它們直接發送到 Plausible 的伺服器。如果您想防止廣告阻擋器阻止對 Plausible 網域的請求，這會很有用。當啟用代理時，追蹤器將自動透過目前的來源路由請求。

若要啟用代理 API，請將 proxy 選項設定為 true

export default defineNuxtConfig({
  modules: ['@nuxtjs/plausible'],

  plausible: {
    proxy: true,
  },
})

!注意啟用後，所有 Plausible 事件將先傳送到您的伺服器，然後伺服器再將它們轉發到 Plausible 的 API。預設的代理端點是 /_plausible，但您可以使用 proxyBaseEndpoint 模組選項自訂路徑。

模組選項

選項	類型	預設值	描述
`enabled`	`boolean`	`true`	是否應啟用追蹤器。
`hashMode`	`boolean`	`false`	當 URL 雜湊變更時，是否應追蹤頁面瀏覽。如果您的 Nuxt 應用程式使用 `hashMode` 路由器選項而不是預設的歷史模式，請啟用此選項。
`domain`	`string`	`'window.location.hostname'`	要將追蹤事件綁定到的網域。
`ignoredHostnames`	`string[]`	`['localhost']`	追蹤事件時要忽略的主機名稱。
`ignoreSubDomains`	`boolean`	`false`	如果主機名稱是 `ignoredHostnames` 的子網域，則忽略該主機名稱。
`apiHost`	`string`	`https://127.0.0.1`	事件將傳送到的 API 主機。
`autoPageviews`	`boolean`	`true`	自動追蹤目前頁面和所有後續頁面。如果您想要手動管理頁面瀏覽追蹤，請停用此選項。
`autoOutboundTracking`	`boolean`	`false`	自動追蹤所有對外連結點擊。如果啟用，則 MutationObserver 會自動偵測整個應用程式的連結節點，並將 `click` 事件繫結到它們。
`logIgnoredEvents`	`boolean`	`false`	如果事件被忽略，則將事件記錄到主控台。
`proxy`	`boolean`	`false`	是否透過目前的來源代理事件端點。
`proxyBaseEndpoint`	`string`	`'/_plausible'`	用於透過代理傳送 Plausible 事件端點的基本端點。

Composables

與 Nuxt 生態系統中的其他 composables 一樣，它們是自動匯入的，並且可以在您應用程式的元件中使用。

!注意由於 Plausible 實例僅在客戶端中可用，因此在伺服器上執行 composables 將不會有任何效果。

`useTrackEvent`

追蹤自訂事件。透過傳遞目標名稱作為引數 eventName 來追蹤您定義的目標。

類型宣告

function useTrackEvent(
  eventName: string,
  options?: EventOptions,
  eventData?: PlausibleOptions,
): void

範例

// Tracks the `signup` goal
useTrackEvent('signup')

// Tracks the `Download` goal passing a `method` property.
useTrackEvent('Download', { props: { method: 'HTTP' } })

`useTrackPageview`

手動追蹤頁面瀏覽。

傳遞可選的事件資料以使用 eventData 引數傳送。預設為目前頁面的資料，與 Plausible 初始化期間提供的預設選項合併。

類型宣告

function useTrackPageview(
  eventData?: PlausibleOptions,
  options?: EventOptions,
): void

💻 開發

複製此儲存庫
使用 corepack enable 啟用 Corepack
使用 pnpm install 安裝相依性
執行 pnpm run dev:prepare
使用 pnpm run dev 啟動開發伺服器

鳴謝

@Barbapapazes 的 Plausible 追蹤器重寫