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://#`	事件将发送到的 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 跟踪器重写贡献