Rokt UX Helper - Advanced Usage

This guide covers advanced usage scenarios and features of the Rokt UX Helper library.

Multiple Placement Support

Rokt UX Helper supports multiple placements on a single page. Each placement requires its own rokt-layout-view element with a unique ID:

<!-- Primary placement -->
<rokt-layout-view id="rokt-primary"></rokt-layout-view>

<!-- Secondary placement -->
<rokt-layout-view id="rokt-secondary"></rokt-layout-view>

<!-- Overlay placement -->
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>

When rendering experiences, each placement will only display plugins that match its selector:

// Get the experience data that contains multiple plugins
const experienceData = await fetchExperienceData();

// Render experiences to all placement elements
document.querySelectorAll('rokt-layout-view').forEach(element => {
  element.renderExperiences(experienceData);
});

Element Targeting

Plugins in the experience payload are matched to the appropriate rokt-layout-view element based on the targetElementSelector property in the plugin configuration. The matching rules are:

1. ID Selector: A plugin with targetElementSelector: "#rokt-primary" will target the element with id="rokt-primary".
2. Class Selector: A plugin with targetElementSelector: ".placement-class" will target elements with class="placement-class".
3. Body Selector: A plugin with targetElementSelector: "body" will target elements with the render-overlay attribute.

Event Communication

Sending Events to Layouts

You can also send events to the rendered layouts using the send method. This is useful for communicating with layouts based on actions in your application:

// Send a cart update event to all rendered layouts
await roktElement.send('V2_UPDATE_CART_ITEM', {
    cartItemId: "item-123",
    quantity: 2
});

This is useful for dynamic updates to rendered experiences based on user interactions or external data changes.

Handling Events from All Placements

To centralize event handling, you can listen for events at the document level:

document.addEventListener('RoktUXEvent', (event) => {
  const { pluginId, eventName, data } = event.detail;
  console.log(`UX Event from plugin ${pluginId}:`, eventName, data);
});

document.addEventListener('RoktPlatformEvent', (event) => {
  // Forward all platform events to your backend
  fetch('/api/rokt-events', {
    method: 'POST',
    body: JSON.stringify(event.detail)
  });
});

Cleanup and Error Handling

Proper Cleanup

When a component containing rokt-layout-view is removed, ensure proper cleanup:

// In vanilla JS
function cleanup() {
  const roktElement = document.getElementById('rokt-placement');
  if (roktElement) {
    roktElement.close();
  }
}

// In React
useEffect(() => {
  return () => {
    if (roktRef.current) {
      roktRef.current.close();
    }
  };
}, []);

Error Handling

Implement proper error handling when working with the Rokt UX Helper:

try {
  const experienceData = await fetchExperienceData();
  if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
    console.warn('No experiences to render');
    return;
  }

  roktElement.renderExperiences(experienceData);
} catch (error) {
  console.error('Failed to render Rokt experiences:', error);
  // Implement fallback behavior if needed
}

// Listen for layout failures
roktElement.addEventListener('RoktUXEvent', (event) => {
  if (event.detail.eventName === 'LayoutFailure') {
    console.error('Layout failed to render:', event.detail);
    // Implement fallback behavior
  }
});

Performance Considerations

For optimal performance when using Rokt UX Helper:

1. Lazy Loading: Consider lazy loading the Rokt UX Helper library, especially if the experiences are not visible immediately:

// Load the library only when needed
function loadRoktUXHelper() {
  return import('@rokt/ux-helper-web').then(() => {
    console.log('Rokt UX Helper loaded');
    // Initialize and render experiences
  });
}

// Use with Intersection Observer for visibility-based loading
const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting) {
    loadRoktUXHelper();
    observer.disconnect();
  }
}, { threshold: 0.1 });

observer.observe(document.getElementById('rokt-container'));