Clarity - Nuxt Scripts 中文文档

Clarity 是微软提供的一款屏幕录制和热图工具，帮助你了解用户如何与网站交互。

Nuxt Scripts 提供了一个注册脚本组合式函数 useScriptClarity，让你可以轻松地在 Nuxt 应用中集成 Clarity。

在 Nuxt 应用中全局加载 Clarity 的最简单方式是通过 Nuxt 配置。或者你也可以直接使用 useScriptClarity 组合式函数。

全局加载

如果你不打算发送自定义事件，可以使用环境覆盖来在开发环境中禁用脚本。

export default defineNuxtConfig({
  scripts: {
    registry: {
      clarity: {
        id: 'YOUR_ID'
      }
    }
  }
})

export default defineNuxtConfig({
  $production: {
    scripts: {
      registry: {
        clarity: {
          id: 'YOUR_ID',
        }
      }
    }
  }
})

export default defineNuxtConfig({
  scripts: {
    registry: {
      clarity: true,
    }
  },
  // 你需要提供运行时配置以访问环境变量
  runtimeConfig: {
    public: {
      scripts: {
        clarity: {
          // .env 文件中
          // NUXT_PUBLIC_SCRIPTS_CLARITY_ID=<your-id>
          id: '',
        },
      },
    },
  },
})

useScriptClarity

useScriptClarity 组合式函数允许你精细控制 Clarity 在你的网站上何时及如何加载。

const { proxy } = useScriptClarity({
  id: 'YOUR_ID'
})
// 示例
proxy.clarity("identify", "custom-id", "custom-session-id", "custom-page-id", "friendly-name")

请参阅注册脚本指南以了解更多高级用法。

ClarityApi

type ClarityFunctions = ((fn: 'start', options: { content: boolean, cookies: string[], dob: number, expire: number, projectId: string, upload: string }) => void)
  & ((fn: 'identify', id: string, session?: string, page?: string, userHint?: string) => Promise<{
  id: string
  session: string
  page: string
  userHint: string
}>)
  & ((fn: 'consent') => void)
  & ((fn: 'set', key: any, value: any) => void)
  & ((fn: 'event', value: any) => void)
  & ((fn: 'upgrade', upgradeReason: any) => void)
  & ((fn: string, ...args: any[]) => void)

export interface ClarityApi {
  clarity: ClarityFunctions & {
    q: any[]
    v: string
  }
}

配置 Schema

首次设置脚本时必须提供选项。

export const ClarityOptions = object({
  /**
   * Clarity 令牌。
   */
  id: pipe(string(), minLength(10)),
})

First-Party 模式

该脚本支持 First-Party 模式，此模式通过你的域名路由所有流量，以提升隐私性及绕过广告拦截。

当通过 scripts.firstParty: true 全局启用时，该脚本将：

从你的域名加载，而非 www.clarity.ms
通过你的服务器路由数据/事件收集（d.clarity.ms, e.clarity.ms）
对 IP 地址、语言和硬件指纹（canvas、webgl、浏览器版本）进行匿名化处理
保留 User-Agent、屏幕分辨率和时区，以便生成准确的热图和设备过滤

nuxt.config.ts

export default defineNuxtConfig({
  scripts: {
    firstParty: true,
    registry: {
      clarity: { id: 'YOUR_ID' }
    }
  }
})

如果想针对特定脚本选择退出：

useScriptClarity({
  id: 'YOUR_ID',
  scriptOptions: {
    firstParty: false // 直接从微软加载
  }
})

示例

仅在生产环境使用 Clarity，同时使用 clarity 发送转化事件。

<script setup lang="ts">
const { proxy } = useScriptClarity()

// 在开发环境和 SSR 中无操作
// 在生产环境和客户端正常工作
function sendConversion() {
  proxy.clarity('event', 'conversion')
}
</script>

<template>
  <div>
    <button @click="sendConversion">
      发送转化事件
    </button>
  </div>
</template>

YouTube 播放器

在您的 Nuxt 应用中展示性能优化的 YouTube 视频。

Hotjar

在你的 Nuxt 应用中使用 Hotjar。