Rokt UX Helper - Troubleshooting

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

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 correct paths for the library are:

   <!-- CommonJS format (for direct browser usage) -->
   <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
   
   <!-- ESM format (for modern applications) -->
   <script type="module">
     import * as RoktUXHelper from 'https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.mjs';
   </script>

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@0.1.5/dist/index.cjs"></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/dist/index.cjs"></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