# @caravela-studio/glancy-next 中文文档

规范地址：https://npmcn.com/package/%40caravela-studio/glancy-next/

版本：0\.4\.0
npm 元数据更新时间：2026-11-04T17:03:15.342Z
中文译文更新时间：2026-11-09T19:25:32.041Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40caravela-studio/glancy-next
原文对照：https://npmcn.com/package/%40caravela-studio/glancy-next/?lang=original
项目主页：https://github.com/caravela-labs/glancy#readme
源码仓库：https://github.com/caravela-labs/glancy

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

- 包体积（解压后）：30.2 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：next \>=13\.4，react \>=18
- 首次发布：2026-10-23T15:18:39.328Z
- 最新版本发布：2026-11-04T17:03:14.729Z
- 近 30 天下载量：1797（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

从 Next.js 直接发送产品分析到 Glancy

## 安装

```sh
npm install @caravela-studio/glancy-next
```

也可以使用：`pnpm add @caravela-studio/glancy-next`、`yarn add @caravela-studio/glancy-next`、`bun add @caravela-studio/glancy-next`

## README

# @caravela-studio/glancy-next

将产品分析从 Next.js 应用直接发送到 Glancy —— 介于两者之间.

-   **浏览器 :** `<GlancyProvider>` 在每个路由更改时发送页面视图, `useGlancy()` 给你 `track` 编号 : `identify` 编号 : `group` 编号 : `alias` 编号 : `reset`。信件被批量(20个信件或2 s)并冲出 `fetch(keepalive)` 当标签被隐藏或关闭时。 与App路由器和Pages路由器合作.
-   **中间软件 :** `withGlancy()` 从 `@caravela-studio/glancy-next/middleware` 发送页面访问页面负载 (与浏览器共享,因此每个存储一次)和 `API Request` 来自服务器的事件——见 [下级](https://npmcn.com/package/%40caravela-studio/glancy-next/#readme-middleware)。 。 。 .
-   **服务器 :** `glancy()` 从 `@caravela-studio/glancy-next/server` 用于路由处理器、服务器动作和中间软件.
-   **会话重放热映射( H) :** 记录会话以监视它们,并收集点击和滚动深度 每页——见 [下级](https://npmcn.com/package/%40caravela-studio/glancy-next/#readme-session-replay-and-heatmaps)。 。 。 .
-   **两人都有一位访客:** 浏览器的匿名 id 住在 `glancy_anon_id` 饼干,服务器事件 可以绑在它上 `getAnonymousId()`。 。 。 . `identify` 将匿名历史合并到用户.

信件遵循片段的规格, 所以它们看起来和片段已经收到的事件完全一样.

> 不在Next.js上吗? 见 [全部 SDK 软件](https://npmcn.com/package/%40caravela-studio/README.md)数字 : `@caravela-studio/glancy-web` 对于任何网络应用, `glancy.js` 任何地点, 反应土著,斯威夫特和克特林. 此软件包基于 [`@caravela-studio/glancy-web`](https://npmcn.com/package/%40caravela-studio/web)。 。 。 .

## 安装

在 npm 上公开,不需要任何符号 :

```bash
npm install @caravela-studio/glancy-next     # brings @caravela-studio/glancy-web with it
```

`.env.local` 您的应用程序( 写键在桶上) **设置** 页面:

```bash
NEXT_PUBLIC_GLANCY_WRITE_KEY=glc_prod_…
# Only when self-hosting (default https://ingest.heyglancy.com):
# NEXT_PUBLIC_GLANCY_HOST=https://analytics.example.com
```

写出密钥只能将事件加到一桶上,从不读取,所以可以将它运送到浏览器上.

## 浏览器

```tsx
// app/layout.tsx
import { GlancyProvider } from "@caravela-studio/glancy-next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <GlancyProvider>{children}</GlancyProvider>
      </body>
    </html>
  );
}
```

```tsx
"use client";
import { useGlancy } from "@caravela-studio/glancy-next";

export function BuyButton() {
  const analytics = useGlancy();
  return <button onClick={() => analytics.track("Order Completed", { revenue: 42, currency: "EUR" })}>Buy</button>;
}
```

| 方法 | 它传递的 |
| --- | --- |
| `track(event, properties?)` | 一个命名的事件 |
| `page(name?, properties?)` | `Page Viewed` 与 `path`, (中文(简体) ), `url`, (中文(简体) ), `title`, (中文(简体) ), `referrer`, (中文(简体) ), `search` (自动与提供者联系) |
| `identify(userId, traits?)` | 将此浏览器链接到用户并存储配置文件中的特性( 签名后调用) |
| `group(groupId, traits?)` | 将用户与公司/团队联系起来 |
| `alias(userId, previousId?)` | 合并上一个 ID `userId` |
| `reset()` | 忘记用户, 开始一个新的匿名ID和一个新的会话( 呼叫签出) |
| `flush()` | 现在发送队列 |
| `stopRecording()` | 停止会话重放和热映射( 如同意被撤回); 事件继续工作 |
| `getSessionId()` | 页:1 `context.sessionId` 每次活动) |

提供道具: `writeKey`, (中文(简体) ), `host` (对上面的阴道违约), `trackPageViews` (默认) `true`, (中文(简体) ), `flushAt` (20个), `flushInterval` (2000毫秒), `debug` (记录每条消息), `sessionReplay`, (中文(简体) ), `heatmaps`。 。 。 .

每条消息都带着 `context.page`, (中文(简体) ), `userAgent`, (中文(简体) ), `os.name`, (中文(简体) ), `locale`, (中文(简体) ), `timezone` 财务报告和审定财务报表 `screen`,所以崩溃 喜欢 _由OS编辑_ 工作从盒子.

## 会话重放和热映射

两者默认关闭,并打开道具:

```tsx
<GlancyProvider sessionReplay heatmaps>{children}</GlancyProvider>

// or with options
<GlancyProvider sessionReplay={{ sampleRate: 0.25, maskAllText: false }} heatmaps>
```

**会话重放** 将 DOM 记录为 [错误网络](https://github.com/rrweb-io/rrweb) 以压缩的方式发送它 每隔几秒钟就切出一块 监视会议 **重放** 在Glancy(与届会的 或从一个人的简介。 录音机是按要求装入的 所以回放时它不在你的包里 关闭.

-   一个会话是浏览器标签; 它在30分钟的不活动后结束或打开 `reset()`。 。 。 .
-   隐私默认:输入中输入的每分每分每分都被蒙上(密码总是被蒙上). 添加 `data-glancy-mask` (或类) `glancy-mask`掩盖一个元素的文本, `data-glancy-block` (或 `glancy-block`完全不说.

| `sessionReplay` 选项 | 默认 |  |
| --- | --- | --- |
| `sampleRate` | `1` | 记录的届会份额(每届决定一次) |
| `maskAllInputs` | `true` | 遮罩什么人类型 |
| `maskAllText` | `false` | 遮盖页面上的每一条文字 |
| `maskTextSelector` | —— 说 | 更多要掩盖的元素 |
| `blockSelector` | —— 说 | 更多要删除的内容 |

**热图** 收集每次点击(在页面中的位置,以及哪个元素)和每个页面视图最深的卷轴. 闪光从您的活页上以框架、每页和设备类(桌面/平板/移动)取出,以及 列出点击次数最多的元素。 给予重要要素a `data-testid` 或者说 `data-glancy-name` 以获得稳定的名字. 要显示页面, 您的网站必须允许被仪表板的出处设定( 否) `X-Frame-Options: DENY` 编号 : 限制性 `frame-ancestors`); SDK没有追踪到这个框架内部.

## 中间软件

在下一部.js 16 以及后来的文件是 `proxy.ts` (Next.js将中间软件更名为代理); 更早, `middleware.ts`。 。 。 .

```ts
// proxy.ts (middleware.ts before Next.js 16)
import { withGlancy } from "@caravela-studio/glancy-next/middleware";

export default withGlancy({ exclude: ["/api/health"], userId: (req) => req.cookies.get("uid")?.value });
export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
```

-   每个页面负荷的页面视图( E)`Sec-Fetch-Dest: document`),带有新鲜的 `messageId` 它将手交给 短寿命浏览器 `glancy_pv` 饼干 浏览器SDK的第一页视图重新使用它 摄取存储一行,填写服务器副本缺少的内容(标题,屏幕,浏览器会话). 客户端导航 `<GlancyProvider>`: Next.js 在中间软件前将 RSC / 前缀头条剥去, 因此,导航不能从那里预示.
-   一个 `API Request` 匹配路径的事件(方法、路径) `api` (默认) `["/api/"]`),加 (中文(简体) ) `status` 当您 中线软件自答;中线软件从未看到路由本身的响应.
-   设定 `glancy_anon_id` 在第一个请求上(由浏览器SDK可读取),所以双方共享访问者.
-   跳过静态文件、预选、重定向和 `exclude`; 发送与 `event.waitUntil`。 。 。 .
-   `withGlancy(options, yourMiddleware)` 先运行你的 并保持它的响应.

## 路由处理器

`withGlancyRoute(handler, options?)` 从 `@caravela-studio/glancy-next/server` 发送一个 `API Request` 与 答复 `status` 财务报告和审定财务报表 `duration_ms` (投出数为500并被重掷). 选项 : `event`, (中文(简体) ), `userId(req)`, (中文(简体) ), `writeKey`, (中文(简体) ), `host`, (中文(简体) ), `onError`。它发送与 `after()` 当可用时。 使用 `api: false` 内 `withGlancy()` (或 `exclude` 所以请求不计算两次.

```ts
export const POST = withGlancyRoute(async (req) => Response.json(await createOrder(req), { status: 201 }));
```

## 服务器

设定 `GLANCY_HOST` 财务报告和审定财务报表 `GLANCY_WRITE_KEY` (单位:千美元) `NEXT_PUBLIC_` 它们被用作后退.

```ts
// app/api/checkout/route.ts
import { glancy, getAnonymousId } from "@caravela-studio/glancy-next/server";
import { cookies } from "next/headers";
import { after } from "next/server";

export async function POST() {
  const anonymousId = getAnonymousId(await cookies());
  after(() => glancy().track({ userId: user.id, anonymousId, event: "Order Completed", properties: { revenue: 42 } }));
  return Response.json({ ok: true });
}
```

服务器呼叫( E)`track`, (中文(简体) ), `identify`, (中文(简体) ), `page`, (中文(简体) ), `group`, (中文(简体) ), `alias`, (中文(简体) ), `batch`需要一个 `userId` 或一个 `anonymousId`每一个 一个被立即发送,一旦存储就解决,所以没有服务器的功能不会降出事件; `after()` 保留 反应时间到 发送从不扔出——失败到 `onError` (默认) `console.error`,最多一分钟一次). `new ServerClient({ writeKey, host })` 创建带有明确配置的客户端.

## 示例

`examples/nextjs` 是一个使用两边的小应用程序 : `npm install && npm run dev` (端口3048号).

## 常见问题

### @caravela-studio/glancy-next 是什么？

从 Next\.js 直接发送产品分析到 Glancy

### 如何安装 @caravela-studio/glancy-next？

在项目目录运行 npm install @caravela-studio/glancy-next，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（\>=13\.4）、react（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @caravela-studio/glancy-next 支持 TypeScript 吗？

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

### @caravela-studio/glancy-next 支持 ESM 还是 CommonJS？

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

### @caravela-studio/glancy-next 可以商用吗？

@caravela-studio/glancy-next 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @caravela-studio/glancy-next 的下载量有多少？

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

### @caravela-studio/glancy-next 还在维护吗？

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