Nuxt Plausible
为 Nuxt 原生集成 Plausible Analytics。
特性
- 🌻 无需配置
- 📯 使用 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
作为 Plausibledomain
配置键,这应该适用于大多数用例。 如果你需要自定义域名,你可以在模块选项中进行自定义。
配置
所有受支持的模块选项都可以使用 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 | boolean | 当 URL 哈希值更改时,是否应跟踪页面浏览量。 如果你的 Nuxt 应用程序使用 hashMode 路由器选项而不是默认的历史模式,请启用此选项。 |
domain | string | 'window.location.hostname' | 将跟踪事件绑定到的域。 |
ignoredHostnames | string[] | ['localhost'] | 跟踪事件时要忽略的主机名。 |
ignoreSubDomains | boolean | boolean | 如果主机名是 ignoredHostnames 的子域名,则忽略该主机名。 |
apiHost | string | string | https://127.0.0.1 |
事件将发送到的 API 主机。 | boolean | true | autoPageviews |
boolean | boolean | boolean | 自动跟踪当前页面和所有后续页面。 如果你想手动管理页面浏览量跟踪,请禁用此选项。 |
autoOutboundTracking | boolean | boolean | boolean |
自动跟踪所有出站链接点击。 如果启用,MutationObserver 会自动检测整个应用程序中的链接节点,并将 | boolean | boolean | logIgnoredEvents |
boolean | string | 如果忽略事件,则将事件记录到控制台。 | proxy |
boolean
是否通过当前源代理事件端点。
proxyBaseEndpoint
string
'/_plausible'
通过其代理 Plausible 事件端点的基本端点。
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' } })
与 Nuxt 生态系统中的其他组合式一样,它们是自动导入的,可以在你的应用程序的组件中使用。
!注意 由于 Plausible 实例仅在客户端可用,因此在服务器上执行组合式将不会产生任何影响。
useTrackEvent
通过其代理 Plausible 事件端点的基本端点。
function useTrackPageview(
eventData?: PlausibleOptions,
options?: EventOptions,
): void
跟踪自定义事件。 通过将目标的名称作为参数 eventName
传递来跟踪你定义的目标。
- 类型声明
- 示例
- useTrackPageview
- 手动跟踪页面浏览量。
- 传递可选的事件数据以与
eventData
参数一起发送。 默认为当前页面的数据与 Plausible 初始化期间提供的默认选项合并。
💻 开发
- 克隆此存储库
使用 corepack enable
启用 Corepack
使用 pnpm install
安装依赖项