Microck/ordinary-claude-skills

DotCMS SDK Analytics 安裝指南

此技能提供在 Next.js 範例專案 /core/examples/nextjs 中安裝與設定 @dotcms/analytics SDK 的逐步說明。

概觀

@dotcms/analytics SDK 是 dotCMS 官方的 JavaScript 函式庫，用於追蹤內容感知事件與分析資料。它提供：

• 自動頁面瀏覽追蹤
• 轉換追蹤（購買、下載、註冊等）
• 自訂事件追蹤
• 工作階段管理（30 分鐘逾時）
• 匿名使用者身分識別
• UTM 廣告活動參數追蹤
• 事件批次/排隊處理以提升效能

🚨 重要：了解分析元件

關鍵：useContentAnalytics() 始終需要將設定作為參數傳入。此 Hook 不使用 React Context。

元件角色

1. <DotContentAnalytics /> - 自動頁面瀏覽追蹤器

   • 唯一目的：在路由變更時自動追蹤頁面瀏覽次數
   • 非 React Context 提供者
   • 不將設定提供給子元件
   • 放置在根佈局中以實現自動頁面瀏覽追蹤

2. useContentAnalytics(config) - 手動追蹤 Hook

   • 用於自訂事件追蹤
   • 始終需要設定參數
   • 在每個使用它的元件中匯入集中設定

正確使用模式

// 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. 在每個使用 Hook 的元件中匯入設定
// /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. 在**每個**使用 Hook 的元件中匯入設定
   └─> /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() Hook（選用）
 *
 * 所需的環境變數：
 * - 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 Layout 中設定 Analytics

使用集中設定更新根佈局檔案以包含分析提供者。

檔案：/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 Analytics 設定
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 Analytics 網站授權金鑰。您可以從 dotCMS 執行個體的 Analytics 應用程式中取得此金鑰。

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>Content here</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: "Buy Now",
      location: "hero-section",
      price: 299.99,
    });
  };

  return <button onClick={handleClick}>Buy Now</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}>Complete Purchase</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}>
      Download Whitepaper
    </button>
  );
}

設定選項

Analytics 設定物件

選項	型別	必填	預設值	描述
siteAuth	string	是	-	來自 dotCMS Analytics 的網站授權金鑰
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	觸發曝光所需的可見百分比
delay	number	0	追蹤前的延遲時間（毫秒）

自訂曝光設定範例：

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  impressions: {
    rootMargin: "100px",
    threshold: 0.25,
    delay: 500,
  },
};

除錯與疑難排解

啟用除錯模式

將 debug: true 新增至設定以查看詳細日誌

const analyticsConfig = {
  ...
  debug: true, // 啟用詳細日誌
};

透過環境變數：

NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG=true

常見問題

1. 事件未追蹤

   • 驗證 siteAuth 和 server 設定是否正確
   • 檢查控制台中是否有錯誤
   • 確保已啟用除錯模式

2. 跨頁面遺失工作階段

   • 工作階段有 30 分鐘逾時
   • 使用 userId 進行持久化身分識別
   • 檢查 cookie 設定

3. 效能問題

   • 調整佇列設定以進行批次處理
   • 停用不必要的自動追蹤
   • 使用 impressions 間隔延遲

其他資源

• dotCMS Analytics 文件
• React SDK 文件
• API 參考