快速开始

5 分钟把 @tripo3d/lens 接入应用。本页只走一条最短可跑路径——先跑通、有反馈，原理留到 核心概念。

跟着做你将完成：

1. 安装并构造一个 TripoLens 实例，确认初始化成功
2. 开启行为埋点，给一个按钮加一处声明式埋点
3. 用 DevTools 扩展 看到这处埋点（以及它的上报）

前置：一个能跑的前端工程（Vite / Vue / React 均可）、Node 18+、Chrome。已用 Nuxt？可直接看 Nuxt 接入 的零接线方式。

1. 安装

pnpm

pnpm add @tripo3d/lens

npm

npm install @tripo3d/lens

yarn

yarn add @tripo3d/lens

私有 registry 认证见 安装与导入。

2. 构造并初始化

新建一个 lens.ts，在里面构造实例。务必在应用入口最早处（任何路由 / URL 改写之前）求值——归因要快照入口 URL：

// lens.ts
import { TripoLens, TrackingPlugin } from '@tripo3d/lens';

export const trace = new TripoLens({
  // 事件前缀，决定上报类型段
  app: 'tripo',
  // 换成你们的远程配置地址
  configUrl: 'https://cdn.example.com/lens/config.json',
  // 上报地址（必传，换成你们的真实网关）
  endpoint: 'https://your-gateway.example.com/v2/trace/events',
  // 开启行为自动采集
  plugins: [
    new TrackingPlugin({ autoTrack: true })
  ], 
  // 生命周期：上报时触发
  onReported: (type) => {
    console.log('[lens] 已上报', type)
  }, 
});

// 解析 device id + 装配插件 + 首访归因
void trace.init();

在应用入口（如 main.ts）第一行导入它，触发求值：

import './lens';

刷新页面，打开浏览器控制台。确认初始化成功——init() 完成后 deviceId 应为非空字符串：

import { trace } from './lens';

// 非空即成功
trace.init().then(
  () => {
    console.log('deviceId =', trace.deviceId)
  }
);

为什么可以再调一次 init()

init() 是幂等的——重复或并发调用都复用同一个初始化 promise，不会二次装配；上面这段只是借它拿到「初始化完成」的时机。另外 init() 完成前 trace.deviceId 是空串、trace.headers 是 {}。详见 初始化。

3. 加一处埋点

给页面里任意按钮加 data-trace* 属性，声明一个点击埋点（坐标 home.quickstart.hello）：

<button
  data-trace="home.quickstart.hello"
  data-trace-type="click"
>
  点我
</button>

用 Vue / React？改用声明式语法，效果相同。注意需先完成框架接线：v-trace 要先按 Vue 接入 用 @tripo3d/lens/vue 注册插件；useTraceProps 从 @tripo3d/lens/react 导入（详见 React 接入）：

Vue

<button
  v-trace="{
    path: 'home.quickstart.hello',
    on: 'click'
  }"
>
  点我
</button>

React

<button 
  {...useTraceProps({
    path: 'home.quickstart.hello',
    on: 'click'
  })}
>
  点我
</button>

坐标怎么拼、有哪些规则，见 行为埋点。

4. 看到它

装上 DevTools 扩展（构建后加载到 Chrome），然后：

1. 按 F12 打开 DevTools，切到 Tripo Lens 面板。
2. 点工具栏「扫描元素」——右侧「追踪元素」列出你刚加的 home.quickstart.hello。这一步不依赖网络，是埋点已生效的最直接证据。
3. 开着面板点一下按钮——若上报地址可达，左侧「事件流」会出现一条 click，点开可看完整信封。

事件流空着？多半是上报地址不可达

示例 configUrl / endpoint 都是占位地址，fetch 失败时事件会被静默转存离线，事件流自然看不到。这不代表没埋上——「扫描元素」能看到坐标就说明埋点生效了。换成可达地址即可看到上报，详见 排查：没有上报。

🎉 看到「追踪元素」里的坐标，你就跑通了 lens 的最小闭环。

下一步

• 按框架接入：Vue · React · Nuxt
• 看懂在做什么：架构总览 · 事件的一生
• 用全能力：行为埋点 · 错误收集 · 性能收集
• 没看到上报：排查：没有上报