DotCMS SDK Analytics 설치 가이드

이 스킬은 /core/examples/nextjs에 있는 Next.js 예제 프로젝트에서 @dotcms/analytics SDK를 설치하고 구성하는 단계별 지침을 제공합니다.

개요

@dotcms/analytics SDK는 콘텐츠 인식 이벤트 및 분석을 추적하기 위한 dotCMS의 공식 JavaScript 라이브러리입니다. 다음을 제공합니다:

자동 페이지 조회 추적
전환 추적(구매, 다운로드, 가입 등)
맞춤 이벤트 추적
세션 관리(30분 타임아웃)
익명 사용자 식별 추적
UTM 캠페인 매개변수 추적
성능 최적화를 위한 이벤트 배치/대기열 처리

🚨 중요: 분석 구성 요소 이해

중요: useContentAnalytics()는 항상 config를 매개변수로 필요로 합니다. 이 훅은 React Context를 사용하지 않습니다.

구성 요소 역할

<DotContentAnalytics /> - 자동 페이지 조회 추적기
- 유일한 목적: 경로 변경 시 페이지 조회를 자동으로 추적
- React Context Provider가 아님
- 하위 컴포넌트에 config를 제공하지 않음
- 자동 페이지 조회 추적을 위해 루트 레이아웃에 배치
useContentAnalytics(config) - 수동 추적 훅
- 맞춤 이벤트 추적에 사용
- 항상 config 매개변수 필요
- 사용하는 각 컴포넌트에 중앙 집중식 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. 훅을 사용하는 모든 컴포넌트에서 config 가져오기
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";

const { track } = useContentAnalytics(analyticsConfig); // ✅ Config 필수!

왜 config를 중앙 집중화하나요? 각 컴포넌트에 가져와야 하지만, 중앙 집중화하면 중복을 방지하고 업데이트가 쉬워집니다.

빠른 설정 요약

전체 설정 흐름은 다음과 같습니다:

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. 훅을 사용하는 모든 컴포넌트에 config 가져오기
   └─> /src/components/MyComponent.js
       └─> import { analyticsConfig } from "@/config/analytics.config"
       └─> const { track } = useContentAnalytics(analyticsConfig) // ✅ Config 필수!

중앙 집중식 설정의 주요 이점:

✅ 구성 값의 단일 진실 공급원
✅ 한 곳에서 환경 변수 업데이트가 용이
✅ 모든 컴포넌트에서 일관된 설정
✅ 모든 파일에서 설정을 중복하는 것보다 낫습니다

설치 단계

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 provider
 * - 단독으로 사용될 때 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초마다 전송 (ms)
  },
};

이 접근 방식의 이점:

✅ 분석 설정의 단일 진실 공급원
✅ 컴포넌트 전체에서 쉽게 가져와서 재사용
✅ 중앙 집중식 환경 변수 관리
✅ 타입 안전 및 IDE 자동 완성 친화적
✅ 단위 테스트에서 쉽게 테스트 및 모킹 가능

4. Next.js 레이아웃에서 분석 설정

중앙 집중식 config를 사용하여 분석 provider를 포함하도록 루트 레이아웃 파일을 업데이트합니다.

파일: /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>
  );
}

분석이 추가된 업데이트 버전 (중앙 집중식 config 사용):

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 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() {
  // ✅ 항상 config 전달 - 중앙 집중식 설정 파일에서 가져오기
  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() {
  // ✅ 항상 config 전달 - 중앙 집중식 설정 파일에서 가져오기
  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>
  );
}

전자상거래 제품 조회 추적

"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 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`	플러시 사이의 시간 (ms)

대기열 비활성화 (즉시 전송):

const analyticsConfig = {
  siteAuth: "your_key",
  server: "https://your-server.com",
  queue: false, // 이벤트를 즉시 전송
};

노출 추적 설정

콘텐츠 가시성의 자동 추적을 제어합니다:

| 옵션 | 유형 | 기본값 | 설명

…

[요약됨]

Microck/ordinary-claude-skills

ordinary-claude-skills란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서