DotCMS SDK 分析インストールガイド

このスキルは、/core/examples/nextjs にある Next.js サンプルプロジェクトに @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: "hero-section",
      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>
  );
}

E コマース商品ビュートラッキング

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

コンバージョントラッキング（E コマース購入）

"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, // イベントを即時送信
};

インプレッショントラッキング設定

コンテンツの可視性の自動追跡を制御します:

オプション	型	デフォルト	説明
`isIntersecting`	`boolean`	-	要素が現在ビューポートにあるか
`intersectionRatio`	`number`	-	要素の可視割合
`scrollDirection`	`string`	-	スクロール方向

Microck/ordinary-claude-skills

ordinary-claude-skills とは？

お気に入りのAIに質問する

ドキュメント