@dotcms/experiments 1.2.0 → 1.2.1

package/README.md

@@ -6,28 +6,31 @@ The `@dotcms/experiments` SDK is the official dotCMS JavaScript library that hel
 
 ### When to Use It
 
-- Adding A/B testing capabilities to your web application
-- Running experiments to optimize user experience
-- Testing different page variants with real users
-- Tracking experiment performance with DotCMS Analytics
+-   Adding A/B testing capabilities to your web application
+-   Running experiments to optimize user experience
+-   Testing different page variants with real users
+-   Tracking experiment performance with DotCMS Analytics
 
 ### Key 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
+-   **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
 
 ## Table of Contents
 
-- [Overview](#overview)
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-  - [Components](#components)
-  - [How A/B Testing Works](#how-ab-testing-works-with-dotcmsexperiments)
-- [Usage](#usage)
-- [Support](#support)
-- [Contributing](#contributing)
-- [Licensing](#licensing)
+-   [Overview](#overview)
+-   [Installation](#installation)
+-   [Getting Started](#getting-started)
+    -   [withExperiments HOC](#withexperiments-higher-order-component)
+    -   [Configuration Object](#configuration-object)
+-   [Usage](#usage)
+    -   [With @dotcms/react](#with-dotcmsreact-recommended)
+    -   [Configuration Best Practices](#configuration-best-practices)
+    -   [How It Works](#how-it-works)
+-   [Support](#support)
+-   [Contributing](#contributing)
+-   [Licensing](#licensing)
 
 ## Installation
 
@@ -45,56 +48,91 @@ yarn add @dotcms/experiments
 
 ## Getting Started
 
-### Components
+### `withExperiments` Higher-Order Component
 
-### `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.
+The SDK exports a single HOC (Higher-Order Component) called `withExperiments` that wraps your page component with experiment functionality. This component handles:
 
-#### Props
+-   User assignment to experiment variants
+-   Automatic redirection to the correct variant
+-   Prevention of content flickering during variant loading
+-   Automatic page view tracking to dotCMS Analytics
+-   Click event handling to maintain variant consistency across navigation
 
--   **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
+### Configuration Object
+
+The `config` object passed to `withExperiments` accepts the following properties:
+
+-   **apiKey** (required): Your API key from the DotCMS Analytics app
+-   **server** (required): The URL of your dotCMS instance (e.g., `https://your-dotcms-instance.com`)
+-   **redirectFn** (optional): Custom redirect function for SPA navigation (default: `window.location.replace`)
+-   **trackPageView** (optional): Enable/disable automatic page view tracking (default: `true`)
+-   **debug** (optional): Enable debug logging in the browser console (default: `false`)
 
 ## Usage
 
+### With @dotcms/react (Recommended)
+
+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:
+
 ```javascript
-import { DotExperimentsProvider } from "@dotcms/experiments";
-import { useRouter } from 'next/router';
+"use client";
 
-const { replace } = useRouter();
+import { withExperiments } from "@dotcms/experiments";
+import { DotCMSLayoutBody, useEditableDotCMSPage } from "@dotcms/react";
+import { useRouter } from 'next/navigation';
 
+// Experiment configuration - only applied if apiKey is present
 const experimentConfig = {
-  apiKey: 'your-api-key-from-dotcms-analytics-app',
-  server: 'https://your-dotcms-instance.com',
-  redirectFn: replace // Use replace from useRouter in Next.js
+    apiKey: process.env.NEXT_PUBLIC_EXPERIMENTS_API_KEY,
+    server: process.env.NEXT_PUBLIC_DOTCMS_HOST,
+    debug: true
 };
 
-return (
-  <DotExperimentsProvider config={experimentConfig}>
-  
-    <Header>
-      <Navigation />
-    </Header>
-    <DotcmsLayout />
-    <Footer />
-    
-  </DotExperimentsProvider>
-);
+export function Page({ pageContent }) {
+    const { pageAsset } = useEditableDotCMSPage(pageContent);
+    const { replace } = useRouter();
+
+    // Conditionally wrap with experiments if apiKey is configured
+    const DotCMSLayoutBodyComponent = experimentConfig.apiKey
+        ? withExperiments(DotCMSLayoutBody, {
+              ...experimentConfig,
+              redirectFn: replace
+          })
+        : DotCMSLayoutBody;
+
+    return (
+        <main>
+            <DotCMSLayoutBodyComponent
+                page={pageAsset}
+                components={pageComponents}
+            />
+        </main>
+    );
+}
 ```
 
-### How A/B Testing Works with @dotcms/experiments
+> 📚 **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.
+
+### Configuration Best Practices
+
+-   **Use Environment Variables**: Store your API key and server URL in environment variables
+-   **Conditional Wrapping**: Only enable experiments when an API key is configured using a ternary operator
+-   **Framework Router**: Pass your framework's router function (e.g., `router.replace` for Next.js) to maintain SPA navigation
+-   **Debug Mode**: Enable debug logging during development to troubleshoot experiment assignment issues
 
-The A/B testing process with `@dotcms/experiments` is designed to be straightforward and automatic:
+### How It Works
 
-1. **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
+Once you wrap your component with `withExperiments`, the SDK automatically handles:
 
-2. **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
+1. **User Assignment**: Assigns users to experiment variants when they visit a page with an active experiment
+2. **Automatic Redirection**: Redirects users to their assigned variant URL (prevents seeing the wrong variant)
+3. **Flicker Prevention**: Hides content during redirection to avoid showing the wrong variant momentarily
+4. **Navigation Handling**: Maintains variant consistency when users click links
+5. **Analytics Tracking**: Sends pageview events to DotCMS Analytics automatically
 
-3. **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
+All of this happens behind the scenes - you just need to wrap your component and provide the configuration.
 
-**Learn More**: For more detailed information on A/B testing features and capabilities, visit the [DotCMS A/B Testing Experiments](https://www.dotcms.com/product/ab-testing-experiments) page.
+**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.
 
 ## Support
 

package/index.esm.js

@@ -1673,6 +1673,13 @@ const useExperimentVariant = data => {
       setShouldWaitForVariant(false);
       return;
     }
+    // If variantId is not provided, show content and warn
+    if (!variantId) {
+      // eslint-disable-next-line no-console
+      console.warn('[DotExperiments] variantId is required but missing. ' + 'Please ensure the page data includes variantId in viewAs. ' + 'Showing content to prevent blank screen.');
+      setShouldWaitForVariant(false);
+      return;
+    }
     const location = typeof window !== 'undefined' ? window.location : undefined;
     if (location && dotExperimentInstance) {
       const variantAssigned = dotExperimentInstance.getVariantFromHref(location.pathname);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/experiments",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Official JavaScript library to use Experiments with DotCMS.",
   "repository": {
     "type": "git",
@@ -25,10 +25,10 @@
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
-    "@dotcms/client": "^1.2.0",
-    "@dotcms/react": "^1.2.0",
-    "@dotcms/uve": "^1.2.0",
-    "@dotcms/types": "^1.2.0"
+    "@dotcms/client": "^1.2.1",
+    "@dotcms/react": "^1.2.1",
+    "@dotcms/uve": "^1.2.1",
+    "@dotcms/types": "^1.2.1"
   },
   "module": "./index.esm.js",
   "type": "module",