@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 来自服务器的事件——见 下级。 。 。 .
• 服务器 : glancy() 从 @caravela-studio/glancy-next/server 用于路由处理器、服务器动作和中间软件.
• 会话重放热映射( H) : 记录会话以监视它们,并收集点击和滚动深度 每页——见 下级。 。 。 .
• 两人都有一位访客: 浏览器的匿名 id 住在 glancy_anon_id 饼干,服务器事件 可以绑在它上 getAnonymousId()。 。 。 . identify 将匿名历史合并到用户.

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

不在Next.js上吗? 见 全部 SDK 软件数字 : @caravela-studio/glancy-web 对于任何网络应用, glancy.js 任何地点, 反应土著,斯威夫特和克特林. 此软件包基于 @caravela-studio/glancy-web。 。 。 .

安装

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

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

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

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

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

浏览器

// 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>
  );
}

"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>;
}

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

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

会话重放和热映射

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

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

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

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

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

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

中间软件

在下一部.js 16 以及后来的文件是 proxy.ts (Next.js将中间软件更名为代理); 更早, middleware.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 所以请求不计算两次.

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

服务器

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

// 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号).