メインコンテンツまでスキップ

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にライブラリを直接含めることができます:

<!-- 最新の安定版を使用 -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>

<!-- または最新の機能を持つ最新バージョンを使用 -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@latest/dist/index.cjs"></script>

このパッケージは異なるモジュール形式も提供しています:

<!-- CommonJS形式 (ブラウザでの直接使用向け) -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>

<!-- ESM形式 (モダンアプリケーション向け) -->
<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>
<!-- Rokt UX Helper JavaScript へのリンク -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
</head>

<body>
<!-- あなたのコンテンツ -->

<!-- 以下の JavaScript で使用される ID に注意してください -->
<rokt-layout-view id="rokt-layout-placeholder"></rokt-layout-view>

<!-- あなたのコンテンツ -->

<!-- 以下に説明されているイベントを処理する JavaScript -->
<script src="./index.js"></script>
</body>

要素を登録し、ペイロードをレンダリングする要素を登録し、ペイロードをレンダリングする への直接リンク

rokt-layout-view を追加したら、それを登録し、レンダリングするペイロードを渡す必要があります。

index.js
// この関数は、バックエンドサービスなどからエクスペリエンスデータをロードします
const payload = fetchExperienceData();

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

// 注意: カスタム要素はライブラリがロードされると自動的に登録されるため、
// registerCustomElements() を明示的に呼び出す必要はありません

オーバーレイエクスペリエンスの処理オーバーレイエクスペリエンスの処理 への直接リンク

bodyセレクタをターゲットとするオーバーレイエクスペリエンスをサポートするには、render-overlay属性を追加します:

<body>
<!-- あなたのコンテンツ -->

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

<!-- あなたのコンテンツ -->
<script src="./index.js"></script>
</body>

イベント処理イベント処理 への直接リンク

Rokt UX Helperは、ユーザーのインタラクションを追跡し、Roktプラットフォームと通信するための2種類のイベントを提供します。

UXイベントUXイベント への直接リンク

UXイベントを使用して、ユーザーのインタラクションに関するリアルタイムのフィードバックを受け取ります:

roktElement.addEventListener('RoktUXEvent', (event) => {
// これらのイベントを使用してユーザー体験をカスタマイズします
console.log('RoktUXEvent received:', event.detail);
});
すべてのUXイベント
イベント説明
OfferEngagementユーザーがオファーに関与したときにトリガーされます
PositiveEngagementユーザーがオファーに積極的に関与したときにトリガーされます
LayoutInteractiveレイアウトがレンダリングされ、対話可能になったときにトリガーされます
LayoutClosedユーザーによってレイアウトが閉じられたときにトリガーされます
LayoutCompletedオファーの進行が終了し、表示するオファーがなくなったときにトリガーされます
LayoutFailureレイアウトの表示に失敗したときにトリガーされます

プラットフォームイベントプラットフォームイベント への直接リンク

プラットフォームイベントは統合に不可欠であり、バックエンドを介してRoktに送信する必要があります。これらのイベントは、イベントデータと統合の詳細を含む完全なJSONペイロードを返します:

roktElement.addEventListener('RoktPlatformEvent', (event) => {
// このペイロードをバックエンドを介してRoktに転送します
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 メソッドを使用して、レンダリングされたレイアウトにイベントを送信することもできます。これは、アプリケーション内のアクションに基づいてレイアウトと通信するのに便利です:

// すべてのレンダリングされたレイアウトにカート更新イベントを送信
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" />

<!-- CDNからRokt UX Helperを読み込む -->
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>
</head>
<body>
<h1>Rokt UX Helper デモ</h1>

<!-- 以下のJavaScriptで使用されるIDに注意 -->
<!-- 単一の`rokt-layout-view`要素を使用して、埋め込みレイアウトとオーバーレイレイアウトを処理することが可能です -->
<rokt-layout-view
id="rokt-layout-placeholder"
render-overlay
></rokt-layout-view>

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

JavaScriptJavaScript への直接リンク

index.js
// この関数はバックエンドサービスからエクスペリエンスデータをロードします
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);

// バックエンドに送信してRoktに転送
fetch("/api/rokt-events", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(event.detail),
});
});

// バックエンドからのペイロードでエクスペリエンスをレンダリング
roktElement.renderExperiences(payload);

🙋 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>;
}

オーバーレイエクスペリエンスをどのように処理しますか?オーバーレイエクスペリエンスをどのように処理しますか? への直接リンク

bodyセレクタをターゲットとするオーバーレイエクスペリエンスをサポートするには、rokt-layout-view要素にrender-overlay属性を追加します。適切なz-indexのスタッキングを確保し、潜在的なDOMの競合を避けるために、オーバーレイ要素を<body>タグの最後に配置することをお勧めします。

埋め込み型とオーバーレイ型のエクスペリエンスのどちらが必要かを判断するには?埋め込み型とオーバーレイ型のエクスペリエンスのどちらが必要かを判断するには? への直接リンク

埋め込み型エクスペリエンス埋め込み型エクスペリエンス への直接リンク

埋め込み型エクスペリエンスは、特定のポイントでページレイアウトに直接統合されます。以下の場合に使用します:

  • エクスペリエンスをページフロー内に表示したい場合
  • コンテンツを表示する特定の場所がある場合
  • 周囲のコンテンツレイアウトを尊重したい場合
<rokt-layout-view id="rokt-placement"></rokt-layout-view>

オーバーレイ型エクスペリエンスオーバーレイ型エクスペリエンス への直接リンク

オーバーレイ型エクスペリエンスは、コンテンツの上に表示され、ページの一部を覆う可能性があります。以下の場合に使用します:

  • エクスペリエンスをモーダルダイアログやポップアップとして表示したい場合
  • コンテンツがユーザーの注意とフォーカスを引く必要がある場合
  • エクスペリエンスをメインページコンテンツから視覚的に分離する必要がある場合
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>

Roktのアカウントマネージャーが、ビジネス目標やデザイン要件に基づいて、どのタイプが最適かを判断するお手伝いをします。

エクスペリエンスが正常にレンダリングされたかどうかを検出するにはどうすればよいですか?エクスペリエンスが正常にレンダリングされたかどうかを検出するにはどうすればよいですか? への直接リンク

RoktUXEventLayoutInteractive イベントタイプをリッスンすることで、レイアウトが正常にレンダリングされ、インタラクション可能になったときにトリガーされます:

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を参照してください。

この記事は役に立ちましたか?
Last updated Oct 29, 2025