@dotcms/experiments

中文文档
26.11.17-1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5049

官方JavaScript库使用实验与DotCMS.

中文使用文档
文档目录20 节
  1. 概览
  2. 何时使用
  3. 关键特性
  4. 目录
  5. 安装
  6. 我该用哪个SDK版本?
  7. 开始
  8. 公共 API
  9. withExperiments 上级部分
  10. 配置对象
  11. 使用量
  12. 用 @ dotcms/ react( 建议)
  13. Next.js App路由器
  14. 配置最佳做法
  15. 反间谍
  16. 如何运作
  17. 解决问题
  18. 支助
  19. 捐款
  20. 许可证发放

点CMS 实验 SDK

这个 @dotcms/experiments SDK是官方的dotCMS JavaScript库,帮助在您的网络应用程序中添加A/B测试. 它处理一个页面的不同变体的用户任务,并跟踪其相互作用.

概览

何时使用

  • 在您的网络应用程序中添加 A/B 测试能力
  • 运行实验以优化用户体验
  • 对真实用户测试不同的页面变体
  • 用 DotCMS 分析跟踪实验性能

关键特性

  • 用户指定给实验: 自动指派用户到不同的实验变体,确保不同的用户体验和可靠的测试数据
  • 重定向的链接验证:检查链接以确保用户被重定向到指定的实验变体,保持测试过程的完整性
  • 自动查看事件发送: 自动将 PageView 事件发送给 DotCMS 分析器, 从而能够实时跟踪用户参与和实验效果

目录

安装

通过 npm 安装软件包 :

npm install @dotcms/experiments

或用雅兰:

yarn add @dotcms/experiments

我该用哪个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)。 。 。 .

开始

公共 API

软件包导出 一个 公共符号 :

导出说明
withExperiments包装布局组件的 HOC( 通常为 DotCMSLayoutBody实验处理

DotExperimentsProvider 其他内部因素有: 没有 部分为公共API. 不要导入它们—— withExperiments 内接供养.

withExperiments 上级部分

withExperiments 用实验功能将您的页面组件包起来 :

  • 给实验变体分配用户任务
  • 自动重定向到正确的变体
  • 防止内容在变异装入时闪烁
  • 自动页面视图跟踪到 dotCMS 分析
  • 点击事件处理以保持整个导航的变体一致性

重要内容: withExperiments 内部使用反应钩. 必须叫它 无条件 在使用它的部件的每个成像上。 见 反间谍。 。 。 .

配置对象

这个 config 对象传递到 withExperiments 接受下列属性:

财产需求默认说明
apiKey对—— 说jsKey from the dotCMS Analytics / Experiments app(前端密钥,不是m2m) 的相接键
server对—— 说点CMS 来源 URL(例如:. https://your-dotcms-instance.com(-不是一个CDN)
redirectFn没有window.location.replaceSPA重定向函数(如:. router.replace 在下一个.js中)
trackPageView没有true启用/ 禁用自动页面视图跟踪
debug没有false浏览器控制台的 Verbose 记录

使用量

使用 单独视图或路径 有实验和没有实验的页。 这样可以避免呼叫 withExperiments 有条件地在同一部分.

// views/StandardPage.tsx — no experiments
"use client";

import { DotCMSLayoutBody, useEditableDotCMSPage } from "@dotcms/react";

import { pageComponents } from "@/components/content-types";

export function StandardPage({ pageContent }) {
    const { pageAsset } = useEditableDotCMSPage(pageContent);

    return (
        <main>
            <DotCMSLayoutBody page={pageAsset} components={pageComponents} />
        </main>
    );
}
// views/ExperimentsPage.tsx — experiments always enabled on this view
"use client";

import { withExperiments } from "@dotcms/experiments";
import { DotCMSLayoutBody, useEditableDotCMSPage } from "@dotcms/react";
import { useRouter } from "next/navigation";

import { pageComponents } from "@/components/content-types";

export function ExperimentsPage({ pageContent }) {
    const { pageAsset } = useEditableDotCMSPage(pageContent);
    const { replace } = useRouter();

    const LayoutBody = withExperiments(DotCMSLayoutBody, {
        apiKey: process.env.NEXT_PUBLIC_DOTCMS_ANALYTICS_KEY!,
        server: process.env.NEXT_PUBLIC_DOTCMS_HOST!,
        redirectFn: replace,
        debug: process.env.NEXT_PUBLIC_DOTCMS_DEBUG === "true",
    });

    return (
        <main>
            <LayoutBody page={pageAsset} components={pageComponents} />
        </main>
    );
}

在 App 路由器中将每个视图连接到自己的路线( 例如) /blog 用于实验,标准页的全集).

学习更多关于 DotCMSLayoutBody: 见 @ dotcms/ react SDK 文档。 。 。 .

Next.js App路由器

实例: examples/nextjs-analytics-experiments

该项目表明:

  • 所有路线的分析 @dotcms/analytics 内 layout.tsx
  • 实验 /blog 通过 withExperiments 在专用视图中
  • 在UVE避免违反规则的安全隔离

环境变量 (见实例) .env.local.example:

NEXT_PUBLIC_DOTCMS_HOST=http://localhost:8080      # dotCMS origin — NOT a CDN
NEXT_PUBLIC_DOTCMS_ANALYTICS_KEY=                  # jsKey (frontend key)
NEXT_PUBLIC_DOTCMS_DEBUG=true

核查 (DevTools 网络):

  1. 在试验路线上: POST {HOST}/api/v1/experiments/isUserIncluded
  2. 与 debug: true数字 : [dotCMS ...] 控制台中的日志
  3. 在 UVE 中打开页面 — 没有“ 客户端例外” 覆盖

配置最佳做法

  • 使用环境变量 页:1 apiKey 财务报告和审定财务报表 server
  • 专用路线/景点 用于实验页面——不要切换 withExperiments 上面有一个三角星 apiKey 在同一个部分
  • 框架路由器: 通过 router.replace (下个js)或等同于 redirectFn 用于SPA 导航
  • 来源 URL数字 : server 必须指向点CMS实例源。 不要使用 Azure Front Door, CloudFront, 或其他 CDNs —— 实验 API 响应是会话特定的, 并且不能被缓存在边缘
  • 对齐的 SDK 版本: 保留 @dotcms/client, (中文(简体) ), @dotcms/react, (中文(简体) ), @dotcms/uve, (中文(简体) ), @dotcms/types,以及 @dotcms/experiments 在同一版本线上
  • 调试模式: 使开发期间能够解决任务问题

反间谍

执行 没有 使用这些模式——它们可以崩溃 Next.js App Router 页面和 UVE 编辑器:

// ❌ Conditional withExperiments — violates rules of hooks
const Layout = experimentConfig.apiKey
    ? withExperiments(DotCMSLayoutBody, config)
    : DotCMSLayoutBody;

// ❌ Early return before withExperiments in the same component
if (!apiKey) return <DotCMSLayoutBody {...props} />;
const Layout = withExperiments(DotCMSLayoutBody, config);

// ❌ Importing internal provider
import { DotExperimentsProvider } from "@dotcms/experiments";

// ❌ CDN as server
server: "https://cdn.example.com"

使用单独的组件/路由(参见 用 @ dotcms/ 反应) (中文(简体) ).

如何运作

一旦你包装你的组件 withExperiments,SDK自动处理:

  1. 用户指定: 用户访问有活性实验的页面时指定实验变体
  2. 自动重定向: 将用户重定向到指定变量 URL( 防止看到错误的变量)
  3. 防闪烁: 重定向时隐藏内容,以避免立即显示错误的变体
  4. 导航处理: 用户点击链接时保持变体一致性
  5. 分析跟踪: 将页面视图事件自动发送到 DotCMS 分析器

学习更多数字 : DotCMS A/B 测试实验

解决问题

症状可能的原因是怎么办
UVE 崩溃: “ 发生了客户端例外 ”withExperiments 或者在UVE状态准备好之前进行初始化实验使用专门的实验视图; 从不使用 apiKey ? withExperiments(...) : DotCMSLayoutBody
GET /api/v1/experiments/DEFAULT 404 (韩语)已知后台问题-变体名 "DEFAULT" 以实验身份通过无头应用程序无害; 后台另跟踪
"没有指派给客户的实验"不在试验中 Running 状态,或尚未分析确认点CMS中的实验状态; 校验 apiKey 财务报告和审定财务报表 server
没有 isUserIncluded 请求失踪 apiKey,错误的路径,或未挂载的实验视图请检查env vars; 确认页面使用实验视图
事件到错误的主机server 指向 CDN 而不是点CMS 来源设定 server 到点CMS实例 URL

支助

在报告问题时,包括SDK版本,框架版本,最小复制步骤,以及预期对实际行为.

捐款

  1. 叉头 点/核心
  2. 创建特性分支
  3. 提交更改
  4. 打开拉请求

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

在接受任何拉动请求之前,一个自动工具会请您同意 dotCMS 贡献者协议。 。 。 .

许可证发放

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

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

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

版本与发布记录

@dotcms/experiments 共发布 335 个版本,首次发布于 2024/04/13;过去 12 个月发布了 193 个版本。

版本发布日期距今
26.11.17-1latest2026/11/17今天
26.11.2-3-next.3107next2026/11/161 天前
26.11.2-3-next.30882026/11/135 天前
26.11.2-32026/11/125 天前
26.11.11-12026/11/116 天前
26.11.10-22026/11/117 天前

其他发布通道:alpha → 0.0.1-alpha.62,next → 26.11.2-3-next.3107。

关于 @dotcms/experiments 的常见问题

@dotcms/experiments 是什么?

官方JavaScript库使用实验与DotCMS.

如何安装 @dotcms/experiments?

在项目目录运行 npm install @dotcms/experiments,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=18)、react-dom(>=18)、@dotcms/uve(26.11.17-1)、@dotcms/react(26.11.17-1)、@dotcms/types(26.11.17-1)、@dotcms/client(26.11.17-1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@dotcms/experiments 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@dotcms/experiments 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@dotcms/experiments 可以商用吗?

@dotcms/experiments 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@dotcms/experiments 的下载量有多少?

根据 npm 官方下载统计,@dotcms/experiments 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,049 次,日均约 168 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@dotcms/experiments 还在维护吗?

最新版本 26.11.17-1 发布于 2026/11/17(今天);至今共发布 335 个版本,其中过去 12 个月发布了 193 个;首次发布于 2024/04/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。