Rokt UX Helper - Troubleshooting

This guide addresses common issues that might arise when implementing the Rokt UX Helper library and provides solutions.

Installation Issues

ERESOLVE peer conflict on react

If npm install fails before anything else happens:

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error While resolving: your-app@1.0.0
npm error Found: react@18.3.1
npm error Could not resolve dependency:
npm error peer react@"^19.2.8" from @rokt/ux-helper-web@2.0.0

React 19 is required from v2.0.0 onward. Either upgrade your app to React 19 (see the React 19 upgrade guide), or stay on the 1.x line, which takes React 18:

npm install @rokt/ux-helper-web@^1.0.2

There are no API changes in v2.0.0. Your markup, your renderExperiences() call and your event handlers all stay as they are, so moving between the two lines is a dependency change only.

Do not force past this with --legacy-peer-deps. The dist/ builds externalize React so your app supplies the single copy everyone shares, and that copy has to be one the renderer supports.

Could not resolve "@emotion/css" at build time

If your bundler fails on an import the library makes:

Could not resolve "@emotion/css"

The dist/ builds leave React and the rest of the render stack unbundled so your app dedupes them, which makes them peerDependencies your app supplies. npm 7 and later install peers automatically, but some package managers do not, and pinning peers yourself can leave one out. Install the package the error names, or check the full peer table in the Web UX Helper installation guide.

This applies to the dist/ builds only. The CDN bundle at build/rokt-ux-helper-web.js inlines everything, so it has no peer requirements.

Common Issues

Experiences Not Rendering

If your experiences aren't appearing on the page:

1. Element Selectors Don't Match: Ensure that the targetElementSelector in your experience payload matches the ID or class of your rokt-layout-view element.

   // Check the plugin configuration in your response
   console.log(experienceData.plugins.map(plugin => plugin.plugin.targetElementSelector));
   
   // Make sure these selectors match your elements
   console.log(document.querySelector('rokt-layout-view').id); // Should match one of the selectors

2. Empty or Invalid Payload: Verify that your experience payload is valid and contains plugins.

   // Validate the payload structure
   if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
     console.error('No valid experience data available');
   }

3. Custom Element Not Registered: Ensure the custom elements are properly registered.

   // Check if the element is registered
   console.log(!!customElements.get('rokt-layout-view'));
   
   // Register manually if needed
   import { registerCustomElements } from '@rokt/ux-helper-web';
   registerCustomElements();

4. Multiple Overlay Elements: Only the first rokt-layout-view with the render-overlay attribute will receive overlay experiences. Check your implementation if you have multiple overlay elements.

CDN Issues

If you're facing issues with loading the library from CDN:

1. Incorrect CDN Path: The only browser-loadable artifact is the IIFE bundle at build/rokt-ux-helper-web.js. It exposes a RoktUXHelper global and registers the custom elements as soon as it loads:

   <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/build/rokt-ux-helper-web.js"></script>

   If you see require is not defined or Cannot use import statement outside a module, you are loading one of the bundler builds from a <script> tag. dist/index.cjs starts with require("react/jsx-runtime"), and dist/index.mjs leaves bare react and @emotion/css imports for a bundler to resolve. A browser cannot resolve either. Point the <script> tag at build/rokt-ux-helper-web.js instead.

2. Version Issues: If a version is giving you trouble, try specifying an exact version:

   <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@2.0.0/build/rokt-ux-helper-web.js"></script>

3. CORS Issues: If you're experiencing CORS errors, ensure your server is configured to allow the CDN domain.

4. Network Issues: Check your browser's network tab to verify the CDN files are being loaded correctly.

Console Errors

"Failed to construct 'CustomElement'"

If you see errors related to constructing custom elements:

Uncaught DOMException: Failed to construct 'CustomElement': The result must not have attributes

This typically occurs in older browsers or with polyfills. Ensure you're using the latest version of the library and consider adding polyfills for older browsers:

<script src="https://unpkg.com/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/build/rokt-ux-helper-web.js"></script>

"Cannot read property 'renderExperiences' of null"

This error occurs when trying to call methods on an element that doesn't exist in the DOM:

Uncaught TypeError: Cannot read property 'renderExperiences' of null

Ensure the element exists before trying to use it:

const roktElement = document.getElementById('rokt-layout-placeholder');
if (roktElement) {
  roktElement.renderExperiences(experienceData);
} else {
  console.error('Element #rokt-layout-placeholder not found in DOM');
}

Layout Issues

"Warning: Multiple overlay plugins detected"

If you see a warning about multiple overlay plugins:

WARNING: Multiple overlay plugins detected. Only rendering the first one.

This means you have multiple plugins targeting the body selector. Only the first one will be rendered. If you need to render multiple overlays, consider using different placement strategies.

Experiences Not Visible But Present in DOM

If experiences are rendered in the DOM but not visible:

1. Check for CSS Issues: Inspect the element and verify no CSS is hiding the content:

   /* Add this temporarily to debug */
   rokt-layout-view {
     border: 1px solid red;
     min-height: 50px;
   }

Event Handling Issues

Events Not Firing

If you're not receiving events:

1. Event Listeners Attached Too Late: Ensure event listeners are attached before rendering experiences:

   // Correct order
   roktElement.addEventListener('RoktUXEvent', handleUXEvent);
   roktElement.addEventListener('RoktPlatformEvent', handlePlatformEvent);
   roktElement.renderExperiences(experienceData);

2. Event Bubbling Issues: Check if events are being stopped from propagating in a parent element:

   // Use capturing phase to intercept events earlier
   document.addEventListener('RoktUXEvent', handleUXEvent, true);
   document.addEventListener('RoktPlatformEvent', handlePlatformEvent, true);

Platform Events Not Being Processed

If Rokt platform events aren't being correctly processed:

1. Incorrect Event Payload: Ensure you're forwarding the complete event payload:

   roktElement.addEventListener('RoktPlatformEvent', (event) => {
     // Send the ENTIRE detail object, don't modify it
     sendToBackend(event.detail);
   });

2. Network Issues: Verify that events are being sent to the correct endpoint with proper authentication.

React Specific Issues

TypeScript Errors

If you're getting TypeScript errors with React:

1. Missing Custom Element Declaration: Ensure you've declared the custom element:

   declare global {
     namespace JSX {
       interface IntrinsicElements {
         "rokt-layout-view": React.DetailedHTMLProps<
           React.HTMLAttributes<HTMLElement> & {
             ref?: React.RefObject<HTMLElement>;
           },
           HTMLElement
         >;
       }
     }
   }

2. Type Casting Issues: Use proper type casting for events:

   const handleUXEvent = (event: Event) => {
     // Cast to CustomEvent to access detail property
     const customEvent = event as CustomEvent;
     console.log(customEvent.detail);
   };

Ref Issues

If you're having issues with React refs:

// Use correct ref type and access pattern
const roktRef = useRef<HTMLElement & {
  renderExperiences: (data: any) => void;
  close: () => void;
}>(null);

// Later in your code
if (roktRef.current) {
  roktRef.current.renderExperiences(data);
}

Getting Help

If you're still experiencing issues after trying these solutions, you can:

1. Check the GitHub repository for open issues or create a new one
2. Review the full API documentation
3. Contact Rokt Support for additional assistance