@ doist/ 交互跟踪

用于跟踪用户互动的性能监测库 互动到下一张图 (INP) 财务报告和审定财务报表 长动画框架( LOAF). 特征声明痕量签名和可插件报告.

安装

npm install @doist/interaction-trace

使用量

初始化监视器

import { initInteractionTraceMonitor } from '@doist/interaction-trace'

const cleanup = initInteractionTraceMonitor({
    reporter: (report) => {
        // Send to your analytics service
        console.log('Trace report:', report)
    },
    enrollment: {
        sampleRate: 10, // 10% of sessions
        isEnabled: () => {
            if (user.isInternal) return true    // force enable for internal users
            return undefined                     // everyone else: use sampleRate
        },
    },
    abortSignal: controller.signal, // Optional: auto-cleanup when aborted
})

// Or call cleanup() manually when done

签名追踪

微量测量从用户点击到浏览器完成所有视觉更新的时间. 追踪自动创建于 pointerup 事件-使用 signInteractionTrace() 以说明和提供有待追踪的细节.

import { signInteractionTrace } from '@doist/interaction-trace'

button.addEventListener('click', () => {
    signInteractionTrace('open modal', { modalId: 'settings' })
    openModal()
})

类型脚本

创建用于编译时间验证微量名称和细节的预型函数 :

import { signInteractionTrace } from '@doist/interaction-trace'

type MyTraces = {
    'open modal': { modalId: string }
    'submit form': { formId: string }
}

const signAppTrace = signInteractionTrace.withTypes<MyTraces>()

signAppTrace('open modal', { modalId: 'settings' })   // ✅ Works
signAppTrace('opne modal', { modalId: 'settings' })   // ❌ Error: typo caught
signAppTrace('open modal', { formId: 'x' })           // ❌ Error: wrong details

反应集成

import { useInteractionTrace } from '@doist/interaction-trace/react'

function SettingsModal() {
    useInteractionTrace('open modal', { modalId: 'settings' })
    return <div>...</div>
}

类型脚本

import { useInteractionTrace } from '@doist/interaction-trace/react'

type MyTraces = {
    'open modal': { modalId: string }
    'submit form': { formId: string }
}

const useAppTrace = useInteractionTrace.withTypes<MyTraces>()

function SettingsModal() {
    useAppTrace('open modal', { modalId: 'settings' })
    return <div>...</div>
}

配置

注册选项

记者界面

记者收到 TraceReport 对象 :

type TraceReport = {
    id: string                        // Unique trace ID (crypto.randomUUID())
    duration: number                  // Total LoAF duration (ms)
    inp: number | undefined           // INP value if captured (ms)
    details: {
        name: string                  // Trace name from signInteractionTrace()
        [key: string]: unknown        // Additional details
    }
    device: {
        memoryGB: string              // Bucketed: "0.25-2", "3-7", "8-plus", or "unknown"
        cpuCores: string              // Bucketed: "1-8", "9-16", "17-plus"
    }
}

浏览器支持

长动画框架和事件时间API需要Chrome 123+. 在不支持的浏览器中,显示器默默无声——你的应用程序继续正常工作,只是没有微量收集.

已知的限制

键盘交互

此库只跟踪基于指针的交互( Q)pointerup 活动)。 键盘启动的交互(例如,按 Enter 键以提交窗体,Space to checkbox)不被捕获. INP 度量衡只会反映鼠标/触碰相互作用.

如果您的应用程序有显著的键盘用法,请在解释所收集的度量时考虑这一点.

发展

发展需要节点.js 22.18.0(见 .node-version) (中文(简体) ).

npm install
npm run build
npm test

释放

这个项目使用 请放行 自动释放。 提交合并为 main 与 fix: 触发补丁释放, feat: 引发轻微释放 feat!: 或者说 fix!: 触发主要释放.

当在 main,释放 - 请创建释放 PR。 将它合并到 npm 和 GitHub 套件 .

许可证

释放 MIT 许可证。 。 。 .