Skip to main content

Web UX Helper

Rokt UX Helper is an open source project that helps you render beautiful customer experiences in a server-to-server environment. You can find and contribute to the project on GitHub.

OverviewDirect link to Overview

Rokt UX Helper leverages web components technology to provide a simple, maintainable solution for rendering Rokt experiences on your website. The rokt-layout-view custom element handles the rendering of experiences based on the payload received from your server.

Integration StepsDirect link to Integration Steps

This document outlines the process for integrating Rokt UX Helper into your web project, which works alongside the Server-to-Server integration (S2S) to deliver relevant experiences to your customers as they checkout.

πŸ“¦ Installation GuideDirect link to πŸ“¦ Installation Guide

The library is available as an npm package. To install it, use the following command:

npm install @rokt/ux-helper-web

This gives you the current stable release. To pin an exact version:

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

πŸ”Ή Version Tags ExplainedDirect link to πŸ”Ή Version Tags Explained

  • @latest: The current stable, production-ready release. This is what you get when you install without a tag, and it is the right choice for production.

  • @next: Pre-release builds. This tag only moves when a pre-release is published, so it can trail @latest by several major versions. Do not install from it blindly. If you are testing a pre-release, list what is actually published and pin the exact version instead:

    npm view @rokt/ux-helper-web dist-tags versions
    npm install @rokt/ux-helper-web@<version>

These are the only two tags. There is no @stable tag; npm install @rokt/ux-helper-web@stable fails with a 404.

RequirementsDirect link to Requirements

React 19 (^19.2.8) is required from v2.0.0 onward. Earlier versions took React 18. If you are still on React 18, stay on the 1.x line with npm install @rokt/ux-helper-web@^1.0.2.

The dist/ builds deliberately leave React and the rest of the render stack unbundled so your app dedupes them instead of running a second copy. That means they are peerDependencies, and your app supplies them:

PeerRange
react, react-dom^19.2.8
@reduxjs/toolkit^2.5.1
react-redux^9.0.2
redux-saga, @redux-saga/core^1.3.0
@emotion/css^11.10.6
embla-carousel-react^8.0.0
embla-carousel-autoplay, embla-carousel-fade^8.6.0
insane^2.6.2
ramda^0.30.1

npm 7 and later install peers automatically, so usually there is nothing to do. If your package manager does not, or you pin peers yourself, a missing one surfaces at build time as Could not resolve "@emotion/css" or similar. Installing v2 into a React 18 app fails earlier than that, at install time, with an ERESOLVE conflict on peer react@"^19.2.8". The troubleshooting guide covers both cases.

CDN UsageDirect link to CDN Usage

If you prefer to use a CDN, load the IIFE bundle. It inlines everything in the table above, including React, so it has no peer requirements and your page's own React version does not matter. It exposes a RoktUXHelper global and registers the custom elements as soon as it loads:

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

<!-- Or pin an exact version -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@2.0.0/build/rokt-ux-helper-web.js"></script>

dist/index.cjs and dist/index.mjs are the bundler builds and cannot be loaded from a <script> tag. dist/index.cjs starts with require("react/jsx-runtime"), which a browser cannot resolve, and dist/index.mjs leaves bare react and @emotion/css imports for a bundler to resolve.

Add rokt-layout-viewDirect link to Add rokt-layout-view

To start using Rokt UX Helper you need to add the bundled Rokt UX Helper script, add rokt-layout-view to the relevant part of your HTML view add your JavaScript.

<head>
  <!-- Link to your Rokt UX Helper JavaScript -->
  <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/build/rokt-ux-helper-web.js"></script>
</head>

<body>
  <!-- Your content -->

  <!-- Note the ID which is used in the JavaScript below -->
  <rokt-layout-view id="rokt-layout-placeholder"></rokt-layout-view>

  <!-- Your content -->

  <!-- This is the JavaScript that handles events described below -->
  <script src="./index.js"></script>
</body>

Register element and render the payloadDirect link to Register element and render the payload

Now you've added your rokt-layout-view you need to register it and pass in the payload to be rendered.

index.js
// This function would load the experiences data from your backend service or similar
const payload = fetchExperienceData();

const roktElement = document.getElementById("rokt-layout-placeholder");
roktElement.renderExperiences(payload);

// Note: The custom elements are automatically registered when the library is loaded,
// so you don't need to explicitly call registerCustomElements()

Handling overlay experiencesDirect link to Handling overlay experiences

To support overlay experiences that target the body selector, add the render-overlay attribute:

<body>
  <!-- Your content -->

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

  <!-- Your content -->
  <script src="./index.js"></script>
</body>

Event HandlingDirect link to Event Handling

Rokt UX Helper provides two types of events to help you track user interactions and communicate with the Rokt platform.

UX EventsDirect link to UX Events

Use UX Events to receive real-time feedback on user interactions:

roktElement.addEventListener('RoktUXEvent', (event) => {
    // Use these events to tailor your user experience
    console.log('RoktUXEvent received:', event.detail);
});
All UX Events
EventDescription
OfferEngagementTriggered when the user engages with the offer
PositiveEngagementTriggered when the user positively engages with the offer
LayoutInteractiveTriggered when a layout is rendered and interactable
LayoutClosedTriggered when a layout is closed by the user
LayoutCompletedTriggered when the offer progression ends with no more offers to display
LayoutFailureTriggered when a layout fails to display

Platform EventsDirect link to Platform Events

Platform events are essential for integration and must be sent to Rokt via your backend. These events return a full JSON payload with event data and integration details:

roktElement.addEventListener('RoktPlatformEvent', (event) => {
    // Forward this payload to Rokt via your backend
    fetch('/api/rokt-events', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(event.detail)
    });
});
Example Platform Event Payload
{
    "events": [
        {
            "eventType": "SignalImpression",
            "eventTime": "2024-12-05T04:42:54.683Z",
            "sessionId": "b23d004d-b2e6-43e9-b254-d9193e650000",
            "parentGuid": "9b6f0e5b-621d-4597-8a73-71d6a5b43a74",
            "pageInstanceGuid": "b23d004d-b2e6-4b82-b7a2-84a13b6c57c5",
            "metadata": [
                {
                    "name": "clientTimeStamp",
                    "value": "2024-12-05T04:42:54.683Z"
                },
                {
                    "name": "captureMethod",
                    "value": "ClientProvided"
                }
            ]
        }
    ],
    "integration": {
        "name": "UX Helper Web",
        "version": "1.0",
        "framework": "JS",
        "platform": "Web",
        "layoutSchemaVersion": "1.3.0",
        "deviceLocale": "en-GB",
        "deviceModel": "Desktop Computer",
        "deviceType": "Desktop",
        "operatingSystem": "MacOS",
        "operatingSystemVersion": "10.15.7",
        "packageName": "UX Helper Web",
        "packageVersion": "1.0"
    },
    "pluginId": "3333926045359669274"
}

For more details on Platform Events, refer to the API reference.

Forwarding to the Session API (v2)Direct link to Forwarding to the Session API (v2)

The payload above is the V1 /events shape and can be posted as is on V1. If your backend calls /v2/sessions/events instead, convert it with buildRecordEventsRequest before forwarding:

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

roktElement.addEventListener('RoktPlatformEvent', async (event) => {
    const body = buildRecordEventsRequest(event.detail, {
        channelType: 's2s',
        singleSession: true
    });

    // Your own backend, which holds rpub/rsec and posts to /v2/sessions/events
    await fetch('/api/rokt-events', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(body)
    });
});

channelType must match the channel your credential is provisioned for, and single_session is required on the request, so both are set explicitly above rather than left at the helper's defaults. The conversion is not the whole request: server-to-server takes four event types, and each event needs an instance_id and a data.token that a platform event does not carry. The advanced guide shows what to add, along with the full option list, event type mapping and field mapping.

Sending Events to LayoutsDirect link to 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 example sends a cart item update event that layouts can respond to, such as updating promotional offers based on quantities.

SummaryDirect link to Summary

Integrating rokt-layout-view into your project is straightforward and provides a flexible way to manage views and experiments. By following the steps outlined in this guide, you can add rokt-layout-view into your project and take full advantage of the powerful features offered by Rokt UX Helper.

Complete ExampleDirect link to Complete Example

HTMLDirect link to HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Rokt UX Helper</title>
    <link rel="stylesheet" href="./index.css" />

    <!-- Load Rokt UX Helper from CDN -->
    <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/build/rokt-ux-helper-web.js"></script>
  </head>
  <body>
    <h1>Rokt UX Helper Demo</h1>

    <!-- Note the ID which is used in the JavaScript below -->
    <!-- It is possible to use a single `rokt-layout-view` element to handle your embedded and overlay layouts -->
    <rokt-layout-view
      id="rokt-layout-placeholder"
      render-overlay
    ></rokt-layout-view>

    <script src="./index.js"></script>
  </body>
</html>

JavaScriptDirect link to JavaScript

index.js
// This function would load the experiences data from your backend service
const payload = fetchExperienceData();

const roktElement = document.getElementById("rokt-layout-placeholder");

roktElement.addEventListener("RoktUXEvent", (event) => {
  console.log("RoktUXEvent received: ", event.detail);
});

roktElement.addEventListener("RoktPlatformEvent", (event) => {
  console.log("RoktPlatformEvent received: ", event.detail);

  // Send to your backend to forward to Rokt
  fetch("/api/rokt-events", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(event.detail),
  });
});

// Render the experience with the payload from your backend
roktElement.renderExperiences(payload);

πŸ™‹ FAQDirect link to πŸ™‹ FAQ

My backend calls the Session API (v2). How do I render that response?Direct link to My backend calls the Session API (v2). How do I render that response?

The /v2/sessions/offers response is snake_case, while renderExperiences() expects the camelCase model. Convert it with the exported adaptSelectResponse helper:

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

// Your own backend call. This library does not make it for you.
const offersResponse = await fetchV2Offers();

const model = adaptSelectResponse(offersResponse);

document.querySelectorAll('rokt-layout-view').forEach((layoutView) => {
  layoutView.renderExperiences(model);
});

Platform events go the other way, through buildRecordEventsRequest. Both helpers are covered in the advanced guide.

What is the rokt-layout-view?Direct link to What is the rokt-layout-view?

The rokt-layout-view is a custom element that is used to render the Rokt Layouts on your website. It is a web component that can be added to your HTML view and used to render the experience payload.

What are the interfaces for the rokt-layout-view?Direct link to What are the interfaces for the rokt-layout-view?

The rokt-layout-view interface is defined in the @rokt/ux-helper-web package. You can find the interface here: RoktLayoutViewInterface

export interface RoktLayoutViewInterface extends HTMLElement {
  renderExperiences(data: ExperiencesResponseInterface): void;
  close(): void;
  send<T>(name: string, data?: T): Promise<void>;
}

How do I handle overlay experiences?Direct link to How do I handle overlay experiences?

To support overlay experiences that target the body selector, add the render-overlay attribute to your rokt-layout-view element. It's recommended to place the overlay element at the end of the <body> tag to ensure proper z-index stacking and avoid potential DOM conflicts.

How do I determine if I need embedded or overlay experiences?Direct link to How do I determine if I need embedded or overlay experiences?

Embedded ExperiencesDirect link to Embedded Experiences

Embedded experiences integrate directly within your page layout at specific points. Use these when:

  • You want the experience to appear within your page flow
  • You have a specific location where the content should be displayed
  • You want the experience to respect surrounding content layout
<rokt-layout-view id="rokt-placement"></rokt-layout-view>

Overlay ExperiencesDirect link to Overlay Experiences

Overlay experiences appear on top of your content, potentially covering parts of your page. Use these when:

  • You want the experience to appear as a modal dialog or popup
  • The content should grab the user's attention and focus
  • The experience needs to be visually separated from the main page content
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>

Your Rokt Account Manager can help determine which type best suits your needs based on your business goals and design requirements.

How can I detect if the experience has rendered successfully?Direct link to How can I detect if the experience has rendered successfully?

You can listen for the RoktUXEvent with the LayoutInteractive event type, which is triggered when a layout is successfully rendered and ready for interaction:

roktElement.addEventListener('RoktUXEvent', (event) => {
  if (event.detail.eventName === 'LayoutInteractive') {
    console.log('Experience is successfully rendered and interactive');
  }
});

What should I do if I need multiple placement locations?Direct link to What should I do if I need multiple placement locations?

You can add multiple rokt-layout-view elements with different IDs to target different placement locations on your page. Each element should have a unique ID that matches the target selector in your configured experiences.

How do I debug integration issues?Direct link to How do I debug integration issues?

Check your browser console for any warnings or errors from the Rokt UX Helper. You can also use the browser's element inspector to examine the rokt-layout-view elements and their shadow DOM content. For more detailed debugging, refer to the troubleshooting guide.

Is the Web UX Helper compatible with all browsers?Direct link to Is the Web UX Helper compatible with all browsers?

The Web UX Helper is compatible with all modern browsers that support Web Components (Chrome, Firefox, Safari, Edge). For older browsers, you may need to use polyfills.

What events can I send to the rokt-layout-view?Direct link to What events can I send to the rokt-layout-view?

You can send various events to communicate with the rendered layouts. A common example is the V2_UPDATE_CART_ITEM event, which allows you to inform layouts about cart changes:

await roktElement.send('V2_UPDATE_CART_ITEM', {
  cartItemId: "item-123",
  quantity: 2
});

This helps create dynamic experiences that react to user actions in your application. For more events, refer to the API reference.

How do I contribute to the project?Direct link to How do I contribute to the project?

As an open source project, we welcome contributions! Visit our GitHub repository to submit issues, create pull requests, or explore the codebase.

Are there any advanced guides for the Web UX Helper?Direct link to Are there any advanced guides for the Web UX Helper?

Yes, for more advanced usage, refer to the Web UX Helper Advanced Guide.

Was this article helpful?
Last updated Aug 19, 2026