customware-support-widget

Customware サポートウィジェット

Customware React Router クライアント専用 SPA テンプレートに、Customware サポートチャットのエントリーポイントが必要な場合に、このスキルを使用します。

このウィジェットは、サードパーティ製のブラウザーカスタム要素です。このテンプレートでは、HTML ドキュメントの構造を定義する root.tsx または同等の React Router ルートファイル／コンポーネントでウィジェットのスクリプトを読み込み、サポートを表示するルートまたはレイアウトでのみ <customware-chat> をレンダリングします。ウィジェットが Shadow DOM の UI、チャットのランタイム、サービス呼び出し、ツールバッジ、音声入力、ページ操作を管理します。

React のコード例、スクリプトの読み込みパターン、JSX の型定義、吹き出し／全画面モードの例、メタデータ、スタイルオプションについては、references/component-usage.md を参照してください。

提供機能

• <customware-chat> によるサポートチャット UI。
• フローティングランチャー／ダイアログ用の chat-bubble モード。
• サイドバー、レール、ドロワー、分割ペインのチャット領域用の full モード。
• meta DOM プロパティによる任意の訪問者メタデータ。
• styleOptions または style-options による任意のサイズ調整／カスタマイズ。
• ツールを利用したサポート機能：ドメイン／コンテキストの読み取り、タスクの一覧表示と作成、表示中のページの操作。
• フォームへの入力、オプションの選択、ボタンのクリック、値の置き換え、表示中の UI の送信といったユーザーの依頼に対するページ操作。

正確な React 実装パターンについては、references/component-usage.md を参照してください。

使用しない場合

• サーバーサイドレンダリングの作業には、このスキルを使用しないでください。対象のテンプレートはクライアント専用の React Router SPA モードです。
• カスタムチャット UI の構築には、このスキルを使用しないでください。
• ウィジェットを iframe で表示するために、このスキルを使用しないでください。
• サポートチャットのエンドポイントを直接呼び出すために、このスキルを使用しないでください。
• 明示的に依頼されない限り、テンプレート以外の React アプリや React 以外のアプリには、このスキルを使用しないでください。
• orgId または projectId を特定できない場合は、このスキルを使用しないでください。必要な Customware の組織／プロジェクト ID が不足していることを明確に示して、タスクを失敗として扱ってください。

必ず守る事項

• 必ず実際のカスタム要素 <customware-chat> をレンダリングしてください。
• 必ず org-id と project-id の両方を渡してください。
• いずれかの ID が利用できない場合は、プレースホルダーをレンダリングしたり追加の質問をしたりせず、ID が不足していることを明確に示してタスクを失敗として扱ってください。
• 既存のアプリレベルのローダーが対応していない限り、root.tsx またはテンプレートの同等の React Router ルートドキュメントシェルから、https://app.customware.ai/support-widget/customware-chat.js を一度だけ読み込んでください。
• タスク ID、ドメイン ID、ユーザー ID、API トークン、セッショントークン、認証 Cookie、シークレットをコンポーネントに渡さないでください。
• meta は、任意の訪問者 ID 情報である email および／または name のみを指定するために使用してください。
• サイズ調整には、ラッパーの CSS、styleOptions、または style-options を使用してください。ウィジェットの設定にネイティブ DOM の style プロパティを使用しないでください。
• ツール呼び出しは、ボタンではなく簡潔なステータスバッジです。
• ページ操作はウィジェット内で処理されます。その周囲に独自のクリック／入力／ページ制御ハンドラーを追加しないでください。
• ホストアプリにページ操作のプロンプトや値をハードコードしないでください。ユーザーがウィジェットに依頼内容を入力する必要があります。

実装ワークフロー

1. references/component-usage.md を読みます。
2. React アプリに orgId と projectId があることを確認します。
3. モードを選択します。
   • chat-bubble は、フローティングのサポートランチャー／ダイアログに使用します。
   • full は、埋め込み型のレール、ドロワー、分割ペイン、固定チャット領域に使用します。
4. まだ追加されていない場合は、HTML ドキュメントの <head> を定義する root.tsx または React Router のルートファイル／コンポーネントにスクリプトタグを追加します。
5. テンプレートが <customware-chat> を認識しない場合は、.d.ts ファイルに JSX カスタム要素の型定義を追加します。
6. サポートが必要な特定のルートまたはレイアウトで、org-id と project-id を指定して <customware-chat> をレンダリングします。
7. 必要に応じて、型付けされた React ref を通じて任意の meta と styleOptions を設定します。
8. full モードでは、ラッパー／コンポーネントに具体的な高さを設定し、内部スクロールがウィジェットに属するようにします。
9. bubble モードでは、ラッパーがクリップされず、適切な z-index が設定されていることを確認します。
10. 生成された React コードの構文を検証し、利用可能な場合は npm run check も実行します。

各モードの完全なコード例については、references/component-usage.md を参照してください。

MITB エージェントの制約

• Playwright、スクリーンショット、ブラウザー DevTools、またはビジュアルテストを利用できると想定しないでください。
• ウィジェットをビジュアルテストしたと主張しないでください。
• 生成されたアプリ内に、ユーザー向けのステータスレポートを書かないでください。
• コードの確認、TypeScript／コンパイルチェック、および生成された React Router／Vite コードが references/component-usage.md の例に従っていることによって検証してください。
• 生成時に実行時 ID を取得できない場合は、ID が不足している理由を明確にしてタスクを失敗させてください。ID が実行時に非同期で読み込まれる想定の場合は、orgId && projectId が成立するまでコンポーネントを表示せず、プレースホルダーでレンダリングされないようにしてください。

してはいけないこと

• iframe による統合を作成しないでください。
• React でウィジェットの内部を再構築したり、スタイルを変更したりしないでください。
• Shadow DOM にアクセスしたり、内部のクラス名に依存したりしないでください。
• ツール呼び出しをクリック可能な UI コントロールとして公開しないでください。
• ホストアプリからサポートチャット API またはページ操作 API を直接呼び出さないでください。
• フォールバックの埋め込みモードを追加しないでください。
• シークレット、アクセストークン、プライベートなペイロード、認証／セッションデータをウィジェットの属性に保存しないでください。
• 任意のユーザー／プロフィールオブジェクトを meta に渡さないでください。渡せるのは任意の email と name のみです。
• 想定上の内部メッセージリストだけに固定の高さを設定しないでください。full モードのホスト領域全体のサイズを指定してください。
• 意図的な動作でない限り、クリップまたは変形されたコンテナ内に bubble モードを配置しないでください。