Rokt UX Helper - 高度な使用法

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

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

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

<!-- Primary placement -->
<rokt-layout-view id="rokt-primary"></rokt-layout-view>

<!-- Secondary placement -->
<rokt-layout-view id="rokt-secondary"></rokt-layout-view>

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

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

// Get the experience data that contains multiple plugins
const experienceData = await fetchExperienceData();

// Render experiences to all placement elements
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メソッドを使用して、レンダリングされたレイアウトにイベントを送信することもできます。これは、アプリケーション内のアクションに基づいてレイアウトと通信するのに便利です:

// Send a cart update event to all rendered layouts
await roktElement.send('V2_UPDATE_CART_ITEM', {
    cartItemId: "item-123",
    quantity: 2
});

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

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

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

document.addEventListener('RoktUXEvent', (event) => {
  const { pluginId, eventName, data } = event.detail;
  console.log(`UX Event from plugin ${pluginId}:`, eventName, data);
});

document.addEventListener('RoktPlatformEvent', (event) => {
  // Forward all platform events to your backend
  fetch('/api/rokt-events', {
    method: 'POST',
    body: JSON.stringify(event.detail)
  });
});

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

適切なクリーンアップ

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

// In vanilla JS
function cleanup() {
  const roktElement = document.getElementById('rokt-placement');
  if (roktElement) {
    roktElement.close();
  }
}

// In 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);
  // Implement fallback behavior if needed
}

// Listen for layout failures
roktElement.addEventListener('RoktUXEvent', (event) => {
  if (event.detail.eventName === 'LayoutFailure') {
    console.error('Layout failed to render:', event.detail);
    // Implement fallback behavior
  }
});

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

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

1. 遅延読み込み: 特にエクスペリエンスがすぐに表示されない場合は、Rokt UX Helperライブラリの遅延読み込みを検討してください:

// Load the library only when needed
function loadRoktUXHelper() {
  return import('@rokt/ux-helper-web').then(() => {
    console.log('Rokt UX Helper loaded');
    // Initialize and render experiences
  });
}

// Use with Intersection Observer for visibility-based loading
const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting) {
    loadRoktUXHelper();
    observer.disconnect();
  }
}, { threshold: 0.1 });

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