Rokt UX Helper Web

The Rokt UX Helper Web is an open source library that enables partner applications to more easily render various user experiences, increasing the velocity of testing and ultimately improving relevancy for the customer. This library provides the flexibility to modify the Rokt optimized user experience before rendering content and exposes various events for the RoktLayout that the application can listen to and may forward to their server.

Resident Experts

• Cris Ryan Tan - [email protected]
• Martin Rubinsztein - [email protected]
• James Newman - [email protected]

Installation

Install the library using npm:

npm install @rokt/ux-helper-web@stable

To use the most stable and production-ready version, the @stable tag is recommended. For testing new features, use @latest.

Usage

1. Register the Web Component

Register the RoktLayoutView component globally in the DOM using the provided function:

import { registerCustomElements } from '@rokt/ux-helper-web';

// Register Rokt custom elements globally
registerCustomElements();

Note: This library supports multiple module formats, including ESModules, CommonJS, and IIFE. The example above demonstrates usage with ESModules; syntax may vary depending on the module format used in your project.

2. Add the Component to Your DOM

You can add the RoktLayoutView component directly in your HTML or interact with it dynamically in your JavaScript code.

Example: Adding the Component in HTML

Even before registering the custom element, you can include the RoktLayoutView tags in your HTML:

<rokt-layout-view id="rokt-placeholder"></rokt-layout-view>

Example: Interacting with the Component in JavaScript

Once the custom element is registered, you can dynamically create and manipulate it in your JavaScript:

// Dynamically create and append the RoktLayoutView element
const layoutView = document.createElement('rokt-layout-view');
layoutView.id = 'rokt-placeholder';
document.body.appendChild(layoutView);

3. Configure and Render Experiences

Before calling any methods on rokt-layout-view elements, ensure the custom element is registered. Once registered, you can configure and render the layout view with experience data fetched from your backend:

// Register Rokt custom elements globally
registerCustomElements();

// This function would load the experiences data from your backend service or similar
const experienceData = fetchExperienceData();
const layoutViews = document.querySelectorAll('rokt-layout-view');

layoutViews.forEach((layoutView) => {
  layoutView.renderExperiences(experienceData);
});

Important: Methods like renderExperiences are only available after the custom element is registered. Ensure registration is completed before invoking these methods.

4. Listen to Events

Track platform and UX-related interactions by listening to custom events:

// RoktPlatformEvent should be listened for and sent to your backend for processing and ultimately sent to Rokt
document.addEventListener('RoktPlatformEvent', (event) => {
  console.log('Platform Event:', event.detail);
});

// RoktUXEvent allow you to react to things like user interaction
document.addEventListener('RoktUXEvent', (event) => {
  console.log('UX Event:', event.detail);
});

Key Directories

• rokt-custom-elements/: Contains web component definitions like RoktLayoutView.
• renderer/: Manages rendering and core application logic.
• utils/: Includes reusable utility functions (e.g., parseUserAgent).
• types/: Defines shared TypeScript interfaces and types.

FAQ

1. Where can I find integration guides?

Refer to the Web integration guide.

2. What are the branches used for?

• main: The primary branch for production-ready code.
• release branches: Used for deploying stable versions.
• feature branches: Experimental or in-development features.