# @clakta/nextjs 中文文档

规范地址：https://npmcn.com/package/%40clakta/nextjs/

版本：1\.1\.4
npm 元数据更新时间：2026-10-31T18:53:46.662Z
中文译文更新时间：2026-10-31T19:35:33.970Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clakta/nextjs
原文对照：https://npmcn.com/package/%40clakta/nextjs/?lang=original
项目主页：https://clakta.com/
源码仓库：https://github.com/clakta/clakta-js

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

- 包体积（解压后）：18.5 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：next \>=13\.0\.0，react \>=18\.0\.0
- 首次发布：2026-10-22T14:23:10.543Z
- 最新版本发布：2026-10-31T18:53:46.510Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

# @clakta / nextjs

## 安装

```sh
npm install @clakta/nextjs
```

也可以使用：`pnpm add @clakta/nextjs`、`yarn add @clakta/nextjs`、`bun add @clakta/nextjs`

## README

# @clakta / nextjs

Next.js的官方Clakta SDK。  
  
Clakta是一个为现代企业打造的现代销售和广告跟踪平台。通过现代而强大的平台，获得准确的数据并了解哪些广告表现最佳，哪些影响者销售最多。  
  
[**网站**](https://www.clakta.com/)

[![npm version](https://img.shields.io/npm/v/@clakta/nextjs.svg)](https://www.npmjs.com/package/@clakta/nextjs) [![npm downloads](https://img.shields.io/npm/dm/@clakta/nextjs.svg)](https://www.npmjs.com/package/@clakta/nextjs) [![minzipped size](https://img.shields.io/bundlephobia/minzip/@clakta/nextjs)](https://bundlephobia.com/package/@clakta/nextjs) [![license](https://img.shields.io/npm/l/@clakta/nextjs.svg)](https://www.npmjs.com/package/@clakta/nextjs)

* * *

包装 [`@clakta/javascript`](https://github.com/clakta/clakta-js/tree/main/packages/javascript) 与一个 `<ClaktaProvider>` 组件，用于在挂载时初始化SDK。适用于应用路由器和页面路由器。

需要Next.js 13+和React 18+。

## 安装

```bash
npm install @clakta/nextjs
```

```bash
pnpm add @clakta/nextjs
```

```bash
yarn add @clakta/nextjs
```

## 使用

渲染 `<ClaktaProvider>` 一旦接近你的应用程序的根并传递你的脚本id。它不呈现任何内容，并且在页面的生命周期内只运行一次初始化。

### 应用路由器

```tsx
// app/layout.tsx
import { ClaktaProvider } from "@clakta/nextjs"

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

提供程序已经是一个客户端组件，所以您不需要 `"use client"` 在你的布局中。

### 页面的路由器

```tsx
// pages/_app.tsx
import { ClaktaProvider } from "@clakta/nextjs"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <ClaktaProvider id="YOUR_SCRIPT_ID" />
      <Component {...pageProps} />
    </>
  )
}
```

### 道具

`<ClaktaProvider>` 的选项相同 `init`：

| 道具 | 类型 | 默认的 | 描述 |
| --- | --- | --- | --- |
| `id` | `string` | \- - - - - - | **必需的。** 您的Clakta脚本id。 |
| `apiHost` | `string` | `https://api.clakta.com` | 覆盖API主机。跟踪/配置使用 [https://t.clakta.com](https://t.clakta.com/) 默认情况下;Stripe停留在api.clakta.com上。 |
| `debug` | `boolean` | `false` | 详细控制台日志记录。 |
| `consent` | `boolean` | 按访客地点划分 | 访问者是否同意使用第一方标识符。看到 [同意](https://npmcn.com/package/%40clakta/nextjs/#readme-consent). |

因为初始化在每个页生命周期中发生一次，所以第一次挂载之后的prop更改将被忽略——除非 `consent`，应用于 [`updateConsent`](https://npmcn.com/package/%40clakta/nextjs/#readme-consent) 会。从env变量传递id，而不是从state传递id：

```tsx
<ClaktaProvider id={process.env.NEXT_PUBLIC_CLAKTA_ID!} />
```

## 跟踪事件

当你的项目启用页面视图时，它们会为你处理——App Router和Pages Router的导航都要通过历史API， SDK会监听这些API。其他的都可以直接调用。

跟踪功能 `window`因此，从客户端组件调用它们——在事件处理程序或效果中，而不是在服务器渲染期间。

```tsx
"use client"

import { trackEvent } from "@clakta/nextjs"

export function BuyButton() {
  return (
    <button onClick={() => trackEvent("hero-cta", "click", { variant: "A" })}>
      Buy now
    </button>
  )
}
```

### 识别客户

```tsx
"use client"

import { identify } from "@clakta/nextjs"
import { useEffect } from "react"

export function IdentifyUser({
  user,
}: {
  user: { id: string; email: string }
}) {
  useEffect(() => {
    identify({ externalId: user.id, email: user.email })
  }, [user])

  return null
}
```

至少有一个 `externalId`， `claktaCustomerId`，或者 `email` 是必需的。

### 电子商务

三个漏斗事件覆盖了通向销售的道路。他们联系 `window`，因此可以从客户端组件调用它们。

```tsx
"use client"

import { addToCart, initiateCheckout, purchase } from "@clakta/nextjs"

// Add to cart — no order exists yet
addToCart({
  products: [{ id: "42", name: "Tee", price: 29.99, quantity: 2 }],
  totalPrice: 59.98,
  currency: "USD",
})

// Checkout started
initiateCheckout({
  orderId: "1001",
  totalPrice: 59.98,
  currency: "USD",
  products: [{ id: "42", name: "Tee", price: 29.99, quantity: 2 }],
  customer: { email: "ada@example.com" },
})

// Purchase completed
purchase({
  orderId: "1001",
  totalPrice: 59.98,
  currency: "USD",
  paymentMethod: "credit_card",
  products: [{ id: "42", name: "Tee", price: 29.99, quantity: 2 }],
  customer: { email: "ada@example.com" },
  // Optional — clkt is read from the URL when you don't pass one
  tracking: { utm_source: "facebook", utm_medium: "cpc" },
})
```

`initiateCheckout` 和 `purchase` **需要** `orderId` -订单的id在你自己的数据库，和相同的值，你的服务器发送给 [订单的API](https://www.clakta.com/docs/api-reference/orders/create-order)． 没有调用的调用将被丢弃，并发出控制台警告。

Clakta将浏览器事件与服务器发布的顺序相协调，服务器的顺序保留了状态、总数和内容的真实来源——因此，在您的感谢页面呈现之前关闭标签页的访问者不会对您造成任何损失。一切除了 `orderId` 是该有效载荷的一个小识别子集(`totalPrice`， `currency`， `paymentMethod`， `products`， `customer`， `tracking`）; 服务器拥有的字段不被客户端接受。

`customer` 是个人资料而只按 `full_attribution` 征得同意。看到 [`@clakta/javascript` 自述](https://github.com/clakta/clakta-js/tree/main/packages/javascript#ecommerce) 以获取完整的字段参考。

这两个事件都是可选的 `tracking` 块, `clkt` 加上 `utm_source`， `utm_medium`， `utm_campaign` 和 `utm_content` -把订单归功于点击。省略 `clkt` SDK从当前URL解析它，返回到访问登陆的URL，这在应用路由器中很重要：你重定向到的确认页面不再包含广告的查询字符串。

在App Router中常见的一个形状——从确认页面触发购买事件，一次，使用你已经在服务器端拥有的订单id：

```tsx
// app/orders/[orderId]/confirmation/page.tsx
import { PurchaseTracker } from "./purchase-tracker"

export default async function ConfirmationPage({
  params,
}: {
  params: Promise<{ orderId: string }>
}) {
  const { orderId } = await params
  const order = await getOrder(orderId) // your own data layer

  return (
    <>
      <PurchaseTracker order={order} />
      <OrderSummary order={order} />
    </>
  )
}
```

```tsx
// app/orders/[orderId]/confirmation/purchase-tracker.tsx
"use client"

import { purchase } from "@clakta/nextjs"
import { useEffect, useRef } from "react"

export function PurchaseTracker({ order }: { order: Order }) {
  const tracked = useRef(false)

  useEffect(() => {
    if (tracked.current) return
    tracked.current = true

    purchase({
      orderId: order.id,
      totalPrice: order.total,
      currency: order.currency,
      paymentMethod: "credit_card",
      products: order.items.map((item) => ({
        id: item.productId,
        name: item.name,
        quantity: item.quantity,
        price: item.price,
      })),
      customer: { email: order.customerEmail },
    })
  }, [order])

  return null
}
```

## 同意

同意只有在项目运行时才有效 `full_attribution` 模式;在 `privacy_friendly` 模式不使用第一方标识符。

除非你设置它，否则“同意”会跟随访问者的位置：欧盟、欧洲经济区、英国和瑞士的访问者——以及任何位置未知的访问者——开始时没有它，只有在你的cookie横幅授权后才会被识别出来。其他人都是从它开始的。未经同意的访客仍会被匿名统计。看到 [`@clakta/javascript` 自述](https://github.com/clakta/clakta-js/tree/main/packages/javascript#consent) 到底什么是收集的，什么不是收集的。

在provider -上设置它 `false` 让每个访问者保持匿名直到他们接受页面，无论他们在哪里，无论他们之前回答了什么，或者 `true` 如果提供商只在访问者接受后才呈现：

```tsx
<ClaktaProvider id="YOUR_SCRIPT_ID" consent={false} />
```

道具在挂载后仍然有效，所以你可以将其从旗帜状态中移除。或者在访问者回答时直接更新：

```tsx
"use client"

import { updateConsent } from "@clakta/nextjs"

export function CookieBanner() {
  return <button onClick={() => updateConsent(true)}>Accept</button>
}
```

读取当前状态 `getConsent`，该网站报道 `false` 直到做出选择：

```tsx
import { getConsent } from "@clakta/nextjs"

getConsent() // => true
```

答案会被记住——在一个cookie中保存一年，并且在localStorage中没有过期——所以以后的页面从他们的第一个事件开始应用它，而一个接受中途访问的访问者会立即开始一个识别会话，并保留他们到达时的广告源。撤销许可会立即清除SDK存储的所有标识符，后续事件以匿名方式记录。

## API

再出口的 [`@clakta/javascript`](https://github.com/clakta/clakta-js/tree/main/packages/javascript)，所以对于常见情况，你只需要一个依赖项：

`init` · `pageView` · `trackEvent` · `identify` · `pageViewWithProduct` · `addToCart` · `initiateCheckout` · `purchase` · `getConsent` · `updateConsent`

加上类型： `ClaktaCartDetails`， `ClaktaConfig`， `ClaktaOptions`， `ClaktaOrderCustomer`， `ClaktaOrderDetails`， `ClaktaPaymentMethod`， `ClaktaProduct`， `ClaktaTrackingParams`， `CustomerData`， `ResolvedConfig`， `TrackingMode`.

看到 [`@clakta/javascript` 自述](https://github.com/clakta/clakta-js/tree/main/packages/javascript) 获取完整的API参考、跟踪模式和自动跟踪行为。

## 链接

-   [网站](https://www.clakta.com/)
-   [`@clakta/javascript`](https://github.com/clakta/clakta-js/tree/main/packages/javascript) -底层浏览器SDK
-   [问题](https://github.com/clakta/clakta-js/issues)

## 许可证

麻省理工学院

## 常见问题

### @clakta/nextjs 是什么？

@clakta / nextjs

### 如何安装 @clakta/nextjs？

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

### @clakta/nextjs 支持 TypeScript 吗？

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

### @clakta/nextjs 支持 ESM 还是 CommonJS？

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

### @clakta/nextjs 可以商用吗？

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

### @clakta/nextjs 还在维护吗？

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