@clakta / nextjs

Next.js的官方Clakta SDK。

Clakta是一个为现代企业打造的现代销售和广告跟踪平台。通过现代而强大的平台，获得准确的数据并了解哪些广告表现最佳，哪些影响者销售最多。

网站

包装 @clakta/javascript 与一个 <ClaktaProvider> 组件，用于在挂载时初始化SDK。适用于应用路由器和页面路由器。

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

安装

npm install @clakta/nextjs

pnpm add @clakta/nextjs

yarn add @clakta/nextjs

使用

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

应用路由器

// 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" 在你的布局中。

页面的路由器

// 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：

因为初始化在每个页生命周期中发生一次，所以第一次挂载之后的prop更改将被忽略——除非 consent，应用于 updateConsent 会。从env变量传递id，而不是从state传递id：

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

跟踪事件

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

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

"use client"

import { trackEvent } from "@clakta/nextjs"

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

识别客户

"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，因此可以从客户端组件调用它们。

"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: "[email protected]" },
})

// 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: "[email protected]" },
  // 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． 没有调用的调用将被丢弃，并发出控制台警告。

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

customer 是个人资料而只按 full_attribution 征得同意。看到 @clakta/javascript 自述 以获取完整的字段参考。

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

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

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

// 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 自述 到底什么是收集的，什么不是收集的。

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

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

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

"use client"

import { updateConsent } from "@clakta/nextjs"

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

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

import { getConsent } from "@clakta/nextjs"

getConsent() // => true

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

API

再出口的 @clakta/javascript，所以对于常见情况，你只需要一个依赖项：

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

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

看到 @clakta/javascript 自述 获取完整的API参考、跟踪模式和自动跟踪行为。

链接

• 网站
• @clakta/javascript -底层浏览器SDK
• 问题

许可证

麻省理工学院