DotCMS SDK 分析安装指南

本技能为在 Next.js 示例项目（/core/examples/nextjs）中安装和配置 @dotcms/analytics SDK 提供逐步说明。

概述

@dotcms/analytics SDK 是 dotCMS 官方的 JavaScript 库，用于跟踪内容感知事件和分析数据。它提供：

自动页面浏览跟踪
转化跟踪（购买、下载、注册等）
自定义事件跟踪
会话管理（30 分钟超时）
匿名用户身份跟踪
UTM 活动参数跟踪
事件批量排队处理以优化性能

🚨 重要：了解分析组件

关键信息：useContentAnalytics() 始终需要将配置作为参数传入。该钩子不使用 React Context。

组件角色

<DotContentAnalytics /> - 自动页面浏览跟踪器
- 唯一目的：在路由变化时自动跟踪页面浏览量
- 不是 React Context Provider
- 不向子组件提供配置
- 放置在根布局中以实现自动页面浏览跟踪
useContentAnalytics(config) - 手动跟踪钩子
- 用于自定义事件跟踪
- 始终需要配置参数
- 在每个使用它的组件中导入集中式配置

正确的使用模式

// 1. 创建集中式配置文件（仅一次）
// /src/config/analytics.config.js
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true,
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
};

// 2. 将 DotContentAnalytics 添加到布局中以实现自动页面浏览跟踪（可选）
// /src/app/layout.js
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

<DotContentAnalytics config={analyticsConfig} />;

// 3. 在每个使用该钩子的组件中导入配置
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

const { track } = useContentAnalytics(analyticsConfig); // ✅ 配置是必需的！

为什么要集中配置？ 虽然你必须在每个组件中导入它，但集中配置可以防止重复，并使更新更容易。

快速设置摘要

以下是完整的设置流程：

1. 安装包
   └─> npm install @dotcms/analytics

2. 创建集中式配置文件
   └─> /src/config/analytics.config.js
       └─> export const analyticsConfig = { siteAuth, server, debug, ... }

3. （可选）添加 DotContentAnalytics 以实现自动页面浏览跟踪
   └─> /src/app/layout.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> <DotContentAnalytics config={analyticsConfig} />

4. 在每个使用该钩子的组件中导入配置
   └─> /src/components/MyComponent.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> const { track } = useContentAnalytics(analyticsConfig) // ✅ 配置是必需的！

集中式配置的主要优势：

✅ 配置值的单一数据源
✅ 易于在一个地方更新环境变量
✅ 所有组件之间保持一致的配置
✅ 优于在每个文件中重复配置

安装步骤

1. 安装包

导航到 Next.js 示例目录并安装包：

cd /core/examples/nextjs
npm install @dotcms/analytics

2. 验证安装

检查包是否已添加到 package.json：

grep "@dotcms/analytics" package.json

预期输出："@dotcms/analytics": "latest" 或类似版本。

3. 创建集中式分析配置

创建一个专用的配置文件来集中管理分析设置。这使其更易于维护和在整个应用中重复使用。

文件：/core/examples/nextjs/src/config/analytics.config.js

/**
 * dotCMS 内容分析的集中式配置
 *
 * 此配置用于：
 * - layout.js 中的 DotContentAnalytics 提供者
 * - 单独使用 useContentAnalytics() 钩子时（可选）
 *
 * 所需环境变量：
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST
 * - NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG（可选）
 */
export const analyticsConfig = {
  siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
  server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
  autoPageView: true, // 自动跟踪路由变化时的页面浏览量
  debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
  queue: {
    eventBatchSize: 15, // 当 15 个事件排队时发送
    flushInterval: 5000, // 或每 5 秒发送一次（毫秒）
  },
};

此方法的好处：

✅ 分析配置的单一数据源
✅ 易于在组件之间导入和重复使用
✅ 集中管理环境变量
✅ 类型安全且支持 IDE 自动补全
✅ 易于在单元测试中测试和模拟

4. 在 Next.js 布局中配置分析

更新根布局文件以包含使用集中式配置的分析提供者。

文件：/core/examples/nextjs/src/app/layout.js

import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

使用分析功能更新后（使用集中式配置）：

import { Inter } from "next/font/google";
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <DotContentAnalytics config={analyticsConfig} />
        {children}
      </body>
    </html>
  );
}

4. 添加环境变量

在 Next.js 项目根目录创建或更新 .env.local 文件：

文件：/core/examples/nextjs/.env.local

# dotCMS 分析配置
NEXT_PUBLIC_DOTCMS_SITE_AUTH=your_site_auth_key_here
NEXT_PUBLIC_DOTCMS_SERVER=https://your-dotcms-server.com

重要：将 your_site_auth_key_here 替换为你的实际 dotCMS 分析站点认证密钥。可以从你的 dotCMS 实例中的分析应用获取。

5. 将 `.env.local` 添加到 `.gitignore`

确保环境文件不被提交到版本控制：

# 检查是否已被忽略
grep ".env.local" /core/examples/nextjs/.gitignore

# 如果不存在，添加它
echo ".env.local" >> /core/examples/nextjs/.gitignore

使用示例

基本设置（自动页面浏览量）

使用上述配置后，页面浏览量将在每次路由变化时自动跟踪。无需额外代码！

使用自定义数据的手动页面浏览跟踪

跟踪带有额外上下文的页面浏览量：

"use client";

import { useEffect } from "react";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function MyComponent() {
  // ✅ 始终传递配置 - 从集中式配置文件导入
  const { pageView } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // 使用自定义数据跟踪页面视图
    pageView({
      contentType: "blog",
      category: "technology",
      author: "john-doe",
      wordCount: 1500,
    });
  }, []);

  return <div>此处放置内容</div>;
}

跟踪自定义事件

跟踪特定的用户交互：

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function CallToActionButton() {
  // ✅ 始终传递配置 - 从集中式配置文件导入
  const { track } = useContentAnalytics(analyticsConfig);

  const handleClick = () => {
    // 跟踪自定义事件
    track("cta-click", {
      button: "立即购买",
      location: "英雄区域",
      price: 299.99,
    });
  };

  return <button onClick={handleClick}>立即购买</button>;
}

表单提交跟踪

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function ContactForm() {
  const { track } = useContentAnalytics(analyticsConfig);

  const handleSubmit = async (e) => {
    e.preventDefault();

    // 跟踪表单提交
    track("form-submit", {
      formName: "contact-form",
      formType: "lead-gen",
      source: "homepage",
    });

    // 提交表单...
  };

  return <form onSubmit={handleSubmit}>{/* 表单字段 */}</form>;
}

视频/媒体交互跟踪

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function VideoPlayer({ videoId }) {
  const { track } = useContentAnalytics(analyticsConfig);

  const handlePlay = () => {
    track("video-play", {
      videoId,
      duration: 120,
      autoplay: false,
    });
  };

  const handleComplete = () => {
    track("video-complete", {
      videoId,
      watchPercentage: 100,
    });
  };

  return (
    <video onPlay={handlePlay} onEnded={handleComplete}>
      {/* 视频源 */}
    </video>
  );
}

电子商务产品浏览跟踪

"use client";

import { useEffect } from "react";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function ProductPage({ product }) {
  const { track } = useContentAnalytics(analyticsConfig);

  useEffect(() => {
    // 跟踪产品浏览
    track("product-view", {
      productId: product.sku,
      productName: product.title,
      category: product.category,
      price: product.price,
      inStock: product.inventory > 0,
    });
  }, [product]);

  return <div>{/* 产品详情 */}</div>;
}

转化跟踪（电子商务购买）

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function CheckoutButton({ product, quantity }) {
  const { conversion } = useContentAnalytics(analyticsConfig);

  const handlePurchase = () => {
    // 在此处理结账逻辑...
    // 成功支付确认后：

    // 仅在成功购买后跟踪转化
    conversion("purchase", {
      value: product.price * quantity,
      currency: "USD",
      productId: product.sku,
      productName: product.title,
      quantity: quantity,
      category: product.category,
    });
  };

  return <button onClick={handlePurchase}>完成购买</button>;
}

转化跟踪（潜在客户生成）

"use client";

import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

function DownloadWhitepaper() {
  const { conversion } = useContentAnalytics(analyticsConfig);

  const handleDownload = () => {
    // 在此触发下载逻辑...
    // 下载成功完成后：

    // 仅在成功下载后跟踪转化
    conversion("download", {
      fileType: "pdf",
      fileName: "whitepaper-2024.pdf",
      category: "lead-magnet",
    });
  };

  return (
    <button id="download-btn" onClick={handleDownload}>
      下载白皮书
    </button>
  );
}

配置选项

分析配置对象

选项	类型	必需	默认值	描述
`siteAuth`	`string`	是	-	来自 dotCMS 分析的站点认证密钥
`server`	`string`	是	-	你的 dotCMS 服务器 URL
`debug`	`boolean`	否	`false`	启用详细日志以进行调试
`autoPageView`	`boolean`	否	`true` (React)	自动跟踪路由变化时的页面浏览量
`queue`	`QueueConfig \| false`	否	默认队列设置	事件批处理配置
`impressions`	`ImpressionConfig \| boolean`	否	`false`	内容展示跟踪（默认禁用）
`clicks`	`boolean`	否	`false`	内容点击跟踪，300ms 节流（默认禁用）

队列配置

控制事件的批处理和发送方式：

选项	类型	默认值	描述
`eventBatchSize`	`number`	`15`	每批最大事件数 - 达到时自动发送
`flushInterval`	`number`	`5000`	两次刷新之间的时间（毫秒）

禁用队列（立即发送）：

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  queue: false, // 立即发送事件
};

展示跟踪配置

控制内容可见性的自动跟踪：

选项	类型	默认值	描述
`rootMargin`	`string`	`"0px"`	Intersection Observer 的根边距
`threshold`	`number`	`0.5`	触发可见性事件所需的最小可见比例
`once`	`boolean`	`true`	仅跟踪首次展示（避免重复跟踪相同元素）

启用展示跟踪：

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  impressions: {
    rootMargin: "0px",
    threshold: 0.5,
    once: true,
  },
};

点击跟踪配置

跟踪用户与内容的交互：

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  clicks: true, // 启用内容点击跟踪，默认节流为 300ms
};

环境变量

以下环境变量需要在 .env.local 中设置：

变量名	必需	描述
`NEXT_PUBLIC_DOTCMS_SITE_AUTH`	是	dotCMS 分析站点认证密钥
`NEXT_PUBLIC_DOTCMS_SERVER`	是	dotCMS 服务器 URL
`NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG`	否	设置为 "true" 以启用调试日志

常见问题

Q：如何排除某些路径不被跟踪？

虽然该技能没有涵盖高级路由过滤，但你可以修改布局以实现条件渲染逻辑，或使用 react-router-dom 的钩子手动控制跟踪。请查阅 @dotcms/analytics 官方文档了解更多详细信息。

Q：我是否需要在每个页面组件中都包含 analyticsConfig？

不，你只需要在明确使用 useContentAnalytics 钩子的组件中导入 analyticsConfig。如果组件不需要任何分析事件，则无需导入。

Q：如何在开发环境中测试分析功能？

在 .env.local 中设置 NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG=true，以查看控制台日志中的分析事件和配置信息。

在你喜欢的 AI 中提问

文档