Rokt UX Helper - 上級使用法

このガイドでは、Rokt UX Helper ライブラリの上級使用シナリオと機能について説明します。

複数プレースメントのサポート

Rokt UX Helper は、単一ページでの複数のプレースメントをサポートしています。各プレースメントには、固有の ID を持つ rokt-layout-view 要素が必要です:

<!-- プライマリプレースメント -->
<rokt-layout-view id="rokt-primary"></rokt-layout-view>

<!-- セカンダリプレースメント -->
<rokt-layout-view id="rokt-secondary"></rokt-layout-view>

<!-- オーバーレイプレースメント -->
<rokt-layout-view id="rokt-overlay" render-overlay></rokt-layout-view>

エクスペリエンスをレンダリングする際、各プレースメントはそのセレクタに一致するプラグインのみを表示します:

// 複数のプラグインを含むエクスペリエンスデータを取得
const experienceData = await fetchExperienceData();

// すべてのプレースメント要素にエクスペリエンスをレンダリング
document.querySelectorAll('rokt-layout-view').forEach(element => {
  element.renderExperiences(experienceData);
});

要素ターゲティング

エクスペリエンスペイロード内のプラグインは、プラグイン設定の targetElementSelector プロパティに基づいて適切な rokt-layout-view 要素にマッチングされます。マッチングルールは以下の通りです：

1. IDセレクタ: targetElementSelector: "#rokt-primary" を持つプラグインは、id="rokt-primary" を持つ要素をターゲットにします。
2. クラスセレクタ: targetElementSelector: ".placement-class" を持つプラグインは、class="placement-class" を持つ要素をターゲットにします。
3. ボディセレクタ: targetElementSelector: "body" を持つプラグインは、render-overlay 属性を持つ要素をターゲットにします。

イベント通信

レイアウトへのイベント送信

send メソッドを使用して、レンダリングされたレイアウトにイベントを送信することもできます。これは、アプリケーション内のアクションに基づいてレイアウトと通信するのに便利です：

// すべてのレンダリングされたレイアウトにカート更新イベントを送信
await roktElement.send('V2_UPDATE_CART_ITEM', {
    cartItemId: "item-123",
    quantity: 2
});

これは、ユーザーの操作や外部データの変更に基づいてレンダリングされたエクスペリエンスを動的に更新するのに役立ちます。

すべてのプレースメントからのイベントの処理

イベント処理を中央集権化するために、ドキュメントレベルでイベントをリッスンすることができます:

document.addEventListener('RoktUXEvent', (event) => {
  const { pluginId, eventName, data } = event.detail;
  console.log(`プラグイン ${pluginId} からのUXイベント:`, eventName, data);
});

document.addEventListener('RoktPlatformEvent', (event) => {
  // すべてのプラットフォームイベントをバックエンドに転送する
  fetch('/api/rokt-events', {
    method: 'POST',
    body: JSON.stringify(event.detail)
  });
});

クリーンアップとエラーハンドリング

適切なクリーンアップ

rokt-layout-view を含むコンポーネントが削除されるときは、適切なクリーンアップを行ってください:

// バニラJSの場合
function cleanup() {
  const roktElement = document.getElementById('rokt-placement');
  if (roktElement) {
    roktElement.close();
  }
}

// Reactの場合
useEffect(() => {
  return () => {
    if (roktRef.current) {
      roktRef.current.close();
    }
  };
}, []);

エラーハンドリング

Rokt UX Helperを使用する際に適切なエラーハンドリングを実装します:

try {
  const experienceData = await fetchExperienceData();
  if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
    console.warn('No experiences to render');
    return;
  }

  roktElement.renderExperiences(experienceData);
} catch (error) {
  console.error('Failed to render Rokt experiences:', error);
  // 必要に応じてフォールバック動作を実装
}

// レイアウトの失敗を監視
roktElement.addEventListener('RoktUXEvent', (event) => {
  if (event.detail.eventName === 'LayoutFailure') {
    console.error('Layout failed to render:', event.detail);
    // フォールバック動作を実装
  }
});

パフォーマンスの考慮事項

Rokt UX Helperを使用する際の最適なパフォーマンスのために:

1. 遅延読み込み (Lazy Loading): Rokt UX Helperライブラリを遅延読み込みすることを検討します。特に、エクスペリエンスがすぐに表示されない場合:

// 必要なときにのみライブラリを読み込む
function loadRoktUXHelper() {
  return import('@rokt/ux-helper-web').then(() => {
    console.log('Rokt UX Helper loaded');
    // エクスペリエンスを初期化してレンダリング
  });
}

// 可視性に基づく読み込みのためにIntersection Observerを使用
const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting) {
    loadRoktUXHelper();
    observer.disconnect();
  }
}, { threshold: 0.1 });

observer.observe(document.getElementById('rokt-container'));