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

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

一般的な問題

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

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

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

   // レスポンス内のプラグイン設定を確認
   console.log(experienceData.plugins.map(plugin => plugin.plugin.targetElementSelector));
   
   // これらのセレクタが要素と一致していることを確認
   console.log(document.querySelector('rokt-layout-view').id); // セレクタの1つと一致する必要があります

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

   // ペイロードの構造を検証
   if (!experienceData || !experienceData.plugins || experienceData.plugins.length === 0) {
     console.error('有効なエクスペリエンスデータが利用できません');
   }

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

   // 要素が登録されているか確認
   console.log(!!customElements.get('rokt-layout-view'));
   
   // 必要に応じて手動で登録
   import { registerCustomElements } from '@rokt/ux-helper-web';
   registerCustomElements();

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

CDNの問題

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

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

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

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

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

<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. Only rendering the first one.

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

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

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

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

   /* デバッグ用に一時的に追加 */
   rokt-layout-view {
     border: 1px solid red;
     min-height: 50px;
   }

イベント処理の問題

イベントが発火しない

イベントを受け取っていない場合:

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

   // 正しい順序
   roktElement.addEventListener('RoktUXEvent', handleUXEvent);
   roktElement.addEventListener('RoktPlatformEvent', handlePlatformEvent);
   roktElement.renderExperiences(experienceData);

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

   // キャプチャフェーズを使用してイベントを早期にインターセプト
   document.addEventListener('RoktUXEvent', handleUXEvent, true);
   document.addEventListener('RoktPlatformEvent', handlePlatformEvent, true);

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

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

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

   roktElement.addEventListener('RoktPlatformEvent', (event) => {
     // 詳細オブジェクト全体を送信し、変更しないでください
     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) => {
     // detailプロパティにアクセスするためにCustomEventにキャスト
     const customEvent = event as CustomEvent;
     console.log(customEvent.detail);
   };

Refの問題

Reactのrefに関する問題が発生している場合:

// 正しいrefの型とアクセスパターンを使用
const roktRef = useRef<HTMLElement & {
  renderExperiences: (data: any) => void;
  close: () => void;
}>(null);

// コード内の後の部分で
if (roktRef.current) {
  roktRef.current.renderExperiences(data);
}

ヘルプの取得

これらの解決策を試した後も問題が解決しない場合は、以下の方法を試してください:

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