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.

📦 Installation

Install the library using npm:

# Current stable release, tagged @latest (recommended for production)
npm install @rokt/ux-helper-web

There is no @stable tag. Installing without a tag resolves @latest, which is the stable release.

Install pre-releases by their exact version rather than by tag, because @next only moves when a pre-release is cut and can trail @latest by several major versions:

# Check what is published, then pin the pre-release you want
npm view @rokt/ux-helper-web dist-tags versions
npm install @rokt/ux-helper-web@<version>

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.

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:

| Peer | Range | | -------------------------------------------------------- | ---------- | | 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+ installs 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.

CDN Usage

Load the IIFE bundle, which inlines everything above — including React — and so has no peer requirements at all. It exposes a RoktUXHelper global and registers the custom elements on load:

<!-- Use the stable version for production -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/build/rokt-ux-helper-web.js"></script>

dist/index.cjs is not usable from a <script> tag. It is the CommonJS build for bundlers and starts with require("react/jsx-runtime"), which a browser cannot resolve.

🚀 Getting Started

This library is a renderer, not a network client. Your backend makes the API calls and hands the response to a <rokt-layout-view> element, which paints the layout and emits DOM events for you to forward back.

Pick the guide that matches the API you call:

• docs/GETTING_STARTED.md — V2 sessions API (/v2/sessions/offers, /v2/sessions/events). Start here for new integrations.
• docs/GETTING_STARTED_V1.md — V1 Partner Experiences API (/experiences, /events). Still fully supported.

One package serves both. Migrating from V1 to V2 changes your fetch and forward code only, not the package version or your DOM markup.

V2 helpers

Two exports cover the shape differences at the API boundaries:

| Export | Purpose | | --------------------------------------- | ------------------------------------------------------------------------ | | adaptSelectResponse(response) | Converts a snake_case /v2/sessions/offers response into the render model | | buildRecordEventsRequest(detail, opts) | Converts a RoktPlatformEvent payload into a /v2/sessions/events body |

🔔 Events

For detailed event handling documentation, refer to docs/EVENTS.md.

Main Event Types

• RoktUXEvent - User interaction events you can use to customize your UX
• RoktPlatformEvent - System events that should be forwarded to Rokt

🔧 Utils

For detailed documentation on utility functions, refer to docs/UTILS.md.

📂 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.

📖 Additional Resources

• 🛠 API Reference - Events
• 🌟 API Reference - Experiences
• 📝 Full Documentation

🙋 FAQ

Where can I find integration guides?

Start with docs/GETTING_STARTED.md for V2, or docs/GETTING_STARTED_V1.md if you call /experiences. The hosted version is the Web integration guide.

Do I have to migrate from V1 to V2?

No. Both APIs are supported by the current version and V1 is not deprecated in this library. When you do migrate, only your fetch and forward code changes.

Nothing renders and there is no error. What now?

Most often the response's target_element_selector does not match your element. A bare token such as checkout-slot will not match id="checkout-slot", since the selector must be #checkout-slot. See debugging a blank render.

Icons render as words like "Close" instead of symbols. Why?

Icons are ligatures in a font Rokt hosts, so when that font is blocked the browser falls back to showing the icon's name as text. Allow https://apps.rokt.com in your font-src CSP directive. See Content Security Policy.

How do I determine if I need embedded or overlay experiences?

Embedded experiences integrate within your page structure, while overlay experiences appear on top of your content. Review your design requirements or consult with your Rokt Account Manager to determine which type best meets your needs.

How do I report issues?

Open an issue on GitHub Issues.

What browser versions are supported?

The library is compatible with modern browsers including Chrome, Firefox, Safari, and Edge. For older browser support, consider adding web component polyfills.

👥 Resident Experts

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

📝 License

Licensed under Rokt License.