Web UX Helper
Rokt UX Helperは、サーバー間環境で美しい顧客体験をレンダリングするのを助けるオープンソースプロジェクトです。GitHubでプロジェクトを見つけて貢献することができます。
概要概要 への直接リンク
Rokt UX Helperは、ウェブコンポーネント技術を活用して、あなたのウェブサイト上でRoktの体験をレンダリングするためのシンプルでメンテナブルなソリューションを提供します。rokt-layout-viewカスタム要素は、サーバーから受け取ったペイロードに基づいて体験をレンダリングします。
統合手順統合手順 への直接リンク
このドキュメントは、Rokt UX Helperをウェブプロジェクトに統合するプロセスを説明しており、サーバー間統合(S2S)と連携して、チェックアウト時に顧客に関連する体験を提供します。
📦 インストールガイド📦 インストールガイド への直接リンク
このライブラリはnpmパッケージとして利用可能です。インストールするには、以下のコマンドを使用してください:
npm install @rokt/ux-helper-web@stable
新機能をテストするには、@stable の代わりに @latest を使用してください:
npm install @rokt/ux-helper-web@latest
🔹 バージョンタグの説明🔹 バージョンタグの説明 への直接リンク
@stable: このタグは、ライブラリの最新のプロダクション対応バージョンを指します。安定性と信頼性が求められるアプリケーションに推奨されます。@latest: このタグは、まだ完全にテストされていない可能性のある新機能や改善を含む最新バージョンを指します。開発およびテスト目的でのみ使用し、公式に安定版としてマークされる前に最新の更新を取得します。
CDNの使用CDNの使用 への直接リンク
CDNを使用したい場合は、HTMLにライブラリを直接含めることができます:
<!-- Use the latest stable version -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
<!-- Or use the latest version with newest features -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@latest/dist/index.cjs"></script>
このパッケージは異なるモジュール形式も提供しています:
<!-- 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>
rokt-layout-viewを追加するrokt-layout-viewを追加する への直接リンク
Rokt UX Helperを使用開始するには、バンドルされたRokt UX Helperスクリプトを追加し、HTMLビューの関連部分にrokt-layout-viewを追加してJavaScriptを追加します。
<head>
<!-- Link to your Rokt UX Helper JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></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>
要素を登録しペイロードをレンダリングする要素を登録しペイロードをレンダリングする への直接リンク
rokt-layout-viewを追加したら、それを登録し、レンダリングするペイロードを渡す必要があります。
// 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()
オーバーレイ体験の処理オーバーレイ体験の処理 への直接リンク
bodyセレクタを対象とするオーバーレイ体験をサポートするには、render-overlay属性を追加します:
<body>
<!-- Your content -->
<rokt-layout-view id="overlay" render-overlay></rokt-layout-view>
<!-- Your content -->
<script src="./index.js"></script>
</body>
イベントハンドリングイベントハンドリング への直接リンク
Rokt UX Helperは、ユーザーのインタラクションを追跡し、Roktプラットフォームと通信するための2種類のイベントを提供します。
UXイベントUXイベント への直接リンク
UXイベントを使用して、ユーザーのインタラクションに関するリアルタイムのフィードバックを受け取ります:
roktElement.addEventListener('RoktUXEvent', (event) => {
// Use these events to tailor your user experience
console.log('RoktUXEvent received:', event.detail);
});
すべてのUXイベント
| イベント | 説明 |
|---|---|
| OfferEngagement | ユーザーがオファーに関与したときにトリガーされます |
| PositiveEngagement | ユーザーがオファーに積極的に関与したときにトリガーされます |
| LayoutInteractive | レイアウトがレンダリングされ、操作可能になったときにトリガーされます |
| LayoutClosed | ユーザーによってレイアウトが閉じられたときにトリガーされます |
| LayoutCompleted | オファーの進行が終了し、表示するオファーがなくなったときにトリガーされます |
| LayoutFailure | レイアウトの表示に失敗したときにトリガーされます |
プラットフォームイベントプラットフォームイベント への直接リンク
プラットフォームイベントは統合に不可欠であり、バックエンドを通じてRoktに送信する必要があります。これらのイベントは、イベントデータと統合の詳細を含む完全なJSONペイロードを返します:
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)
});
});
プラットフォームイベントペイロードの例
{
"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"
}
プラットフォームイベントの詳細については、APIリファレンスを参照してください。
レイアウトへのイベント送信レイアウトへのイベント送信 への直接リンク
send メソッドを使用して、レンダリングされたレイアウトにイベントを送信することもできます。これは、アプリケーション内のアクションに基づいてレイアウトと通信するのに役立ちます:
// Send a cart update event to all rendered layouts
await roktElement.send('V2_UPDATE_CART_ITEM', {
cartItemId: "item-123",
quantity: 2
});
この例では、レイアウトが応答できるカートアイテムの更新イベントを送信し、数量に基づいてプロモーションオファーを更新するなどの操作を行います。
まとめまとめ への直接リンク
rokt-layout-viewをプロジェクトに統合することは簡単で、ビューや実験を管理する柔軟な方法を提供します。このガイドに示された手順に従うことで、rokt-layout-viewをプロジェクトに追加し、Rokt UX Helperが提供する強力な機能を最大限に活用することができます。
完全な例完全な例 への直接リンク
HTMLHTML への直接リンク
<!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/dist/index.cjs"></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>
JavaScriptJavaScript への直接リンク
// 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);
📦 インストールガイド📦 インストールガイド への直接リンク
このライブラリはnpmパッケージとして利用可能です。インストールするには、以下のコマンドを使用してください:
npm install @rokt/ux-helper-web@stable
新機能をテストするには、@stable の代わりに @latest を使用してください:
npm install @rokt/ux-helper-web@latest
🔹 バージョンタグの説明🔹 バージョンタグの説明 への直接リンク
@stable: このタグは、ライブラリの最新のプロダクション対応バージョンを指します。安定性と信頼性が求められるアプリケーションに推奨されます。@latest: このタグは、まだ完全にテストされていない可能性のある新機能や改善を含む最新バージョンを指します。開発およびテスト目的でのみ使用し、公式に安定版としてマークされる前に最新の更新を取得します。
CDNの使用CDNの使用 への直接リンク
CDNを使用したい場合は、HTMLにライブラリを直接含めることができます:
<!-- Use the latest stable version -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
<!-- Or use the latest version with newest features -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@latest/dist/index.cjs"></script>
このパッケージは異なるモジュール形式も提供しています:
<!-- 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>
要素の登録とペイロードのレンダリング要素の登録とペイロードのレンダリング への直接リンク
ReactでRokt UX Helperを使用するには、rokt-layout-viewカスタム要素をレンダリングし、エクスペリエンスペイロードをrenderExperiencesメソッドを通じて渡す必要があります。
import { useRef, useEffect } from "react";
import { RoktLayoutViewInterface, ExperiencesResponseInterface } from "@rokt/ux-helper-web";
// Define the custom element for TypeScript
declare global {
namespace JSX {
interface IntrinsicElements {
"rokt-layout-view": React.DetailedHTMLProps<React.HTMLAttributes<RoktLayoutViewInterface>, RoktLayoutViewInterface>;
}
}
}
function RoktLayoutView() {
const roktElement = useRef<RoktLayoutViewInterface>(null);
// Get experience data from your backend
const experienceData: ExperiencesResponseInterface = /* Fetch from your server */;
// When component mounts and experienceData is available
useEffect(() => {
if (roktElement.current && experienceData) {
roktElement.current.renderExperiences(experienceData);
}
}, [experienceData]);
return (
<rokt-layout-view
ref={roktElement}
id="rokt-layout-placeholder"
></rokt-layout-view>
);
}
export default RoktLayoutView;
注意: カスタム要素は、
@rokt/ux-helper-webパッケージがインポートされると自動的に登録されます。特別な理由がない限り、registerCustomElements()を明示的に呼び出す必要はありません。
イベントの処理イベントの処理 への直接リンク
イベントハンドリングイベントハンドリング への直接リンク
Rokt UX Helperは、ユーザーのインタラクションを追跡し、Roktプラットフォームと通信するための2種類のイベントを提供します。
UXイベントUXイベント への直接リンク
UXイベントを使用して、ユーザーのインタラクションに関するリアルタイムのフィードバックを受け取ります:
roktElement.addEventListener('RoktUXEvent', (event) => {
// Use these events to tailor your user experience
console.log('RoktUXEvent received:', event.detail);
});
すべてのUXイベント
| イベント | 説明 |
|---|---|
| OfferEngagement | ユーザーがオファーに関与したときにトリガーされます |
| PositiveEngagement | ユーザーがオファーに積極的に関与したときにトリガーされます |
| LayoutInteractive | レイアウトがレンダリングされ、操作可能になったときにトリガーされます |
| LayoutClosed | ユーザーによってレイアウトが閉じられたときにトリガーされます |
| LayoutCompleted | オファーの進行が終了し、表示するオファーがなくなったときにトリガーされます |
| LayoutFailure | レイアウトの表示に失敗したときにトリガーされます |
プラットフォームイベントプラットフォームイベント への直接リンク
プラットフォームイベントは統合に不可欠であり、バックエンドを通じてRoktに送信する必要があります。これらのイベントは、イベントデータと統合の詳細を含む完全なJSONペイロードを返します:
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)
});
});
プラットフォームイベントペイロードの例
{
"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"
}
プラットフォームイベントの詳細については、APIリファレンスを参照してください。
レイアウトへのイベント送信レイアウトへのイベント送信 への直接リンク
send メソッドを使用して、レンダリングされたレイアウトにイベントを送信することもできます。これは、アプリケーション内のアクションに基づいてレイアウトと通信するのに役立ちます:
// Send a cart update event to all rendered layouts
await roktElement.send('V2_UPDATE_CART_ITEM', {
cartItemId: "item-123",
quantity: 2
});
この例では、レイアウトが応答できるカートアイテムの更新イベントを送信し、数量に基づいてプロモーションオファーを更新するなどの操作を行います。
オーバーレイエクスペリエンスの処理オーバーレイエクスペリエンスの処理 への直接リンク
bodyセレクタをターゲットにしたオーバーレイエクスペリエンスをサポートするには、render-overlay属性を追加します:
function RoktLayoutView() {
const overlayRef = useRef<RoktLayoutViewInterface>(null);
// Same event handling and experience rendering as above
// The same `rokt-layout-view` can handle your embedded and overlay placements
return (
<rokt-layout-view
ref={overlayRef}
id="rokt-layout-placeholder"
render-overlay
></rokt-layout-view>
);
}
完全な例完全な例 への直接リンク
Rokt UX Helperをレンダリングし、両方のイベントを処理するReactコンポーネントの完全な例を以下に示します:
import { useRef, useEffect, useState } from "react";
import {
RoktLayoutViewInterface,
ExperiencesResponseInterface,
} from "@rokt/ux-helper-web";
declare global {
namespace JSX {
interface IntrinsicElements {
"rokt-layout-view": React.DetailedHTMLProps<
React.HTMLAttributes<RoktLayoutViewInterface>,
RoktLayoutViewInterface
>;
}
}
}
function RoktLayoutView() {
const roktElement = useRef<RoktLayoutViewInterface>(null);
const [experienceData, setExperienceData] =
useState<ExperiencesResponseInterface | null>(null);
// Fetch experience data from your backend when component mounts
useEffect(() => {
const fetchExperienceData = async () => {
try {
const response = await fetch("/api/rokt-experiences");
const data = await response.json();
setExperienceData(data);
} catch (error) {
console.error("Failed to fetch experience data:", error);
}
};
fetchExperienceData();
}, []);
useEffect(() => {
const currentRoktElement = roktElement.current;
const handleRoktUXEvent = (event: Event) => {
const customEvent = event as CustomEvent;
console.log("RoktUXEvent received:", customEvent.detail);
};
const handleRoktPlatformEvent = (event: Event) => {
const customEvent = event as CustomEvent;
console.log("RoktPlatformEvent received:", customEvent.detail);
// Send to your backend to forward to Rokt
fetch("/api/rokt-events", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(customEvent.detail),
});
};
if (currentRoktElement) {
currentRoktElement.addEventListener("RoktUXEvent", handleRoktUXEvent);
currentRoktElement.addEventListener(
"RoktPlatformEvent",
handleRoktPlatformEvent
);
// Render experiences when data is available
if (experienceData) {
currentRoktElement.renderExperiences(experienceData);
}
}
return () => {
if (currentRoktElement) {
currentRoktElement.removeEventListener(
"RoktUXEvent",
handleRoktUXEvent
);
currentRoktElement.removeEventListener(
"RoktPlatformEvent",
handleRoktPlatformEvent
);
currentRoktElement.close(); // Clean up when component unmounts
}
};
}, [experienceData, roktElement]);
return (
<>
<rokt-layout-view
ref={roktElement}
id="rokt-layout-placeholder"
render-overlay
></rokt-layout-view>
</>
);
}
export default RoktLayoutView;
まとめまとめ への直接リンク
rokt-layout-viewをReactプロジェクトに統合することは簡単で、ビューと実験を管理する柔軟な方法を提供します。このガイドに記載された手順に従うことで、rokt-layout-viewをプロジェクトに追加し、Rokt UX Helperが提供する強力な機能を最大限に活用できます。
🙋 FAQ🙋 FAQ への直接リンク
rokt-layout-viewとは何ですか?rokt-layout-viewとは何ですか? への直接リンク
rokt-layout-viewは、あなたのウェブサイト上でRoktレイアウトをレンダリングするために使用されるカスタム要素です。これは、HTMLビューに追加して体験ペイロードをレンダリングするために使用できるウェブコンポーネントです。
rokt-layout-viewのインターフェースは何ですか?rokt-layout-viewのインターフェースは何ですか? への直接リンク
rokt-layout-viewインターフェースは、@rokt/ux-helper-webパッケージで定義されています。インターフェースはこちらで見つけることができます:RoktLayoutViewInterface
export interface RoktLayoutViewInterface extends HTMLElement {
renderExperiences(data: ExperiencesResponseInterface): void;
close(): void;
send<T>(name: string, data?: T): Promise<void>;
}
オーバーレイ体験をどのように処理しますか?オーバーレイ体験をどのように処理しますか? への直接リンク
ボディセレクタをターゲットにしたオーバーレイ体験をサポートするには、render-overlay属性をrokt-layout-view要素に追加します。オーバーレイ要素を<body>タグの最後に配置することをお勧めします。これにより、適切なz-indexスタッキングが確保され、潜在的なDOMの競合を避けることができます。
埋め込み体験とオーバーレイ体験のどちらが必要かをどのように判断しますか?埋め込み体験とオーバーレイ体験のどちらが必要かをどのように判断しますか? への直接リンク
埋め込み体験埋め込み体験 への直接リンク
埋め込み体験は、特定のポイントでページレイアウトに直接統合されます。以下の場合に使用します:
- ページフロー内に体験を表示したい
- コンテンツを表示する特定の場所がある
- 周囲のコンテンツレイアウトを尊重したい
<rokt-layout-view id="rokt-placement"></rokt-layout-view>
オーバーレイ体験オーバーレイ体験 への直接リンク
オーバーレイ体験は、コンテンツの上に表示され、ページの一部を覆う可能性があります。以下の場合に使用します:
- モーダルダイアログやポップアップとして体験を表示したい
- コンテンツがユーザーの注意と集中を引くべき
- 体験がメインページコンテンツから視覚的に分離される必要がある
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>
あなたのRoktアカウントマネージャーは、ビジネス目標とデザイン要件に基づいて、どのタイプが最適かを判断するのを手助けします。
体験が正常にレンダリングされたかどうかをどのように検出しますか?体験が正常にレンダリングされたかどうかをどのように検出しますか? への直接リンク
RoktUXEventをLayoutInteractiveイベントタイプでリッスンすることができます。これは、レイアウトが正常にレンダリングされ、インタラクションの準備が整ったときにトリガーされます:
roktElement.addEventListener('RoktUXEvent', (event) => {
if (event.detail.eventName === 'LayoutInteractive') {
console.log('Experience is successfully rendered and interactive');
}
});
複数の配置場所が必要な場合はどうすればよいですか?複数の配置場所が必要な場合はどうすればよいですか? への直接リンク
異なるIDを持つ複数のrokt-layout-view要素を追加して、ページ上の異なる配置場所をターゲットにすることができます。各要素には、設定された体験のターゲットセレクタに一致する一意のIDが必要です。
統合の問題をどのようにデバッグしますか?統合の問題をどのようにデバッグしますか? への直接リンク
Rokt UX Helperからの警告やエラーについて、ブラウザコンソールを確認してください。また、ブラウザの要素インスペクタを使用して、rokt-layout-view要素とそのシャドウDOMコンテンツを調べることもできます。より詳細なデバッグについては、トラブルシューティングガイドを参照してください。
Web UX Helperはすべてのブラウザと互換性がありますか?Web UX Helperはすべてのブラウザと互換性がありますか? への直接リンク
Web UX Helperは、Web Componentsをサポートするすべての最新のブラウザ(Chrome、Firefox、Safari、Edge)と互換性があります。古いブラウザの場合、ポリフィルを使用する必要があるかもしれません。
rokt-layout-view にどのようなイベントを送信できますか?rokt-layout-view にどのようなイベントを送信できますか? への直接リンク
レンダリングされたレイアウトと通信するために、さまざまなイベントを送信できます。一般的な例としては、カートの変更をレイアウトに通知するための V2_UPDATE_CART_ITEM イベントがあります。
await roktElement.send('V2_UPDATE_CART_ITEM', {
cartItemId: "item-123",
quantity: 2
});
これにより、アプリケーション内でユーザーのアクションに反応する動的な体験を作成できます。その他のイベントについては、API リファレンスを参照してください。
プロジェクトに貢献するにはどうすればよいですか?プロジェクトに貢献するにはどうすればよいですか? への直接リンク
オープンソースプロジェクトとして、貢献を歓迎します!GitHub リポジトリを訪れて、問題を提出したり、プルリクエストを作成したり、コードベースを探索したりしてください。
Web UX Helper のための高度なガイドはありますか?Web UX Helper のための高度なガイドはありますか? への直接リンク
はい、より高度な使用法については、Web UX Helper Advanced Guideを参照してください。