plausible
@nuxtjs/plausible

用于原生集成 Plausible analytics 的 Nuxt 模块

Nuxt Plausible module

Nuxt Plausible

npm version

Nuxt 原生集成 Plausible Analytics

功能

  • 🌻 无需配置
  • 📯 使用 可组合项 手动跟踪事件和页面浏览
  • 🔀 可选的 API 代理以避免广告拦截器
  • 📂 .env 文件支持
  • 🧺 合理的默认选项
  • 🦾 SSR-ready

设置

npx nuxi@latest module add plausible

基本用法

@nuxtjs/plausible 添加到 Nuxt 配置的 modules 部分

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

完成!Plausible 现在将在你的应用程序客户端中运行。

!TIP 默认情况下,@nuxtjs/plausible 将使用 window.location.hostname 作为 Plausible 的 domain 配置键,这应该适用于大多数用例。如果你需要自定义域,可以在模块选项中进行。

配置

所有 支持的模块选项 都可以使用 Nuxt 配置中的 plausible 键进行配置

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

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

!TIP 要允许在 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,
  },
})

!NOTE 启用后,所有 Plausible 事件将首先发送到你的服务器,然后服务器将其转发到 Plausible 的 API。默认的代理端点是 /_plausible,但你可以使用 proxyBaseEndpoint 模块选项自定义路径。

模块选项

选项类型默认描述
enabledbooleantrue是否启用跟踪器。
hashModebooleanfalse当 URL 哈希改变时是否跟踪页面浏览。如果你的 Nuxt 应用使用 hashMode 路由器选项而不是默认的历史模式,请启用此项。
domainstring'window.location.hostname'绑定跟踪事件的域。
ignoredHostnamesstring[]['localhost']跟踪事件时要忽略的主机名。
ignoreSubDomainsbooleanfalse如果主机名是 ignoredHostnames 的子域,则忽略该主机名。
apiHoststringhttps://#事件将发送到的 API 主机。
autoPageviewsbooleantrue自动跟踪当前页面和所有后续页面。如果你想手动管理页面浏览跟踪,请禁用此项。
autoOutboundTrackingbooleanfalse自动跟踪所有出站链接点击。如果启用,MutationObserver 将自动检测应用程序中的链接节点并为其绑定 click 事件。
logIgnoredEventsbooleanfalse如果事件被忽略,则将其记录到控制台。
proxybooleanfalse是否通过当前来源代理事件端点。
proxyBaseEndpointstring'/_plausible'代理 Plausible 事件端点的基本端点。

可组合项

与 Nuxt 生态系统中的其他可组合项一样,它们是自动导入的,可以在应用程序的组件中使用。

!NOTE 由于 Plausible 实例仅在客户端可用,因此在服务器上执行可组合项将无效。

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

💻 开发

  1. 克隆此仓库
  2. 使用 corepack enable 启用 Corepack
  3. 使用 pnpm install 安装依赖
  4. 运行 pnpm run dev:prepare
  5. 使用 pnpm run dev 启动开发服务器

鸣谢

许可证

MIT 许可证 © 2022-PRESENT Johann Schopplich