点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.replace | SPA重定向函数(如:. router.replace 在下一个.js中) |
trackPageView | 没有 | true | 启用/ 禁用自动页面视图跟踪 |
debug | 没有 | false | 浏览器控制台的 Verbose 记录 |
使用量
用 @ dotcms/ react( 建议)
使用 单独视图或路径 有实验和没有实验的页。 这样可以避免呼叫 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 网络):
- 在试验路线上:
POST {HOST}/api/v1/experiments/isUserIncluded - 与
debug: true数字 :[dotCMS ...]控制台中的日志 - 在 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自动处理:
- 用户指定: 用户访问有活性实验的页面时指定实验变体
- 自动重定向: 将用户重定向到指定变量 URL( 防止看到错误的变量)
- 防闪烁: 重定向时隐藏内容,以避免立即显示错误的变体
- 导航处理: 用户点击链接时保持变体一致性
- 分析跟踪: 将页面视图事件自动发送到 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 |
支助
- GitHub 问题数字 : 打开一个问题
- 社区论坛数字 : 社区. dotcms.com
- 叠叠流标签
dotcms-experiments - 企业支助数字 : 点CMS 支持
在报告问题时,包括SDK版本,框架版本,最小复制步骤,以及预期对实际行为.
捐款
- 叉头 点/核心
- 创建特性分支
- 提交更改
- 打开拉请求
请确保您的代码遵循现有的样式并包含适当的测试 .
在接受任何拉动请求之前,一个自动工具会请您同意 dotCMS 贡献者协议。 。 。 .
许可证发放
点CMS 可在 业务来源许可证1.1(BSL) 或商业执照.
在BSL下,DotCMS可以免费由个人开发商,小企业或机构在总资金中低于5M美元,也可以由非生产环境下的更大型组织使用. BSL每次发布都会在其发布后四年自动转换为GPL v3. 全文和问题,访问 dotcms.com/bsl (英语) 财务报告和审定财务报表 dotcms.com/bsl-faq (英语)。 。 。 .
大型组织的生产用途,以及管理下的云、服务级协议、支助和企业能力,均根据点集管理系统的商业许可证提供。 关于商业计划、特点和支助选项的详情,见 dotcms.com/定价。 。 。 .