# @builtonveya/analytics-web 中文文档

规范地址：https://npmcn.com/package/%40builtonveya/analytics-web/

版本：4\.0\.4
npm 元数据更新时间：2026-09-29T20:33:56.774Z
中文译文更新时间：2026-11-08T19:40:44.472Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40builtonveya/analytics-web
原文对照：https://npmcn.com/package/%40builtonveya/analytics-web/?lang=original
项目主页：https://github.com/adam-3owl/veya-analytics-api#readme
源码仓库：https://github.com/adam-3owl/veya-analytics-api

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：433 kB，26 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-25T20:36:40.255Z
- 最新版本发布：2026-09-29T20:33:56.562Z
- 近 30 天下载量：3039（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

Veya Analytics SDK for the web - 自动检测页面,产品和推车追踪,供餐厅订购网站使用

## 安装

```sh
npm install @builtonveya/analytics-web
```

也可以使用：`pnpm add @builtonveya/analytics-web`、`yarn add @builtonveya/analytics-web`、`bun add @builtonveya/analytics-web`

## README

# @burnonveya/分析-网络

Veya Analytics SDK为网络服务. 自动检测页面类型、产品印象和推车更改 分批订货 分批订货.

与其核心共享 `@builtonveya/analytics-react-native` (同一事件分类学,同版本行).

## 安装

**npm/ 纱线/ pnpm**

```bash
npm install @builtonveya/analytics-web
```

```ts
import veya from '@builtonveya/analytics-web';

await veya.init({ tenantSlug: 'your-tenant-slug' });
```

**脚本标签** (包装一个自成一体的浏览器捆绑 `window.veya`(中文(简体) )

```html
<script src="https://cdn.jsdelivr.net/npm/@builtonveya/analytics-web@4/dist/veya-analytics.min.js"></script>
<script>
  veya.init({ tenantSlug: 'your-tenant-slug' });
</script>
```

将主线拉入( P)`@4`用于自动补丁更新,或精确的版本(`@4.0.0`为了一个被冻结的建筑.

## 配置

```ts
await veya.init({
  tenantSlug: 'your-tenant-slug',      // required
  endpoint: 'https://analytics.builtonveya.com/v1/events',   // the default
  storeId: 'store-81',                 // if known at init; otherwise call veya.setStore(id, name)
  debug: false,
  autoDetect: true,                    // page-type detection on navigation
  autoTrackProducts: true,             // product impressions
  autoTrackCart: true,                 // cart change detection
  interceptOloApi: false,              // opt-in: patches window.fetch to read Olo order responses
  batchSize: 10,
  flushInterval: 5000,
  sessionTimeout: 1800000,             // 30 minutes
});
```

## 音轨

核心SDK提供的一切 默认导出: `track`, (中文(简体) ), `pageView`, (中文(简体) ), `productView`, (中文(简体) ), `productClick`, (中文(简体) ), `addToCart`, (中文(简体) ), `removeFromCart`, (中文(简体) ), `updateCartQuantity`, (中文(简体) ), `setCart`, (中文(简体) ), `checkoutStart`, (中文(简体) ), `checkoutStep`, (中文(简体) ), `addPaymentInfo`, (中文(简体) ), `checkoutComplete`, (中文(简体) ), `loginAttempt`, (中文(简体) ), `loginSuccess`, (中文(简体) ), `loginFailure`, (中文(简体) ), `logout`, (中文(简体) ), `identify`, (中文(简体) ), `storeSelect`, (中文(简体) ), `setStore`, (中文(简体) ), `search`, (中文(简体) ), `loyaltyLogin`, (中文(简体) ), `rewardView`, (中文(简体) ), `rewardApply`, (中文(简体) ), `rewardRemove`, (中文(简体) ), `promoApply`, (中文(简体) ), `promoRemove`, (中文(简体) ), `setExperiment`, (中文(简体) ), `error`, (中文(简体) ), `flush`, (中文(简体) ), `getSessionId`, (中文(简体) ), `getVisitorId`, (中文(简体) ), `getCustomerId`。 。 。 .

```ts
veya.setStore('81', 'Earthbar Flagship - West Hollywood');
veya.addToCart({ id: 'olo:item:106702642', name: 'The Workout Smoothie', price: 12.95 }, 1);
veya.checkoutComplete({ order_id: '46749…', total: 12.95, items: [...] });
```

`init()` 不止一次,有人在飞行时打过电话 直接解开,所以反应 严格模型的双重效果是无害的.

## 自动事件

| 活动 | 何时 | 属性 |
| --- | --- | --- |
| `session_start` | 每一次新会话——在恢复存储会话时不再重复(30分钟超时内满页) | `platform` |
| `page_view` | 在加载时,在客户端导航时,当页面从浏览器的后/后缓存返回时, **仅使用 `autoDetect: true`** (默认). 与 `autoDetect: false`电话 `veya.pageView()` 自己(恢复起火) `pageshow` 与 `event.persisted === true`(中文(简体) ) | `page_url`, (中文(简体) ), `page_title`, (中文(简体) ), `page_type`, (中文(简体) ), `referrer`, (中文(简体) ), `utm_*` |
| `page_hidden` 编号 : `page_visible` | 标签被隐藏 / 再次显示 | `page_hidden`数字 : `time_on_page` (自上页视图或回放/前移-缓存恢复以来); `page_visible`: 无 |
| `scroll_depth` | 页面被滚动过25 / 50 / 75 / 100% —— 每页浏览一次, 每页浏览一次重置, 并用回/ 后- 前- 缓存恢复; 不滚动的页面不报告任何信息 | `depth` |
| `page_unload` | 页面为左 (`pagehide`: 完全导航, 关闭标签, 或进入后方/ 前方缓存 | `time_on_page`· ; `persisted` —— 说 `true` 当页面进入后方/前方缓存( 可能恢复) 而不是被卸下时 |
| `error` | 未发现错误和未处理的承诺拒绝 | `error_type`, (中文(简体) ), `error_message`,, , , , , , , , |

准确命名的属性 `email`, (中文(简体) ), `phone`, (中文(简体) ), `password`, (中文(简体) ), `ssn`, (中文(简体) ), `credit_card`, (中文(简体) ), `cvv`, (中文(简体) ), `address` 或者说 `street` 从每起事件(以及从 `identify()` 作为反对派遣的后援 个人资料是错的 只有那些精确的顶级密钥: 不要依赖它来捕捉 `delivery_address`, (中文(简体) ), `streetAddress` 或筑巢物体。 允许ZIP / 邮政编码: 发送 `address_postal_code` (5-digital ZIP)用于交付区分析,从不提供街道地址.

## 4.0.4的变动

-   通话 `identify()`, (中文(简体) ), `loginSuccess()`, (中文(简体) ), `logout()` 或者说 `setExperiment()` 在此之前 `init()` 不再存储空会话 ID, 没有 ID 的存储会话则永远不会恢复 。 之前,这种会议的每一起事件 都因失踪而被否决 `session_id`。它们对登录状态的影响和实验只有在 `init()` 开始新的会话,所以请在 `await veya.init()`。 。 。 .

## 4.0.3的变动

-   PII 后站不再下降 `postal_code` 财务报告和审定财务报表 `zip` - 只有街道层面 `address` 财务报告和审定财务报表 `street` (加上现有的电子邮件/电话/密码/SSN/卡/CVV密钥). 一个ZIP已经足够粗糙,可以保留,这就是送货区分析的运行过程;4.0.2随街地址一起掉入.

## 4.0.2的变动

-   `page_unload` 发送于 `pagehide` 改为 `beforeunload`A级 `beforeunload` 收听者不让Firefox将页面放入后/前缓存,因此后方重新装入了页面而不是恢复; `pagehide` 而不是,移动浏览器在关闭标签时更可靠地点出它. 新财产 `persisted`数字 : `true` 当页面进入后方/前方缓存而不是卸载时.
-   从后方/ 前方缓存恢复的页面 `time_on_page` 编辑 `scroll_depth` 阈值,并发送 `page_view` 何时 `autoDetect` 开始 之前,我们.., `time_on_page` 返回从原负载中计数后,滚动深度从此不再开火.
-   PII 后站也会下降 `address`, (中文(简体) ), `street`, (中文(简体) ), `postal_code` 财务报告和审定财务报表 `zip` (4.0.3再保留ZIP键). `query` 刻意不在列表中:搜索事件用于所输入的内容.
-   已删除 `aiEndpoint` 财务报告和审定财务报表 `useAiClassification` 选项:没有读取,以及 `aiEndpoint` 默认为无法解决的主机. 仍然通过它们的TypeScript代码会遇到过量的财产错误;删除它们.

## 4.0.1的变动

-   `session_start` 发送( 它被丢弃的原因是 `init()` 追踪到它,然后自己开始标记),每一次新会话.
-   无自动 `page_view` 与 `autoDetect: false` —— 4. 0.0 在每个负载上都送出一个,除了应用程序自己的.
-   新建自动事件 : `page_hidden` 编号 : `page_visible` 财务报告和审定财务报表 `scroll_depth` (见上文).
-   新方法 : `addPaymentInfo(paymentMethod, properties?)` → `add_payment_info` 与 `{ payment_method }` 在漏斗阶下 `checkout_payment` (四会.
-   卸载发送的页面 `page_unload` 改为 `session_end` (会话贯穿全程导航).
-   默认 : `endpoint` 是现场直播 `https://analytics.builtonveya.com/v1/events` (4.0.0指一个不能解决的宿主); `interceptOloApi` 现在选择进入.
-   同时 `init()` 呼叫共享一个运行,而不是设置听众和发送 `session_start`。 。 。 .

## 服务器侧渲染

导入服务器上的软件包是安全的: 模块只装入登记器 `window.veya` 当 a `window` 存在,直到 `init()` 运行。 打电话 `init()` 客户端 效应.

## 构建和发布( P)

```bash
cd sdk/web
npm ci
npm run build      # dist/esm (ESM + types), dist/cjs, dist/veya-analytics[.min].js
npm run smoke      # loads all three outputs and checks the public surface
npm publish        # prepublishOnly runs build + smoke; scope @builtonveya is public
```

弹出 `version` 内 `package.json` 当共享核心改变时,与 React 本地软件包同步.

## 常见问题

### @builtonveya/analytics-web 是什么？

Veya Analytics SDK for the web - 自动检测页面,产品和推车追踪,供餐厅订购网站使用

### 如何安装 @builtonveya/analytics-web？

在项目目录运行 npm install @builtonveya/analytics-web，或使用 pnpm add / yarn add / bun add。

### @builtonveya/analytics-web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @builtonveya/analytics-web 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @builtonveya/analytics-web 可以商用吗？

@builtonveya/analytics-web 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @builtonveya/analytics-web 的下载量有多少？

根据 npm 官方下载统计，@builtonveya/analytics-web 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,039 次，日均约 101 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @builtonveya/analytics-web 还在维护吗？

最新版本 4\.0\.4 发布于 2026/09/30（1 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。