@ dotcms/分析

内容 Analytics SDK用于在dotCMS驱动的应用程序中跟踪了解内容的事件.

入境点

升级? 套接字根用于再导出 React 绑定, 所以 @dotcms/analytics 财务报告和审定财务报表 @dotcms/analytics/react 解决了同一模块。 该根现在框架中立. 如果导入 useContentAnalytics 或者说 DotContentAnalytics 从根起,添加 /react 说明者——见 移民.md。 。 。 .

我该用哪个SDK版本?

dotCMS SDKs 发布在锁定步骤中,同时发布 dotCMS 本身: 每 @dotcms/* 货包船 地点 完全相同的版本编号 作为点CMS的发布,它是为(例如:点CMS)而建的 26.7.14-1 → @dotcms/[email protected], (中文(简体) ), @dotcms/[email protected],等等).

简单的拇指规则:使用匹配您点CMS实例版本的 SDK 版本.

每次dotCMS发布新版本(反之亦然)时,你不必升级SDK. 大部分的发布都不会改变SDK所依赖的东西,所以一个更老的SDK通常会继续工作 对一个新的点CMS案例,罚款。 但偶尔,释放确实包括一个真正的 打破更改——如果您的 SDK 年龄超过此点, 它会停止正确工作 .

你不需要自己去跟踪它: 你的点CMS实例总是知道最古老的SDK 版本它仍然支持,SDK自动对照它检查自己. 狦琌 使用SDK这个太老了,你会看到一个清晰的警告 在你的控制台上告诉你 升级.

建议: 将您的 SDK 与您的点CMS 实例相同的版本连接, 并且只接通 当您升级了点CMS, 或者当控制台告诉你.

在LTS发布? LTS发行版目前没有获得自己匹配的SDK版本. 在解决之前,请使用所出版的SDK版本,以便最接近定期发布 或者在你的LTS版本之前.

想要更多关于dotCMS发布和支持窗口如何工作的背景吗? 见 发布和支持生命周期( S)。 。 。 .

快速启动

1. 安装

npm install @dotcms/analytics

2. 创建集中配置文件

// 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',
    impressions: true,
    clicks: true
};

3. 在您的布局中添加自动页面视图跟踪

// src/app/layout.js
import { DotContentAnalytics } from '@dotcms/analytics/react';
import { analyticsConfig } from '@/config/analytics.config';

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

4. 部分中的跟踪事件

'use client';

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

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

    const handleSubmit = (e) => {
        e.preventDefault();
        // ... submit form logic ...

        // Track conversion ONLY after successful submission
        conversion('form-submit', {
            formName: 'contact-us',
            formType: 'lead-gen'
        });
    };

    return <form onSubmit={handleSubmit}>{/* form fields */}</form>;
}

理解各组成部分

SDK输出出两个回放原始. 了解他们的作用对正确使用至关重要.

<DotContentAnalytics /> -- 自动页面查看跟踪器

• 内容 仅目的 将自动跟踪路由更改的页面视图
• 没错 没有 a 反应上下文提供者
• 没错 没有 共享与子组件配置
• 将其放入根版式

useContentAnalytics(config) - 手动跟踪钩

• 用于自定义事件、转换和人工页面浏览
• 总是需要 config 作为参数 - 它不从上下文读取
• 在使用钩子的每个组件中导入集中配置

// Every component that tracks events must import config explicitly
import { useContentAnalytics } from '@dotcms/analytics/react';
import { analyticsConfig } from '@/config/analytics.config';

const { track, pageView, conversion } = useContentAnalytics(analyticsConfig);

为什么要集中配置? 您必须在每个组件中导入它, 但有一个文件可以防止重复, 并更容易更新 .

配置

环境变量

把这些添加到您的 .env.local 文件 :

NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY=YOUR_ANALYTICS_SITE_KEY
NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST=http://localhost:8080
NEXT_PUBLIC_DOTCMS_ANALYTICS_DEBUG=true

配置选项

队列配置

控制事件在发送到服务器前的批量 :

• false: 停止排队,立即发送事件
• undefined (默认): 启用默认设置的队列
• QueueConfig 对象: 自定义设置

如何运作:

• 当 eventBatchSize 到达
• 发送待决事件 flushInterval 毫秒
• 在页面导航/关闭时自动显示 visibilitychange + 键 pagehide
• 用途 navigator.sendBeacon() 在卸页时可靠发送

// Disable queuing (send immediately)
export const analyticsConfig = {
    siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
    server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
    queue: false
};

// Custom queue settings
export const analyticsConfig = {
    siteAuth: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_SITE_KEY,
    server: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_HOST,
    queue: {
        eventBatchSize: 10,
        flushInterval: 3000
    }
};

印象跟踪

控制视图中内容能见度的自动跟踪 :

• false 或者说 undefined (默认): 已禁用
• true: 以默认设置启用
• ImpressionConfig 对象: 自定义设置

如何运作:

• 标记为 dotcms-contentlet 类和 data-dot-* 属性
• 性能使用 Intersection 观察 API
• 只当一个元素在所配置的阈值可见并停留时间时起火
• 每个会话的内容片段一个印象( 无重复)
• 在 dotCMS 编辑器模式下自动禁用

// Enable with defaults (50% visible, 750ms dwell)
export const analyticsConfig = {
    // ...required fields
    impressions: true
};

// Custom thresholds
export const analyticsConfig = {
    // ...required fields
    impressions: {
        visibilityThreshold: 0.7,
        dwellMs: 1000,
        maxNodes: 500
    }
};

点击跟踪

控制用户点击内容元素的自动跟踪:

• false 或者说 undefined (默认): 已禁用
• true: 启用了300ms节流阀

如何运作:

• 音轨点击 <a> 财务报告和审定财务报表 <button> 内容中的元素
• 内容必须标记为 dotcms-contentlet 类和 data-dot-* 属性
• 抓取语义属性( E)href, (中文(简体) ), aria-label, (中文(简体) ), data-*)不包括CSS类
• 螺旋快速点击以防止重复( 300ms)
• 在 dotCMS 编辑器模式下自动禁用

每次点击抓取的数据 :

• 内容信息数字 : identifier, (中文(简体) ), inode, (中文(简体) ), title, (中文(简体) ), content_type
• 元素信息数字 : text, (中文(简体) ), type (a/按钮), id, (中文(简体) ), class, (中文(简体) ), href, (中文(简体) ), attributes
• 职位信息数字 : viewport_offset_pct, (中文(简体) ), dom_index

您可以使用 data-* hTML 中的属性 :

<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>

核心概念

事件类型

SDK发送四种类型的事件,由 event_type数字 :

页视图

这个 pageView() 方法跟踪页面导航事件。 这个 自动丰富 活动地址:

• 页面数据: URL、标题、参考者、路径、协议、搜索参数
• 设备数据: 屏幕分辨率、视图大小、语言、用户代理
• UTM 参数:运动跟踪数据(来源、中期、运动、术语、内容)
• A. 背景情况: 站点密钥、会话ID、用户ID、时间戳

您可以选择通过将发送的自定义数据 此外,还有: 所有自动浓缩.

转换跟踪

这个 conversion() 方法跟踪用户转换(购买,下载,签名等).

仅在成功动作或完成目标后进行音轨转换. 跟踪点击或尝试(在成功之前)会降低其作为转换指标的价值。 音轨时间 :

• 采购完成,付款得到确认
• 下载已成功完成
• 提交注册表并创建账户
• 任何商业目标都已经实现

自定义事件

这个 track() 方法跟踪任何自定义用户动作,并带有独特的事件名称和可选属性.

• eventName 无法是 "pageview" 或者说 "conversion" (保留)
• 使用描述性名称 : "button-click", (中文(简体) ), "form-submit", (中文(简体) ), "video-play"等 (中文(简体) ).

会议

• 30分钟无活动暂停
• 协调世界时午夜恢复
• 如果 UTM 活动更改新会话

身份

• 匿名用户标识在会话中持续
• 存储于 dot_analytics_user_id

用法实例

自动页面视图跟踪

添加 DotContentAnalytics 到您的根布局。 不需要额外的代码 -- -- 每一路由更改都跟踪页面浏览.

// src/app/layout.js
import { DotContentAnalytics } from '@dotcms/analytics/react';
import { analyticsConfig } from '@/config/analytics.config';

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

手动带有自定义数据的页面视图

'use client';

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

function BlogPost({ post }) {
    const { pageView } = useContentAnalytics(analyticsConfig);

    useEffect(() => {
        pageView({
            contentType: 'blog',
            category: post.category,
            author: post.author,
            wordCount: post.wordCount
        });
    }, []);

    return <article>{/* post content */}</article>;
}

自定义事件跟踪

'use client';

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

function CallToAction() {
    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>;
}

转换跟踪(真实世界实例)

此示例基于 Next.js 示例应用程序数字 :

'use client';

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

export default function ContactUs({ description }) {
    const [isSubmitting, setIsSubmitting] = useState(false);
    const [isSuccess, setIsSuccess] = useState(false);
    const { conversion } = useContentAnalytics(analyticsConfig);

    const handleSubmit = (e) => {
        e.preventDefault();
        setIsSubmitting(true);

        // Simulate form submission
        setTimeout(() => {
            setIsSuccess(true);

            // Track conversion ONLY after successful submission
            conversion('form-submit', {
                formName: 'contact-us',
                formType: 'lead-gen'
            });
        }, 3000);
    };

    return (
        <form onSubmit={handleSubmit}>
            {/* form fields */}
            <button type="submit" disabled={isSubmitting}>
                {isSubmitting ? 'Submitting...' : 'Submit'}
            </button>
        </form>
    );
}

电子商务

'use client';

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

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

    const handlePurchase = async () => {
        // Process payment...
        const result = await processPayment(product, quantity);

        if (result.success) {
            // Track conversion ONLY after confirmed payment
            conversion('purchase', {
                value: product.price * quantity,
                currency: 'USD',
                productId: product.sku,
                category: product.category
            });
        }
    };

    return <button onClick={handlePurchase}>Complete Purchase</button>;
}

API 参考

<DotContentAnalytics />

在路由变化中自动进行页面查看跟踪的响应组件 .

interface DotContentAnalyticsProps {
    config: DotCMSAnalyticsConfig;
}

在您的根布局中放置一次 。 将内部跟踪器包入 <Suspense> next.js App 路由器兼容性.

useContentAnalytics(config)

反应钩子,返回跟踪方法. 总是需要配置为参数.

function useContentAnalytics(config: DotCMSAnalyticsConfig): DotCMSAnalytics;

interface DotCMSAnalytics {
    /** Track a page view with optional custom data */
    pageView: (customData?: Record<string, unknown>) => void;

    /** Track a custom event (eventName cannot be "pageview" or "conversion") */
    track: (eventName: string, properties?: Record<string, unknown>) => void;

    /** Track a conversion after a successful business action */
    conversion: (name: string, options?: Record<string, unknown>) => void;
}

DotCMSAnalyticsConfig

interface DotCMSAnalyticsConfig {
    server: string;
    siteAuth: string;
    debug?: boolean;
    autoPageView?: boolean;
    queue?: QueueConfig | false;
    impressions?: ImpressionConfig | boolean;
    clicks?: boolean;
}

interface QueueConfig {
    eventBatchSize?: number;
    flushInterval?: number;
}

interface ImpressionConfig {
    visibilityThreshold?: number;
    dwellMs?: number;
    maxNodes?: number;
}

事件有效载荷结构

页面查看事件

当你打电话 pageView(customData?)SDK发送:

{
    context: {
        site_key: string;          // Your site key
        session_id: string;        // Current session ID
        user_id: string;           // Anonymous user ID
        device: {
            screen_resolution: string;
            language: string;
            viewport_width: string;
            viewport_height: string;
        }
    },
    events: [{
        event_type: "pageview",
        local_time: string,        // ISO 8601 timestamp with timezone
        data: {
            page: {                // Captured automatically
                url: string;
                title: string;
                referrer: string;
                path: string;
                doc_host: string;
                doc_protocol: string;
                doc_search: string;
                doc_hash: string;
                doc_encoding: string;
            },
            utm?: {                // Captured automatically (if present in URL)
                source: string;
                medium: string;
                campaign: string;
                term: string;
                content: string;
            },
            custom?: {             // Your optional data from pageView(customData)
                // Any properties you pass
            }
        }
    }]
}

自定义事件

当你打电话 track(eventName, properties)数字 :

{
    context: { /* same as above */ },
    events: [{
        event_type: string,        // Your custom event name
        local_time: string,
        data: {
            custom: {
                // Your properties object
            }
        }
    }]
}

转换事件

当你打电话 conversion(name, options)数字 :

{
    context: { /* same as above */ },
    events: [{
        event_type: "conversion",
        local_time: string,
        data: {
            conversion: {
                name: string;      // Your conversion name
            },
            page: {
                url: string;
                title: string;
            },
            custom?: {             // Your optional data from options parameter
                // All properties from options
            }
        }
    }]
}

单击事件

当点击跟踪被启用,而用户点击内容列表元素时:

{
    "content": {
        "identifier": "abc123",
        "inode": "xyz789",
        "title": "Product Page",
        "content_type": "Page"
    },
    "element": {
        "text": "Start Free Trial",
        "type": "a",
        "id": "cta-signup",
        "class": "btn btn-primary",
        "href": "/signup",
        "attributes": [
            "data-category:primary-cta",
            "data-campaign:summer-sale",
            "aria-label:Sign up for free trial"
        ]
    },
    "position": {
        "viewport_offset_pct": 45.2,
        "dom_index": 2
    }
}

在兜帽男的下面

存储密钥

编辑器检测

分析器在botCMS通用视觉编辑器(UVE)内部时会自动被禁用. 没有以编辑器模式发送事件 .

终点

所有活动均通过 POST 改为:

{server}/api/v1/analytics/content/event

何处 {server} 这是 server 从您的配置值.

调试出问题( T)

启用调试模式

设定 debug: true 在您的配置中看到浏览器控制台上的动词记录.

校验网络标签中的事件

1. 打开浏览器 DevTools > 网络标签
2. 过滤器由 /api/v1/analytics/content/event
3. 在应用程序中执行动作
4. 检查要求有效载荷查看所捕获的数据

检查存储

打开浏览器 DevTools > 应用程序 > 本地存储并查找:

• dot_analytics_user_id
• dot_analytics_session_id
• dot_analytics_session_utm
• dot_analytics_session_start

共同问题

事情没有发生?

• 校验 siteAuth 财务报告和审定财务报表 server 在配置中正确
• 启用 debug: true 查看控制台日志
• 确保环境变量设置在 .env.local (更改后重新启动 dev 服务器)
• 检查变量名称的起始 NEXT_PUBLIC_
• 分析器在 DotCMS 编辑器模式下自动失效 -- 测试在预览或发布模式中

排队不冲?

• 检查 eventBatchSize - 门槛可能尚未达到
• 校验 flushInterval 适合您使用的情况
• 页面导航/关闭中自动擦出的事件 visibilitychange

届会没有持续?

• 检查浏览器是否启用本地Storage
• 校验没有浏览器扩展封存

支助

我们提供多个渠道来获得帮助 点CMS分析SDK:

• GitHub 问题: 对于错误报告和特性请求,请 打开一个问题 在 GitHub 仓库中.
• 社区论坛: 加入我们 社区讨论 以提问和分享解决方案.
• 叠叠流:使用标签 dotcms-analytics 当张贴问题.
• 企业支助:企业客户可通过 dotCMS 支持门户。 。 。 .

在报告问题时,请包括:

• 您使用的 SDK 版本
• 框架/图书馆版本(如果适用)
• 最小复制步骤
• 预期与实际行为

捐款

GitHub 拖取请求是向dotCMS提供代码的首选方法. 我们欢迎对DotCMS分析SDK的贡献! 如果你想作出贡献,请遵循这些步骤:

1. 叉子存储器 点/核心
2. 创建特性分支( E)git checkout -b feature/amazing-feature(中文(简体) )
3. 提交更改( E)git commit -m 'Add some amazing feature'(中文(简体) )
4. 推向分行(git push origin feature/amazing-feature(中文(简体) )
5. 打开拉请求

请确保您的代码遵循现有的样式并包含适当的测试 .

许可证发放

点CMS 可在 业务来源许可证1.1(BSL) 或商业执照.

在BSL下,DotCMS可以免费由个人开发商,小企业或机构在总资金中低于5M美元,也可以由非生产环境下的更大型组织使用. BSL每次发布都会在其发布后四年自动转换为GPL v3. 全文和问题,访问 dotcms.com/bsl (英语) 财务报告和审定财务报表 dotcms.com/bsl-faq (英语)。 。 。 .

大型组织的生产用途,以及管理下的云、服务级协议、支助和企业能力,均根据点集管理系统的商业许可证提供。 关于商业计划、特点和支助选项的详情,见 dotcms.com/定价。 。 。 .