view --main sdk-analytics-installer-skill-dlya-ustanovki-analitiki.md
SDK Analytics Installer: Скилл для установки аналитики
SKILL.md
readonly
--- lines
---
name: SDK Analytics Installer
description: Use this skill when the user asks to install, configure, or set up @dotcms/analytics, sdk-analytics, analytics SDK, add analytics tracking, or mentions installing analytics in Next.js or React projects
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
version: 1.0.0
---
# DotCMS SDK Analytics Installation Guide
This skill provides step-by-step instructions for installing and configuring the `@dotcms/analytics` SDK in the Next.js example project at `/core/examples/nextjs`.
## Overview
The `@dotcms/analytics` SDK is dotCMS's official JavaScript library for tracking content-aware events and analytics. It provides:
- Automatic page view tracking
- Conversion tracking (purchases, downloads, sign-ups, etc.)
- Custom event tracking
- Session management (30-minute timeout)
- Anonymous user identity tracking
- UTM campaign parameter tracking
- Event batching/queuing for performance
## 🚨 Important: Understanding the Analytics Components
**CRITICAL**: `useContentAnalytics()` **ALWAYS requires config as a parameter**. The hook does NOT use React Context.
### Component Roles
1. **`<DotContentAnalytics />`** - Auto Page View Tracker
- Only purpose: Automatically track pageviews on route changes
- **NOT a React Context Provider**
- Does **NOT** provide config to child components
- Place in root layout for automatic pageview tracking
2. **`useContentAnalytics(config)`** - Manual Tracking Hook
- Used for custom event tracking
- **ALWAYS requires config parameter**
- Import centralized config in each component that uses it
### Correct Usage Pattern
```javascript
// 1. Create centralized config file (once)
// /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. Add DotContentAnalytics to layout for auto pageview tracking (optional)
// /src/app/layout.js
import { DotContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
<DotContentAnalytics config={analyticsConfig} />;
// 3. Import config in every component that uses the hook
// /src/components/MyComponent.js
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
const { track } = useContentAnalytics(analyticsConfig); // ✅ Config required!
```
**Why centralize config?** While you must import it in each component, centralizing prevents duplication and makes updates easier.
## Quick Setup Summary
Here's the complete setup flow:
```
1. Install package
└─> npm install @dotcms/analytics
2. Create centralized config file
└─> /src/config/analytics.config.js
└─> export const analyticsConfig = { siteAuth, server, debug, ... }
3. (Optional) Add DotContentAnalytics for auto pageview tracking
└─> /src/app/layout.js
└─> import { analyticsConfig } from "@/config/analytics.config"
└─> <DotContentAnalytics config={analyticsConfig} />
4. Import config in EVERY component that uses the hook
└─> /src/components/MyComponent.js
└─> import { analyticsConfig } from "@/config/analytics.config"
└─> const { track } = useContentAnalytics(analyticsConfig) // ✅ Config required!
```
**Key Benefits of Centralized Config**:
- ✅ Single source of truth for configuration values
- ✅ Easy to update environment variables in one place
- ✅ Consistent config across all components
- ✅ Better than duplicating config in every file
## Installation Steps
### 1. Install the Package
Navigate to the Next.js example directory and install the package:
```bash
cd /core/examples/nextjs
npm install @dotcms/analytics
```
### 2. Verify Installation
Check that the package was added to `package.json`:
```bash
grep "@dotcms/analytics" package.json
```
Expected output: `"@dotcms/analytics": "latest"` or similar version.
### 3. Create Centralized Analytics Configuration
Create a dedicated configuration file to centralize your analytics settings. This makes it easier to maintain and reuse across your application.
**File**: `/core/examples/nextjs/src/config/analytics.config.js`
```javascript
/**
* Centralized analytics configuration for dotCMS Content Analytics
*
* This configuration is used by:
* - DotContentAnalytics provider in layout.js
* - useContentAnalytics() hook when used standalone (optional)
*
* Environment variables required:
* - NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY
* - NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST
* - NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG (optional)
*/
export const analyticsConfig = {
siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
autoPageView: true, // Automatically track page views on route changes
debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
queue: {
eventBatchSize: 15, // Send when 15 events are queued
flushInterval: 5000, // Or send every 5 seconds (ms)
},
};
```
**Benefits of this approach**:
- ✅ Single source of truth for analytics configuration
- ✅ Easy to import and reuse across components
- ✅ Centralized environment variable management
- ✅ Type-safe and IDE autocomplete friendly
- ✅ Easy to test and mock in unit tests
### 4. Configure Analytics in Next.js Layout
Update the root layout file to include the analytics provider using the centralized config.
**File**: `/core/examples/nextjs/src/app/layout.js`
```javascript
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>
);
}
```
**Updated with Analytics** (using centralized config):
```javascript
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. Add Environment Variables
Create or update `.env.local` file in the Next.js project root:
**File**: `/core/examples/nextjs/.env.local`
```bash
# dotCMS Analytics Configuration
NEXT_PUBLIC_DOTCMS_AUTH_TOKEN={GENERATE TOKEN FROM USER PORTLET API ACCESS TOKEN}
NEXT_PUBLIC_DOTCMS_HOST={URL WHERE DOTCMS IS RUNNING}
NEXT_PUBLIC_DOTCMS_SITE_ID={SITE IDENTIFIER}
NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY={GENERATE KEY FROM CONTENT ANALYTICS APP}
NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST={SITE IDENTIFIER}
NEXT_PUBLIC_EXPERIMENTS_API_KEY={GENERATED KEY FROM THE EXPERIMENTS APP}
NEXT_PUBLIC_DOTCMS_MODE='production'
NODE_TLS_REJECT_UNAUTHORIZED=0
```
**Important**: Replace `your_site_auth_key_here` with your actual dotCMS Analytics site auth key. This can be obtained from the Analytics app in your dotCMS instance.
### 5. Add `.env.local` to `.gitignore`
Ensure the environment file is not committed to version control:
```bash
# Check if already ignored
grep ".env.local" /core/examples/nextjs/.gitignore
# If not present, add it
echo ".env.local" >> /core/examples/nextjs/.gitignore
```
## Usage Examples
### Basic Setup (Automatic Page Views)
With the configuration above, page views are automatically tracked on every route change. No additional code needed!
### Manual Page View with Custom Data
Track page views with additional context:
```javascript
"use client";
import { useEffect } from "react";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
function MyComponent() {
// ✅ ALWAYS pass config - import from centralized config file
const { pageView } = useContentAnalytics(analyticsConfig);
useEffect(() => {
// Track page view with custom data
pageView({
contentType: "blog",
category: "technology",
author: "john-doe",
wordCount: 1500,
});
}, []);
return <div>Content here</div>;
}
```
### Track Custom Events
Track specific user interactions:
```javascript
"use client";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
function CallToActionButton() {
// ✅ ALWAYS pass config - import from centralized config file
const { track } = useContentAnalytics(analyticsConfig);
const handleClick = () => {
// Track custom event
track("cta-click", {
button: "Buy Now",
location: "hero-section",
price: 299.99,
});
};
return <button onClick={handleClick}>Buy Now</button>;
}
```
### Form Submission Tracking
```javascript
"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 submission
track("form-submit", {
formName: "contact-form",
formType: "lead-gen",
source: "homepage",
});
// Submit form...
};
return <form onSubmit={handleSubmit}>{/* Form fields */}</form>;
}
```
### Video/Media Interaction Tracking
```javascript
"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 sources */}
</video>
);
}
```
### E-commerce Product View Tracking
```javascript
"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
track("product-view", {
productId: product.sku,
productName: product.title,
category: product.category,
price: product.price,
inStock: product.inventory > 0,
});
}, [product]);
return <div>{/* Product details */}</div>;
}
```
### Conversion Tracking (E-commerce Purchase)
```javascript
"use client";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
function CheckoutButton({ product, quantity }) {
const { conversion } = useContentAnalytics(analyticsConfig);
const handlePurchase = () => {
// Process checkout logic here...
// After successful payment confirmation:
// Track conversion ONLY after successful purchase
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>;
}
```
### Conversion Tracking (Lead Generation)
```javascript
"use client";
import { useContentAnalytics } from "@dotcms/analytics/react";
import { analyticsConfig } from "@/config/analytics.config";
function DownloadWhitepaper() {
const { conversion } = useContentAnalytics(analyticsConfig);
const handleDownload = () => {
// Trigger download logic here...
// After download is successfully completed:
// Track conversion ONLY after successful download
conversion("download", {
fileType: "pdf",
fileName: "whitepaper-2024.pdf",
category: "lead-magnet",
});
};
return (
<button id="download-btn" onClick={handleDownload}>
Download Whitepaper
</button>
);
}
```
## Configuration Options
### Analytics Config Object
| Option | Type | Required | Default | Description |
| -------------- | ----------------------------- | -------- | ---------------------- | ---------------------------------------------------------------- |
| `siteAuth` | `string` | Yes | - | Site authentication key from dotCMS Analytics |
| `server` | `string` | Yes | - | Your dotCMS server URL |
| `debug` | `boolean` | No | `false` | Enable verbose logging for debugging |
| `autoPageView` | `boolean` | No | `true` (React) | Automatically track page views on route changes |
| `queue` | `QueueConfig | false` | No | Default queue settings | Event batching configuration |
| `impressions` | `ImpressionConfig | boolean` | No | `false` | Content impression tracking (disabled by default) |
| `clicks` | `boolean` | No | `false` | Content click tracking with 300ms throttle (disabled by default) |
### Queue Configuration
Controls how events are batched and sent:
| Option | Type | Default | Description |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `eventBatchSize` | `number` | `15` | Max events per batch - auto-sends when reached |
| `flushInterval` | `number` | `5000` | Time in ms between flushes |
**Disable Queuing** (send immediately):
```javascript
const analyticsConfig = {
siteAuth: "your_key",
server: "https://your-server.com",
queue: false, // Send events immediately
};
```
### Impression Tracking Configuration
Controls automatic tracking of content visibility:
| Option | Type | Default | Description |
| --------------------- | -------- | ------- | ----------------------------------------- |
| `visibilityThreshold` | `number` | `0.5` | Min percentage visible (0.0 to 1.0) |
| `dwellMs` | `number` | `750` | Min time visible in milliseconds |
| `maxNodes` | `number` | `1000` | Max elements to track (performance limit) |
**Enable with defaults:**
```javascript
const analyticsConfig = {
siteAuth: "your_key",
server: "https://your-server.com",
impressions: true, // 50% visible, 750ms dwell, 1000 max nodes
};
```
**Custom thresholds:**
```javascript
const analyticsConfig = {
siteAuth: "your_key",
server: "https://your-server.com",
impressions: {
visibilityThreshold: 0.7, // Require 70% visible
dwellMs: 1000, // Must be visible for 1 second
maxNodes: 500, // Track max 500 elements
},
};
```
**How it works:**
- ✅ Tracks contentlets marked with `dotcms-analytics-contentlet` class and `data-dot-analytics-*` attributes
- ✅ Uses Intersection Observer API for high performance and battery efficiency
- ✅ Only fires when element is ≥50% visible for ≥750ms (configurable)
- ✅ Only tracks during active tab (respects page visibility)
- ✅ One impression per contentlet per session (no duplicates)
- ✅ Automatically disabled in dotCMS editor mode
### Click Tracking Configuration
Controls automatic tracking of user interactions with content elements.
**Enable click tracking:**
```javascript
const analyticsConfig = {
siteAuth: "your_key",
server: "https://your-server.com",
clicks: true, // Enable with 300ms throttle (fixed)
};
```
**How it works:**
- ✅ Tracks clicks on `<a>` and `<button>` elements within contentlets
- ✅ Contentlets must be marked with `dotcms-analytics-contentlet` class and `data-dot-analytics-*` attributes
- ✅ Captures semantic attributes (`href`, `aria-label`, `data-*`) and excludes CSS classes
- ✅ Throttles rapid clicks to prevent duplicate tracking (300ms fixed)
- ✅ Automatically disabled in dotCMS editor mode
**Captured Data:**
For each click, the SDK captures:
- **Content Info**: `identifier`, `inode`, `title`, `content_type`
- **Element Info**:
- `text` - Button/link text (truncated to 100 chars)
- `type` - Element type (`a` or `button`)
- `id` - Element ID (required by backend, empty string if not present)
- `class` - Element CSS classes (required by backend, empty string if not present)
- `href` - Link destination as written in HTML (e.g., `/signup` not `http://...`, only for `<a>`, empty string for buttons)
- `attributes` - Additional useful attributes (see below)
- **Position Info**:
- `viewport_offset_pct` - Position relative to viewport (0-100%)
- `dom_index` - Element position in DOM
**Attributes Object:**
The `attributes` object captures additional semantic data:
✅ **Included** (semantic/analytics value):
- `data-*` - Custom data attributes (e.g., `data-category="primary-cta"`)
- `aria-*` - Accessibility attributes
- `title`, `target` - Standard HTML attributes
❌ **Excluded** (to avoid duplication):
- `class` - Already captured as top-level property
- `id` - Already captured as top-level property
- `href` - Already captured as top-level property
- `data-dot-analytics-*` - Internal SDK attributes
**Adding Custom Analytics Metadata:**
Use `data-*` attributes to enrich click tracking:
```javascript
// In your Next.js component
<a
href="/signup"
id="cta-signup"
data-category="primary-cta"
data-campaign="summer-sale"
aria-label="Sign up for free trial">
Start Free Trial →
</a>
<button
data-action="download"
data-file-type="pdf"
data-category="lead-magnet">
Download Whitepaper
</button>
```
**Complete Configuration Example:**
```javascript
// /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",
queue: {
eventBatchSize: 15,
flushInterval: 5000,
},
impressions: {
visibilityThreshold: 0.5, // 50% visible
dwellMs: 750, // 750ms dwell time
maxNodes: 1000, // Track up to 1000 elements
},
clicks: true, // Enable click tracking (300ms throttle, fixed)
};
```
## Data Captured Automatically
The SDK automatically enriches events with:
### Page View Events
- **Page Data**: URL, title, referrer, path, protocol, search params, hash
- **Device Data**: Screen resolution, viewport size, language, user agent
- **UTM Parameters**: Campaign tracking (source, medium, campaign, term, content)
- **Context**: Site key, session ID, user ID, timestamp
### Custom Events
- **Context**: Site key, session ID, user ID
- **Device Data**: Screen resolution, language, viewport dimensions
- **Custom Properties**: Any data you pass to `track()`
## Session Management
- **Duration**: 30-minute timeout of inactivity
- **Reset Conditions**:
- At midnight UTC
- When UTM campaign changes
- **Storage**: Uses `dot_analytics_session_id` in localStorage
## Identity Tracking
- **Anonymous User ID**: Persisted across sessions
- **Storage Key**: `dot_analytics_user_id`
- **Behavior**: Generated automatically on first visit, reused on subsequent visits
## Testing & Debugging
### Enable Debug Mode
Set `debug: true` in config to see verbose logging:
```javascript
const analyticsConfig = {
siteAuth: "your_key",
server: "https://your-server.com",
debug: true, // Enable debug logging
};
```
### Verify Events in Network Tab
1. Open browser DevTools � Network tab
2. Filter by: `/api/v1/analytics/content/event`
3. Perform actions in your app
4. Check request payloads to see captured data
### Check Storage
Open browser DevTools � Application � Local Storage:
- `dot_analytics_user_id` - Anonymous user identifier
- `dot_analytics_session_id` - Current session ID
- `dot_analytics_session_utm` - UTM campaign data
- `dot_analytics_session_start` - Session start timestamp
## Troubleshooting
### Events Not Appearing
1. **Verify Configuration**:
- Check `siteAuth` and `server` are correct
- Enable `debug: true` to see console logs
2. **Check Network Requests**:
- Look for requests to `/api/v1/analytics/content/event`
- Verify they're returning 200 status
3. **Editor Mode Detection**:
- Analytics are automatically disabled inside dotCMS editor
- Test in preview or published mode
4. **Environment Variables**:
- Ensure `.env.local` is loaded (restart dev server if needed)
- Verify variable names start with `NEXT_PUBLIC_`
### Queue Not Flushing
- Check `eventBatchSize` - might not be reaching threshold
- Verify `flushInterval` is appropriate for your use case
- Events auto-flush on page navigation/close via `visibilitychange`
### Session Not Persisting
- Check localStorage is enabled in browser
- Verify no browser extensions are blocking storage
- Check console for storage-related errors
### Config File Issues
1. **Import Path Not Found**:
```javascript
// ❌ Error: Cannot find module '@/config/analytics.config'
```
- Verify the file exists at `/src/config/analytics.config.js`
- Check your `jsconfig.json` or `tsconfig.json` has the `@` alias configured:
```json
{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"]
}
}
}
```
2. **Undefined Config Values**:
```javascript
// Config shows undefined for siteAuth or server
```
- Verify environment variables are set in `.env.local`
- Restart dev server after changing `.env.local`
- Check variable names start with `NEXT_PUBLIC_`
3. **Config Not Updated**:
- Clear Next.js cache: `rm -rf .next`
- Restart dev server: `npm run dev`
## Integration with Existing Next.js Example
The Next.js example at `/core/examples/nextjs` already uses other dotCMS SDK packages:
- `@dotcms/client` - Core API client
- `@dotcms/experiments` - A/B testing
- `@dotcms/react` - React components
- `@dotcms/types` - TypeScript types
- `@dotcms/uve` - Universal Visual Editor
Adding analytics complements these by providing:
- Usage tracking across all content types
- User behavior insights
- Campaign performance metrics
- Content engagement analytics
## API Reference
### Component: `DotContentAnalytics`
```typescript
interface AnalyticsConfig {
siteAuth: string;
server: string;
debug?: boolean;
autoPageView?: boolean;
queue?: QueueConfig | false;
}
interface QueueConfig {
eventBatchSize?: number;
flushInterval?: number;
}
<DotContentAnalytics config={analyticsConfig} />;
```
### Hook: `useContentAnalytics`
```typescript
interface ContentAnalyticsHook {
pageView: (customData?: Record<string, unknown>) => void;
track: (eventName: string, properties?: Record<string, unknown>) => void;
conversion: (name: string, options?: Record<string, unknown>) => void;
}
// ✅ CORRECT: Always pass config - import from centralized config file
import { analyticsConfig } from "@/config/analytics.config";
const { pageView, track, conversion } = useContentAnalytics(analyticsConfig);
```
**CRITICAL**: The hook **ALWAYS requires config as a parameter**. There is no provider pattern for the hook - `<DotContentAnalytics />` is only for auto pageview tracking and does NOT provide context to child components.
**Always import and pass the centralized config** from `/config/analytics.config.js` to ensure consistency.
### Methods
#### `pageView(customData?)`
Track a page view with optional custom data. Automatically captures page, device, UTM, and context data.
**Parameters**:
- `customData` (optional): Object with custom properties to attach
**Example**:
```javascript
pageView({
contentType: "product",
category: "electronics",
});
```
#### `track(eventName, properties?)`
Track a custom event with optional properties.
**Parameters**:
- `eventName` (required): String identifier for the event (cannot be "pageview" or "conversion")
- `properties` (optional): Object with event-specific data
**Example**:
```javascript
track("button-click", {
label: "Subscribe",
location: "sidebar",
});
```
#### `conversion(name, options?)`
Track a conversion event (purchase, download, sign-up, etc.) with optional metadata.
**⚠️ IMPORTANT: Conversion events are business events that should only be tracked after a successful action or completed goal.** Tracking conversions on clicks or attempts (before success) diminishes their value as conversion metrics. Only track conversions when:
- ✅ Purchase is completed and payment is confirmed
- ✅ Download is successfully completed
- ✅ Sign-up form is submitted and account is created
- ✅ Form submission is successful and data is saved
- ✅ Any business goal is actually achieved
**Parameters**:
- `name` (required): String identifier for the conversion (e.g., "purchase", "download", "signup")
- `options` (optional): Object with conversion metadata (all properties go into `custom` object)
**Examples**:
```javascript
// Basic conversion (after successful download)
conversion("download");
// Conversion with custom metadata (after successful purchase)
conversion("purchase", {
value: 99.99,
currency: "USD",
productId: "SKU-12345",
});
// Conversion with additional context (after successful signup)
conversion("signup", {
source: "homepage",
plan: "premium",
});
```
## Best Practices
1. **Centralize Configuration**: Create a dedicated config file (`/config/analytics.config.js`) for all analytics settings
```javascript
// ✅ GOOD: Centralized config file
// /config/analytics.config.js
export const analyticsConfig = {
siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
debug: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG === "true",
autoPageView: true,
};
// ❌ BAD: Inline config in multiple files
// component1.js
const config = { siteAuth: "...", server: "..." };
// component2.js
const config = { siteAuth: "...", server: "..." }; // Duplicate!
```
2. **Always Import and Pass Config**: The hook requires config as a parameter
```javascript
// ✅ CORRECT: Import centralized config in every component
// MyComponent.js
import { analyticsConfig } from "@/config/analytics.config";
const { track } = useContentAnalytics(analyticsConfig);
// ❌ WRONG: Inline config duplication
// MyComponent.js
const { track } = useContentAnalytics({
siteAuth: "...", // Duplicated!
server: "...", // Duplicated!
});
```
3. **Use DotContentAnalytics for Auto PageViews**: Add to layout for automatic tracking
```javascript
// layout.js - For automatic pageview tracking only
import { analyticsConfig } from "@/config/analytics.config";
<DotContentAnalytics config={analyticsConfig} />;
```
4. **Environment Variables**: Always use environment variables for sensitive config (siteAuth)
5. **Event Naming**: Use consistent, descriptive event names (e.g., `cta-click`, not just `click`)
6. **Custom Data**: Include relevant context in event properties
7. **Queue Configuration**: Use default queue settings unless you have specific performance needs
8. **Debug Mode**: Enable only in development, disable in production
9. **Auto Page Views**: Keep enabled for SPAs (Next.js) to track route changes
## Related Resources
- Analytics SDK README: `/core/core-web/libs/sdk/analytics/README.md`
- Package Location: `/core/core-web/libs/sdk/analytics/`
- Next.js Example: `/core/examples/nextjs/`
## Quick Command Reference
```bash
# Install package
cd /core/examples/nextjs
npm install @dotcms/analytics
# Start Next.js dev server
npm run dev
# Build for production
npm run build
# Start production server
npm run start
# Verify installation
npm list @dotcms/analytics
```
Инициализация мануала...
//
$ ls -R related_skills/
package.json
$ install --global
skills.sh
npx skills add https://github.com/dotCMS/core/tree/main/.claude/skills/sdk-analytics
$ download --local
man
[HINT] Скачивает всю директорию скилла с GitHub: SKILL.md и все связанные файлы