@dotcms/experiments
@dotcms/experiments
is the official dotCMS JavaScript library that helps add A/B testing to your webapps. It handle user assignments to different variants of a page and tracks their interactions.
Features
- User Assignment to Experiments: Automatically assigns users to different experimental variants, ensuring diverse user experiences and reliable test data.
- Link Verification for Redirection: Checks links to ensure users are redirected to their assigned experiment variant, maintaining the integrity of the testing process.
- Automatic PageView Event Sending: Automatically sends PageView events to DotCMS Analytics, enabling real-time tracking of user engagement and experiment effectiveness.
Installation
You can install the package via npm or Yarn:
npm install @dotcms/experiments
Or using Yarn:
yarn add @dotcms/experiments
Components
DotExperimentsProvider
This component utilizes React's Context API to provide DotExperiments instances to its descendants, facilitating access to A/B testing features throughout your webapps.
Props
- config: Configuration object for DotCMS Analytics integration.
- apiKey: Your API key from the DotCMS Analytics app.
- server: The URL of your DotCMS instance.
- redirectFn: The redirect function to use when assigning users to experiment variants.
Usage
import { DotExperimentsProvider } from "@dotcms/experiments";
import { useRouter } from 'next/router';
const { replace } = useRouter();
const experimentConfig = {
apiKey: 'your-api-key-from-dotcms-analytics-app',
server: 'https://your-dotcms-instance.com',
redirectFn: replace
};
return (
<DotExperimentsProvider config={experimentConfig}>
<Header>
<Navigation />
</Header>
<DotcmsLayout />
<Footer />
</DotExperimentsProvider>
);
How A/B Testing Works with @dotcms/experiments
The A/B testing process with @dotcms/experiments
is designed to be straightforward and automatic:
-
Experiment Assignment: When a user visits a page that includes an experiment, the library first checks if the user has been assigned to an experiment variant. If not, it queries DotCMS Analytics to determine if there are active experiments and assigns the user to the appropriate variant.
-
Page Redirection: If the user's assigned variant differs from the current page, the library automatically redirects the user to the correct variant page. This ensures that the user experiences the variant they have been assigned to.
-
Tracking Pageviews: After redirection or upon visiting the page, the library sends a pageview event to DotCMS Analytics. This data is used to determine the effectiveness of each variant, ultimately helping to identify which variant performs better in the A/B test.
Learn More About A/B Testing with DotCMS
For more detailed information on A/B testing features and capabilities, visit the DotCMS A/B testing and experiments page: DotCMS A/B Testing Experiments.
Contributing
GitHub pull requests are the preferred method to contribute code to dotCMS. Before any pull requests can be accepted, an automated tool will ask you to agree to the dotCMS Contributor's Agreement.
Licensing
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 a number of enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see the feature page.
Support
If you need help or have any questions, please open an issue in the GitHub repository.
Documentation
Always refer to the official DotCMS documentation for comprehensive guides and API references.
Getting Help