@dotcms/experiments 1.1.1 → 1.2.0-next.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -57
- package/index.esm.js +7 -0
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,105 +1,171 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dotCMS Experiments SDK
|
|
2
2
|
|
|
3
|
-
`@dotcms/experiments` is the official dotCMS JavaScript library that helps add A/B testing to your
|
|
3
|
+
The `@dotcms/experiments` SDK is the official dotCMS JavaScript library that helps add A/B testing to your web applications. It handles user assignments to different variants of a page and tracks their interactions.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Overview
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **Link Verification for Redirection**: Checks links to ensure users are redirected to their assigned experiment variant, maintaining the integrity of the testing process.
|
|
9
|
-
- **Automatic PageView Event Sending**: Automatically sends PageView events to DotCMS Analytics, enabling real-time tracking of user engagement and experiment effectiveness.
|
|
7
|
+
### When to Use It
|
|
10
8
|
|
|
9
|
+
- Adding A/B testing capabilities to your web application
|
|
10
|
+
- Running experiments to optimize user experience
|
|
11
|
+
- Testing different page variants with real users
|
|
12
|
+
- Tracking experiment performance with DotCMS Analytics
|
|
11
13
|
|
|
14
|
+
### Key Features
|
|
15
|
+
|
|
16
|
+
- **User Assignment to Experiments**: Automatically assigns users to different experimental variants, ensuring diverse user experiences and reliable test data
|
|
17
|
+
- **Link Verification for Redirection**: Checks links to ensure users are redirected to their assigned experiment variant, maintaining the integrity of the testing process
|
|
18
|
+
- **Automatic PageView Event Sending**: Automatically sends PageView events to DotCMS Analytics, enabling real-time tracking of user engagement and experiment effectiveness
|
|
19
|
+
|
|
20
|
+
## Table of Contents
|
|
21
|
+
|
|
22
|
+
- [Overview](#overview)
|
|
23
|
+
- [Installation](#installation)
|
|
24
|
+
- [Getting Started](#getting-started)
|
|
25
|
+
- [withExperiments HOC](#withexperiments-higher-order-component)
|
|
26
|
+
- [Configuration Object](#configuration-object)
|
|
27
|
+
- [Usage](#usage)
|
|
28
|
+
- [With @dotcms/react](#with-dotcmsreact-recommended)
|
|
29
|
+
- [Configuration Best Practices](#configuration-best-practices)
|
|
30
|
+
- [How It Works](#how-it-works)
|
|
31
|
+
- [Support](#support)
|
|
32
|
+
- [Contributing](#contributing)
|
|
33
|
+
- [Licensing](#licensing)
|
|
12
34
|
|
|
13
35
|
## Installation
|
|
14
|
-
|
|
36
|
+
|
|
37
|
+
Install the package via npm:
|
|
15
38
|
|
|
16
39
|
```bash
|
|
17
40
|
npm install @dotcms/experiments
|
|
18
41
|
```
|
|
42
|
+
|
|
19
43
|
Or using Yarn:
|
|
20
44
|
|
|
21
45
|
```bash
|
|
22
46
|
yarn add @dotcms/experiments
|
|
23
47
|
```
|
|
24
48
|
|
|
49
|
+
## Getting Started
|
|
50
|
+
|
|
51
|
+
### `withExperiments` Higher-Order Component
|
|
52
|
+
|
|
53
|
+
The SDK exports a single HOC (Higher-Order Component) called `withExperiments` that wraps your page component with experiment functionality. This component handles:
|
|
54
|
+
|
|
55
|
+
- User assignment to experiment variants
|
|
56
|
+
- Automatic redirection to the correct variant
|
|
57
|
+
- Prevention of content flickering during variant loading
|
|
58
|
+
- Automatic page view tracking to dotCMS Analytics
|
|
59
|
+
- Click event handling to maintain variant consistency across navigation
|
|
60
|
+
|
|
61
|
+
### Configuration Object
|
|
25
62
|
|
|
26
|
-
|
|
63
|
+
The `config` object passed to `withExperiments` accepts the following properties:
|
|
27
64
|
|
|
28
|
-
|
|
29
|
-
|
|
65
|
+
- **apiKey** (required): Your API key from the DotCMS Analytics app
|
|
66
|
+
- **server** (required): The URL of your dotCMS instance (e.g., `https://your-dotcms-instance.com`)
|
|
67
|
+
- **redirectFn** (optional): Custom redirect function for SPA navigation (default: `window.location.replace`)
|
|
68
|
+
- **trackPageView** (optional): Enable/disable automatic page view tracking (default: `true`)
|
|
69
|
+
- **debug** (optional): Enable debug logging in the browser console (default: `false`)
|
|
30
70
|
|
|
31
|
-
|
|
32
|
-
- **config**: Configuration object for DotCMS Analytics integration.
|
|
33
|
-
- **apiKey**: Your API key from the DotCMS Analytics app.
|
|
34
|
-
- **server**: The URL of your DotCMS instance.
|
|
35
|
-
- **redirectFn**: The redirect function to use when assigning users to experiment variants.
|
|
71
|
+
## Usage
|
|
36
72
|
|
|
37
|
-
|
|
73
|
+
### With @dotcms/react (Recommended)
|
|
74
|
+
|
|
75
|
+
The recommended approach is to wrap the `DotCMSLayoutBody` component with `withExperiments`. The pattern supports **conditional wrapping** - experiments are only enabled when an API key is configured:
|
|
38
76
|
|
|
39
77
|
```javascript
|
|
40
|
-
|
|
41
|
-
import { useRouter } from 'next/router';
|
|
78
|
+
"use client";
|
|
42
79
|
|
|
43
|
-
|
|
80
|
+
import { withExperiments } from "@dotcms/experiments";
|
|
81
|
+
import { DotCMSLayoutBody, useEditableDotCMSPage } from "@dotcms/react";
|
|
82
|
+
import { useRouter } from 'next/navigation';
|
|
44
83
|
|
|
84
|
+
// Experiment configuration - only applied if apiKey is present
|
|
45
85
|
const experimentConfig = {
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
86
|
+
apiKey: process.env.NEXT_PUBLIC_EXPERIMENTS_API_KEY,
|
|
87
|
+
server: process.env.NEXT_PUBLIC_DOTCMS_HOST,
|
|
88
|
+
debug: true
|
|
49
89
|
};
|
|
50
90
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
91
|
+
export function Page({ pageContent }) {
|
|
92
|
+
const { pageAsset } = useEditableDotCMSPage(pageContent);
|
|
93
|
+
const { replace } = useRouter();
|
|
94
|
+
|
|
95
|
+
// Conditionally wrap with experiments if apiKey is configured
|
|
96
|
+
const DotCMSLayoutBodyComponent = experimentConfig.apiKey
|
|
97
|
+
? withExperiments(DotCMSLayoutBody, {
|
|
98
|
+
...experimentConfig,
|
|
99
|
+
redirectFn: replace
|
|
100
|
+
})
|
|
101
|
+
: DotCMSLayoutBody;
|
|
102
|
+
|
|
103
|
+
return (
|
|
104
|
+
<main>
|
|
105
|
+
<DotCMSLayoutBodyComponent
|
|
106
|
+
page={pageAsset}
|
|
107
|
+
components={pageComponents}
|
|
108
|
+
/>
|
|
109
|
+
</main>
|
|
110
|
+
);
|
|
111
|
+
}
|
|
62
112
|
```
|
|
63
113
|
|
|
64
|
-
|
|
114
|
+
> 📚 **Learn more about `DotCMSLayoutBody`**: See the [@dotcms/react SDK documentation](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/react/README.md#dotcmslayoutbody) for complete details on configuring the layout renderer, component mapping, and available props.
|
|
65
115
|
|
|
66
|
-
|
|
116
|
+
### Configuration Best Practices
|
|
67
117
|
|
|
68
|
-
|
|
118
|
+
- **Use Environment Variables**: Store your API key and server URL in environment variables
|
|
119
|
+
- **Conditional Wrapping**: Only enable experiments when an API key is configured using a ternary operator
|
|
120
|
+
- **Framework Router**: Pass your framework's router function (e.g., `router.replace` for Next.js) to maintain SPA navigation
|
|
121
|
+
- **Debug Mode**: Enable debug logging during development to troubleshoot experiment assignment issues
|
|
69
122
|
|
|
70
|
-
|
|
123
|
+
### How It Works
|
|
71
124
|
|
|
72
|
-
|
|
125
|
+
Once you wrap your component with `withExperiments`, the SDK automatically handles:
|
|
73
126
|
|
|
127
|
+
1. **User Assignment**: Assigns users to experiment variants when they visit a page with an active experiment
|
|
128
|
+
2. **Automatic Redirection**: Redirects users to their assigned variant URL (prevents seeing the wrong variant)
|
|
129
|
+
3. **Flicker Prevention**: Hides content during redirection to avoid showing the wrong variant momentarily
|
|
130
|
+
4. **Navigation Handling**: Maintains variant consistency when users click links
|
|
131
|
+
5. **Analytics Tracking**: Sends pageview events to DotCMS Analytics automatically
|
|
74
132
|
|
|
75
|
-
|
|
133
|
+
All of this happens behind the scenes - you just need to wrap your component and provide the configuration.
|
|
76
134
|
|
|
77
|
-
For
|
|
135
|
+
**Learn More**: For detailed information on creating and managing experiments in dotCMS, visit the [DotCMS A/B Testing Experiments](https://www.dotcms.com/product/ab-testing-experiments) page.
|
|
78
136
|
|
|
137
|
+
## Support
|
|
79
138
|
|
|
80
|
-
|
|
139
|
+
We offer multiple channels to get help with the dotCMS Experiments SDK:
|
|
81
140
|
|
|
82
|
-
GitHub
|
|
141
|
+
- **GitHub Issues**: For bug reports and feature requests, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository
|
|
142
|
+
- **Community Forum**: Join our [community discussions](https://community.dotcms.com/) to ask questions and share solutions
|
|
143
|
+
- **Stack Overflow**: Use the tag `dotcms-experiments` when posting questions
|
|
144
|
+
- **Enterprise Support**: Enterprise customers can access premium support through the [dotCMS Support Portal](https://helpdesk.dotcms.com/support/)
|
|
83
145
|
|
|
84
|
-
|
|
146
|
+
When reporting issues, please include:
|
|
85
147
|
|
|
86
|
-
|
|
148
|
+
- SDK version you're using
|
|
149
|
+
- Framework/library version (if applicable)
|
|
150
|
+
- Minimal reproduction steps
|
|
151
|
+
- Expected vs. actual behavior
|
|
87
152
|
|
|
88
|
-
##
|
|
153
|
+
## Contributing
|
|
154
|
+
|
|
155
|
+
GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the dotCMS Experiments SDK! If you'd like to contribute, please follow these steps:
|
|
89
156
|
|
|
90
|
-
|
|
157
|
+
1. Fork the repository [dotCMS/core](https://github.com/dotCMS/core)
|
|
158
|
+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
159
|
+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
|
160
|
+
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
161
|
+
5. Open a Pull Request
|
|
91
162
|
|
|
92
|
-
|
|
163
|
+
Please ensure your code follows the existing style and includes appropriate tests.
|
|
93
164
|
|
|
94
|
-
|
|
165
|
+
Before any pull requests can be accepted, an automated tool will ask you to agree to the [dotCMS Contributor's Agreement](https://gist.github.com/wezell/85ef45298c48494b90d92755b583acb3).
|
|
166
|
+
|
|
167
|
+
## Licensing
|
|
95
168
|
|
|
96
|
-
|
|
169
|
+
dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://www.dotcms.com/cms-platform/features).
|
|
97
170
|
|
|
98
|
-
|
|
99
|
-
| --------------- | ------------------------------------------------------------------- |
|
|
100
|
-
| Installation | [Installation](https://dotcms.com/docs/latest/installation) |
|
|
101
|
-
| Documentation | [Documentation](https://dotcms.com/docs/latest/table-of-contents) |
|
|
102
|
-
| Videos | [Helpful Videos](http://dotcms.com/videos/) |
|
|
103
|
-
| Forums/Listserv | [via Google Groups](https://groups.google.com/forum/#!forum/dotCMS) |
|
|
104
|
-
| Twitter | @dotCMS |
|
|
105
|
-
| Main Site | [dotCMS.com](https://dotcms.com/) |
|
|
171
|
+
This SDK is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).
|
package/index.esm.js
CHANGED
|
@@ -1673,6 +1673,13 @@ const useExperimentVariant = data => {
|
|
|
1673
1673
|
setShouldWaitForVariant(false);
|
|
1674
1674
|
return;
|
|
1675
1675
|
}
|
|
1676
|
+
// If variantId is not provided, show content and warn
|
|
1677
|
+
if (!variantId) {
|
|
1678
|
+
// eslint-disable-next-line no-console
|
|
1679
|
+
console.warn('[DotExperiments] variantId is required but missing. ' + 'Please ensure the page data includes variantId in viewAs. ' + 'Showing content to prevent blank screen.');
|
|
1680
|
+
setShouldWaitForVariant(false);
|
|
1681
|
+
return;
|
|
1682
|
+
}
|
|
1676
1683
|
const location = typeof window !== 'undefined' ? window.location : undefined;
|
|
1677
1684
|
if (location && dotExperimentInstance) {
|
|
1678
1685
|
const variantAssigned = dotExperimentInstance.getVariantFromHref(location.pathname);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dotcms/experiments",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0-next.10",
|
|
4
4
|
"description": "Official JavaScript library to use Experiments with DotCMS.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -25,13 +25,13 @@
|
|
|
25
25
|
"peerDependencies": {
|
|
26
26
|
"react": ">=18",
|
|
27
27
|
"react-dom": ">=18",
|
|
28
|
-
"@dotcms/client": "^1.
|
|
29
|
-
"@dotcms/react": "^1.
|
|
30
|
-
"@dotcms/uve": "^1.
|
|
31
|
-
"@dotcms/types": "^1.
|
|
28
|
+
"@dotcms/client": "^1.2.0",
|
|
29
|
+
"@dotcms/react": "^1.2.0",
|
|
30
|
+
"@dotcms/uve": "^1.2.0",
|
|
31
|
+
"@dotcms/types": "^1.2.0"
|
|
32
32
|
},
|
|
33
33
|
"module": "./index.esm.js",
|
|
34
34
|
"type": "module",
|
|
35
35
|
"main": "./index.esm.js",
|
|
36
36
|
"types": "./index.esm.d.ts"
|
|
37
|
-
}
|
|
37
|
+
}
|