Rokt UX Helper - トラブルシューティング

このガイドは、Rokt UX Helper ライブラリを実装する際に発生し得る一般的な問題に対処し、解決策を提供します。

一般的な問題

エクスペリエンスがレンダリングされない

エクスペリエンスがページに表示されない場合:

1. 要素セレクタが一致しない: エクスペリエンスペイロード内の targetElementSelector が rokt-layout-view 要素のIDまたはクラスと一致していることを確認してください。

   // Check the plugin configuration in your response
   console.log(experienceData.plugins.map(plugin => plugin.plugin.targetElementSelector));
   
   // Make sure these selectors match your elements
   console.log(document.querySelector('rokt-layout-view').id); // Should match one of the selectors

2. 空または無効なペイロード: エクスペリエンスペイロードが有効であり、プラグインを含んでいることを確認してください。

   // Validate the payload structure
   if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
     console.error('No valid experience data available');
   }

3. カスタム要素が登録されていない: カスタム要素が正しく登録されていることを確認してください。

   // Check if the element is registered
   console.log(!!customElements.get('rokt-layout-view'));
   
   // Register manually if needed
   import { registerCustomElements } from '@rokt/ux-helper-web';
   registerCustomElements();

4. 複数のオーバーレイ要素: rokt-layout-view に render-overlay 属性がある最初の要素のみがオーバーレイエクスペリエンスを受け取ります。複数のオーバーレイ要素がある場合は実装を確認してください。

CDN の問題

CDN からライブラリを読み込む際に問題が発生している場合:

1. CDN パスが間違っている: ライブラリの正しいパスは以下の通りです:

   <!-- 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>

2. バージョンの問題: バージョンに問題がある場合は、正確なバージョンを指定してみてください:

   <script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web@0.1.5/dist/index.cjs"></script>

3. CORS の問題: CORS エラーが発生している場合は、サーバーが CDN ドメインを許可するように設定されていることを確認してください。

4. ネットワークの問題: ブラウザのネットワークタブを確認して、CDN ファイルが正しく読み込まれているか確認してください。

コンソールエラー

"Failed to construct 'CustomElement'"

カスタム要素の構築に関連するエラーが表示される場合:

Uncaught DOMException: Failed to construct 'CustomElement': The result must not have attributes

これは通常、古いブラウザやポリフィルを使用している場合に発生します。最新バージョンのライブラリを使用し、古いブラウザ用にポリフィルを追加することを検討してください:

<script src="https://unpkg.com/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@rokt/ux-helper-web/dist/index.cjs"></script>

"Cannot read property 'renderExperiences' of null"

このエラーは、DOM に存在しない要素に対してメソッドを呼び出そうとしたときに発生します:

Uncaught TypeError: Cannot read property 'renderExperiences' of null

要素が存在することを確認してから使用してください:

const roktElement = document.getElementById('rokt-layout-placeholder');
if (roktElement) {
  roktElement.renderExperiences(experienceData);
} else {
  console.error('Element #rokt-layout-placeholder not found in DOM');
}

レイアウトの問題

"Warning: Multiple overlay plugins detected"

複数のオーバーレイプラグインに関する警告が表示される場合:

WARNING: Multiple overlay plugins detected. Only rendering the first one.

これは、複数のプラグインが body セレクタをターゲットにしていることを意味します。最初のもののみがレンダリングされます。複数のオーバーレイをレンダリングする必要がある場合は、異なる配置戦略を検討してください。

DOMに存在するが表示されないエクスペリエンス

エクスペリエンスがDOMにレンダリングされているが表示されない場合：

1. CSSの問題を確認する: 要素を検査し、CSSがコンテンツを隠していないことを確認します：

   /* Add this temporarily to debug */
   rokt-layout-view {
     border: 1px solid red;
     min-height: 50px;
   }

イベント処理の問題

イベントが発火しない

イベントを受信していない場合：

1. イベントリスナーが遅れてアタッチされている: イベントリスナーがエクスペリエンスをレンダリングする前にアタッチされていることを確認します：

   // Correct order
   roktElement.addEventListener('RoktUXEvent', handleUXEvent);
   roktElement.addEventListener('RoktPlatformEvent', handlePlatformEvent);
   roktElement.renderExperiences(experienceData);

2. イベントバブリングの問題: 親要素でイベントが伝播を止められていないか確認します：

   // Use capturing phase to intercept events earlier
   document.addEventListener('RoktUXEvent', handleUXEvent, true);
   document.addEventListener('RoktPlatformEvent', handlePlatformEvent, true);

プラットフォームイベントが処理されない

Roktプラットフォームのイベントが正しく処理されない場合：

1. イベントペイロードが不正: 完全なイベントペイロードを転送していることを確認します：

   roktElement.addEventListener('RoktPlatformEvent', (event) => {
     // Send the ENTIRE detail object, don't modify it
     sendToBackend(event.detail);
   });

2. ネットワークの問題: イベントが正しいエンドポイントに適切な認証で送信されていることを確認します。

React特有の問題

TypeScriptエラー

ReactでTypeScriptエラーが発生する場合：

1. カスタム要素の宣言が不足している: カスタム要素を宣言していることを確認します：

   declare global {
     namespace JSX {
       interface IntrinsicElements {
         "rokt-layout-view": React.DetailedHTMLProps<
           React.HTMLAttributes<HTMLElement> & {
             ref?: React.RefObject<HTMLElement>;
           },
           HTMLElement
         >;
       }
     }
   }

2. 型キャストの問題: イベントに対して適切な型キャストを使用します：

   const handleUXEvent = (event: Event) => {
     // Cast to CustomEvent to access detail property
     const customEvent = event as CustomEvent;
     console.log(customEvent.detail);
   };

Refの問題

Reactのrefに関する問題がある場合：

// Use correct ref type and access pattern
const roktRef = useRef<HTMLElement & {
  renderExperiences: (data: any) => void;
  close: () => void;
}>(null);

// Later in your code
if (roktRef.current) {
  roktRef.current.renderExperiences(data);
}

ヘルプを得る

これらの解決策を試した後も問題が続く場合は、以下を行うことができます：

1. GitHubリポジトリでオープンイシューを確認するか、新しいイシューを作成する
2. 完全なAPIドキュメントを確認する
3. 追加のサポートが必要な場合はRoktサポートに連絡する