トラブルシューティングとチェックリスト
reactive.chatの埋め込みでよくある問題：ボタンや接続がない、オリジンが拒否される、本人確認できない、Webhookや顧客データが届かない場合の原因、確認方法、公開前のチェックリスト。
ツール
- 開発者ツール → Network：
loader.js、core.<hash>.js、WebSocket接続（「Messages」または「Frames」タブにinit、init_ok、errorを表示）、またはHTTPフォールバックのリクエスト（h/auf、…/sse、…/tx）を確認します。 - 診断を有効にする： ローダータグに
data-rc-debug="true"を指定するか、コンソールでlocalStorage.setItem('rc_debug','1')を実行してから、再読み込みします。 - Console：
ReactiveChat('getSession')、ReactiveChat('getEndpoint')、ReactiveChat('isOpen')、ReactiveChat.version。
チャットボタンが表示されない
- サイトキーがない、または無効。 ローダーは何も表示せずに中止します。実行されたタグの
data-rc-site-key（A–Z a–z 0–9 _ -の8～64文字）を確認してください。タグマネージャーやフレームワークのヘルパーが属性を落とす場合があります。 - scriptタグに
type="module"があると、ローダーは自分のタグを見つけられません。通常のスクリプトとして埋め込んでください。 data-rc-hide-launcher="true"があるか、アカウントで「独自リンク経由のみ（チャットアイコンなし）」が設定されています。- スニペットにブランドの色がない： 有効な
data-rc-brandの色がなければ、接続後にしかボタンを表示しません。アカウントからスニペットを再コピーしてください。 - プロジェクトが一時停止中、またはサイトキーが不明： サーバーは
unknown_site_key（切断コード4002）を返します。このタブでは、10分間再試行しません。 - コアを読み込めない： コンソールに
[reactive.chat] core.js …と表示されます。多くの場合はscript-srcや広告ブロッカーがアドレスをブロックしています。独自ドメインを参照してください。
ボタンはあるが、メッセージが届かない
data-rc-ws-urlなしでloader.jsを自己配信している： ウィジェットは運営側のドメインでチャットサーバーを探します。Networkタブにはwss://ws.<your-domain>/rc_wss/への失敗する接続試行が表示されます。対処：data-rc-ws-url="wss://ws.reactive.chat/rc_wss/"を指定します。origin_denied、切断コード1008： 許可するオリジンにページのドメインがありません。チャットのサブドメインではなく、Webサイトのドメインを入力してください。- CSPによるブロック： コンソールにCSPメッセージが表示されます。対象は
wss://…またはhttps://…/rc_wss/h/auf.connect-srcに両方の形式を追加してください。 - WebSocketを使えない企業ネットワーク： 2回失敗すると、HTTPフォールバックに切り替えます。それも使えなければ、30秒未満でリクエストを切る、または応答をバッファリングするプロキシがないか確認してください（通信）。
- 不正利用対策によるブロック（切断コード1008
blocked）：有効なプロキシキーのない独自プロキシの背後でよく発生します。すべての訪問者が同じアドレスになるためです。 - メッセージが長すぎる： ウィジェットは、プランの上限（1,000または4,000文字）を超えるテキストを送信しません。
ログイン済みユーザーが匿名扱いになる
errorフレームには、detail.reason付きのauth_failedが含まれます。
- no_hash –
identifyにuserHashがありません。 - no_secret – プロジェクトにシークレットが設定されていません。
- bad_exp –
expが秒ではなくミリ秒、または整数ではありません。 - expired – ページを長時間開いているか、サーバーの時計が誤っています。ページの読み込み時に新しいハッシュを計算してください。
- exp_too_far – 24時間を超えて先の時刻です。
- bad_hash – シークレット、順序（
userId + "." + exp）、文字セットが一致しません。シークレットは、デコードしたバイト列ではなく文字列として使います。メールアドレスを含める場合は、渡すものと完全に同じ形で署名してください。
詳細：訪問者の本人確認。
顧客データが届かない
- ログイン済みなのにアシスタントがログインを求める：
expがないか期限切れです。expがなければ、顧客データは取得しません。 - アカウントの接続をテストに理由が表示されます（
http_401、zeitueberschreitung、umleitung、adresse_privatなど）。署名対象はX-RC-Zeit + "." + raw bodyです。再エンコードしたJSONではなく、受信したバイト列で検証してください。 - アシスタントの回答にフィールドがない：アカウントで有効になっていないか、決して取り込まないフィールドの一覧に含まれています。
詳細：顧客データエンドポイント。
Webhookが届かない
- 連携は有効で、イベントは選択されていますか（未選択ならすべて）？有効化後は最大15秒待ってください。
- エンドポイントの応答に10秒を超えてかかるか、リダイレクトを返しています。
- エンドポイントが一度410を返すと、連携は無効になります。再度有効にしてください。
- 署名が一致しない：生の本文と
X-RC-Timestamp + "." + bodyで計算し、sha256=のプレフィックスに注意してください。 dataに内容がない：各イベントのフィールドはWebhookに記載しています。選択していないイベントは、そもそも届きません。
サーバーAPI
- 401
auth_failed： キーが失効済み、入力ミス、または作成者が管理者ではなくなっています。 - 403
insufficient_scope： 権限範囲が不足しています。required_scopeが必要なものを示します。 - 429： 毎分120リクエストを超えています。
Retry-Afterに従ってください。 - 415/413：
Content-Type: application/jsonがないか、本文が64 KiBを超えています。
プライバシーのテキストが表示されない
- ページにローダーがないか、同意管理プラットフォームがブロックしています。
datenschutz.jsを直接埋め込んでください。 - プロジェクトにWebサイトのドメインが登録されていないか、プロジェクトが一時停止中です。
- 要素の
data-rc-privacy-state="error"は、リクエストの失敗を示します。
公開前のチェックリスト
- Webサイトのすべてのドメインを許可するオリジンに登録した。
- プライバシーポリシーのページを含め、チャットを表示するすべてのページに、アカウントのスニペットをそのまま設置した。
- CSP：
script-srcに配信先、connect-srcにwss://とhttps://, 画像用にimg-srcを指定した。 - 同意：
data-rc-consentまたは同意管理プラットフォーム（TCF v2／consented.eu）を確認し、同意あり・なしの両方でテストした。 - プライバシーポリシーを拡張した（
<div data-rc-privacy>または文例）。 - 本人情報：
exp付きのuserHashをサーバーで計算し、シークレットはサーバー環境だけに置き、init_ok.identity.verifiedがtrueである。 - 機密テキストの領域に
data-rc-privateを付けた。 - 独自ドメインの場合、5つの確認ステップがすべて「OK」で、プロキシキーはプロキシ設定だけに置き、
/rc_wss/h/をアクセスログに記録していない。 - Webhook：署名とタイムスタンプを検証し、
X-RC-Deliveryで重複を検出し、すばやく2xxを返す。 data-rc-transport="http"で、HTTPフォールバックを1回テストした。- モバイル表示（480ピクセル未満では全画面）とキーボード操作を確認した。
最終更新: