# @convex-internal/web-analytics 中文文档

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

版本：2\.3\.0
npm 元数据更新时间：2026-11-06T22:43:53.671Z
中文译文更新时间：2026-11-10T18:00:11.297Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40convex-internal/web-analytics
原文对照：https://npmcn.com/package/%40convex-internal/web-analytics/?lang=original

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

- 包体积（解压后）：30.6 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，svelte ^5\.0\.0
- 首次发布：2026-08-18T16:13:23.612Z
- 最新版本发布：2026-11-06T22:43:53.401Z
- 近 30 天下载量：10823（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

共享同意状态,同意横幅,以及Convex网站的分析设置.

## 安装

```sh
npm install @convex-internal/web-analytics
```

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

## README

# @convex- 内部/网络分析

共享同意状态,同意横幅,以及Convex网站的分析设置.

## 核心

在根上挂起一个框架条目( R)[反应](https://npmcn.com/package/%40convex-internal/web-analytics/#readme-react) 或者说 [丝绒](https://npmcn.com/package/%40convex-internal/web-analytics/#readme-svelte)) (中文(简体) ). 分析开始生产,除了本地主机. 同意是同步到 后霍格语. 横幅显示访客尚未选择的时间 .

PostHog 已经复制了标准竞选参数( UTMS, `gclid`, (中文(简体) ), `rdt_cid`, (中文(简体) ), `fbclid`,以及其它常见的点击ID)从登陆 URL 到事件。 这个 软件包也抓取 `dub_id`经同意,PostHog创建了一个匿名 人物简介. 此时仍然可用的运动参数可作为 `$initial_*`,在登录前支持人级属性.

### `capture`

通过框架中性根条目从客户端代码记录一个事件. 第三种备选论点是: [PostHog 的抓取选项](https://posthog.com/docs/libraries/js/usage)。 。 。 .

```tsx
import { capture } from "@convex-internal/web-analytics";

capture("www-login", undefined, {
  transport: "sendBeacon",
  send_instantly: true,
});
```

### `getDistinctId`

PostHog 的当前访客标识 。 经同意后 存储在饼干上 `.convex.dev`,所以浏览器中的每个 Convex 网站都使用 同样的身份证.

当此助手返回一个值时, 已经获得同意 。 把身份证传给一个 第三方工具,使您能够匹配该工具的事件或会话,例如 支持聊天,回到PostHog的同一访客.

估计第一个货总能接到呼叫 `undefined`,所以再次打电话 获得同意后.

它返回一个:

-   **`undefined`**后霍格没有初始化(当地主机,不生产,或 或尚未同意。 事先同意,邮电局 仍然有一个没有饼干的ID, 但它不是稳定的跨网站甚至页面 重新装入,所以返回它会产生噪音而不是有用.
-   **匿名 UUID 软件**,例如 `"019a7d8f-9190-7844-a5c0-73d461a3a5d1"`。 。 。 . 已经同意, 但此浏览器尚未登录到 确定用户身份的仪表板.
-   **Convex 配置文件 ID**,例如 `"4281"`已经同意,而且 浏览器已经登录到仪表板上.

### 同意横幅

旗帜可见于何时 `consent` 实值 `"undecided"`中隐藏它 `consent` 实值 `"unknown"`, (中文(简体) ), `"consented"`,或 `"declined"`。 。 。 .

反应和Svelte 接受可选 `hideBanner` 道具,默认为 `false`。 。 。 .

主题 `--wa-banner-*` 变量在 `.wa-banner`数字 :

```css
.wa-banner {
  --wa-banner-background-color: var(--color-seashell);
  --wa-banner-font-family: var(--font-primary);
  --wa-banner-accept-background-color: var(--color-plum-p4);
}
```

-   背景、文本和边框: `--wa-banner-background-color`, (中文(简体) ), `--wa-banner-text-color`, (中文(简体) ), `--wa-banner-border-color`, (中文(简体) ), `--wa-banner-border-radius`, (中文(简体) ), `--wa-banner-box-shadow`, (中文(简体) ), `--wa-banner-backdrop-filter`
-   类型和布局 : `--wa-banner-font-family`, (中文(简体) ), `--wa-banner-font-size`, (中文(简体) ), `--wa-banner-padding`, (中文(简体) ), `--wa-banner-max-width`, (中文(简体) ), `--wa-banner-action-gap`, (中文(简体) ), `--wa-banner-z-index`
-   链接和重点: `--wa-banner-link-color`, (中文(简体) ), `--wa-banner-focus-color`
-   按钮 : `--wa-banner-button-border-radius`, (中文(简体) ), `--wa-banner-button-padding`, (中文(简体) ), `--wa-banner-button-min-height`, (中文(简体) ), `--wa-banner-button-font-size`, (中文(简体) ), `--wa-banner-button-font-weight`
-   接受按钮 : `--wa-banner-accept-background-color`, (中文(简体) ), `--wa-banner-accept-text-color`
-   降低按钮 : `--wa-banner-decline-background-color`, (中文(简体) ), `--wa-banner-decline-text-color`

按键默认为80%不透明,并在悬浮或键盘焦点上达到100%.

### 同意事件

`cookie_consent_shown` 当旗帜出现时记录. `cookie_consent_decided` 记录为 `{ decision: "accepted" | "declined", source: "banner" }` 刚刚之前 选择被保存,并且 `{ decision: "declined", source: "gpc" }` 何时 gPC优先适用. 没有历史事件 `source` 是横幅 决定.

### Cookie 行为

饼干一读完, `consent` 按此顺序解决:

1.  **全球隐私控制.** 若为 `navigator.globalPrivacyControl === true`, (中文(简体) ), `consent` 实值 `"declined"`。GPC 不存储: cookie 不写入或 已更改。 关闭 GPC , 并再次应用存储的 cookie( 如果设置) .
2.  **饼干.** `true` 实值 `"consented"`, (中文(简体) ), `false` 实值 `"declined"`和缺失 或未识别值为 `"undecided"`。 。 。 .

饼干是用 `path=/` 最多一年的年龄 打开 `convex.dev` 财务报告和审定财务报表 `*.convex.dev` 也设定为 `domain=.convex.dev` 所以网站, Docs, Stack, 和其他子域共用一个选择. 饼干是标记的 `Secure` 除了本地主机 到处都是.

通过 `setConsent` 立即更新。 作出的改动 其他地方,如在另一个标签或 DevTools 中,通过 cookie 同步 当可用时更改事件, 当窗口重起焦点或重起焦点时 可见度作为倒数变化.

## 反应

从 `@convex-internal/web-analytics/react`。 。 。 . `WebAnalyticsProvider` 是客户端组件. `useConsent` 调用时抛出 在供货商之外.

```tsx
import { WebAnalyticsProvider } from "@convex-internal/web-analytics/react";

<WebAnalyticsProvider>{children}</WebAnalyticsProvider>;
```

例如,将横幅隐藏在 `/start` 财务报告和审定财务报表 `/login` 在 Next.js 中重定向页面:

```tsx
"use client";

import { WebAnalyticsProvider } from "@convex-internal/web-analytics/react";
import { usePathname } from "next/navigation";
import type { ReactNode } from "react";

export function Analytics({ children }: { children: ReactNode }) {
  const pathname = usePathname();

  return (
    <WebAnalyticsProvider hideBanner={["/start", "/login"].includes(pathname)}>
      {children}
    </WebAnalyticsProvider>
  );
}
```

### `Consented`

只有在 `consent` 实值 `"consented"`。它不会在 苏维埃社会主义共和国,虽然同意仍然 `"unknown"` 或者说 `"undecided"`如果访客 已放弃,或正在启动全球隐私控制.

```tsx
import { Consented } from "@convex-internal/web-analytics/react";

<Consented>
  <YourAnalyticsScripts />
</Consented>;
```

### `useConsent`

-   `consent` (单位:千美元)`ConsentStatus`(中文(简体) )
    -   `"unknown"` 直到cookie被读取( SSR 和第一个客户端渲染)
    -   `"undecided"` 之后,如果还没有公认的选择
    -   `"consented"` 如果饼干是 `true` 未设置 GPC
    -   `"declined"` 如果饼干是 `false` 或 GPC 设定
-   `setConsent("consented" | "declined")`
    -   将选择保存到 `allowsCookies` 饼干和更新上下文
    -   不要自己写饼干

需要时使用钩子 `consent` 或者说 `setConsent` 直接说 启用跟踪 仅在 `consent === "consented"`。 。 。 .

## 丝绒

Svelte 仅出口条目 `WebAnalytics`把它放入根部一次 设置。 它从PostHog开始,并展示出旗帜. 没有 `Consented` 包装或同意店。 可在稍后添加这些内容; 用斯维尔特的入口 还没有需要它们.

```svelte
<script>
  import { WebAnalytics } from "@convex-internal/web-analytics/svelte";
</script>

<WebAnalytics />
```

## 测试开发中的变化

1.  在那个 `web-analytics` 重播、 构建和包装软件包 :

```bash
cd /path/to/web-analytics
npm run build
npm pack
```

这造出一个柏油球 `convex-internal-web-analytics-1.0.0.tgz`。 。 。 .

1.  在消费应用程序中安装焦油:

```bash
cd /path/to/consuming-app
npm install /path/to/web-analytics/convex-internal-web-analytics-1.0.0.tgz --force
```

`--force` 确保在文件名和版本有时 npm 刷新软件包 未改变.

## 向 npm 发布版本

1.  确认您已签入 npm 账户并访问 `@convex-internal` 组织:

```bash
npm whoami
```

运行 `npm login` 首先,如果需要的话.

1.  提交任何 README 或代码更改,然后折叠版本 . `npm version` 需要一个干净的 Git 工作树, 并创建版本承诺和标记 .

```bash
npm version major   # breaking, or 0.x → 1.0.0
npm version minor   # new backwards-compatible functionality
npm version patch   # bug fixes
```

1.  运行测试,检查包的内容,然后发布. `.npmrc` 套装 `ignore-scripts=true`这样 `prepack` 将不会运行——先建:

```bash
npm test
npm run build
npm pack --dry-run
npm publish
```

## 获取已出版的版本

Convex repos 常规设置 `min-release-age=7` 内 `.npmrc`,所以是一个版本 在过去7天中公布将无法安装。 覆盖窗口 一个安装 :

```bash
npm install @convex-internal/web-analytics@<version> --min-release-age=0
```

当您需要测试更改时, 请使用本地的 tarball 工作流程 尚未公布.

## 常见问题

### @convex-internal/web-analytics 是什么？

共享同意状态,同意横幅,以及Convex网站的分析设置\.

### 如何安装 @convex-internal/web-analytics？

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

### @convex-internal/web-analytics 支持 TypeScript 吗？

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

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

@convex-internal/web-analytics 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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