ステップ1：4 分類で切り分け（読込 / 設定 / フレームワーク / 表示）
どんな「チャットが出ない」でも、まず 4 分類に絞る——これだけで遠回りの大半を省ける。フロー図で決定を明確に：まずスクリプトが読み込まれたか（F12 で meiqia.js）、次に設定・フレームワーク・表示層のどれか。基本は 美洽サイト設置ガイド へ。
設置の原理：なぜこの JS 注入が失敗 / 拒否されるか
一言で十分：美洽のウェブウィジェットはページ内の静的コンポーネントではなく、meiqia.js を美洽の外部ドメインから非同期で読み込み、チャットコンテナ（DOM / iframe）を動的注入し、クロスオリジンの長時間接続を張る。注入成功には「スクリプトが読み込めた（位置正・広告ブロックされない）、コンテナがサイト CSS / 他プラグインに覆われない、entId とドメインが一致、SPA 遷移後に再マウント」が必要。下図でこの経路と 4 つの遮断点を図解——同じコードがサイト / フレームワークで効いたり効かなかったりの根因。
コードは正しく貼ったのに非表示：設置セルフチェック盤を確認
位置・meiqia.js 200・entId を確認しても出ないなら、ほぼ「広告ブロック」か「フレームワーク / 重なり」。下の盤は重要度順：緑は通常 OK、赤（広告ブロック、SPA / 他プラグインの重なり）が高発の落とし穴。1 つずつ確認すると早い。
全症状対照表（現象 / 公式の位置づけ・L2 根本原因）
下表は非表示 / エラーの主な症状を一覧化し、各々に公式の位置づけと L2 根本原因を併記。上の検索ボックスはこの表のデータ駆動——出会ったキーワードで検索できる。
| 症状 | 分類 | L1 現象 / 公式の位置づけ | L2 根本原因 |
|---|---|---|---|
| チャットウィンドウ / 吹き出しが全く表示されない | 読込失敗 | 美洽ウェブウィジェットは貼り付けた 1 つの JS でフローティングチャットを読み込む；コードが正しく埋め込まれ、接入サイトが管理画面で設定済みか確認。 | ウィジェットは meiqia.js が非同期読込後に DOM へ注入する仕組み。全く出ないのは通常「スクリプトが読み込まれていない」——位置ミス、広告ブロック / キャッシュ、ドメイン / entId 不一致で注入が走っていない。 |
| 読込めたがチャットボタンが出ない | 表示異常 | ウィジェットコードはサイトに自動適応してチャットボタンを表示する；表示異常ならスタイルで隠れていないか、初期化が中断していないか確認。 | 読込めたのにボタンが出ないのは多く「表示層」の問題：サイト全体 CSS がボタン位置を上書き / display:none、z-index 負け、他の固定要素が覆う；ページ内の別 JS エラーで初期化が中断する場合も。 |
| meiqia.js が広告ブロック拡張に遮断される | 読込失敗 | 美洽の接客スクリプトはサードパーティドメイン由来；ブロック拡張があると広告 / トラッカーと判定し読込を阻止する場合があり、ブロック解除かホワイトリストを推奨。 | ERR_BLOCKED_BY_CLIENT はブラウザ拡張（AdBlock / uBlock / AdGuard）がフィルタリストでリクエストを遮断したもの。美洽は「サードパーティ外部 + リアルタイム通信」で、こうしたルールに広告 / トラッカーと誤判定され「管理画面は正常、ユーザー側は非表示」の偽障害に。 |
| meiqia.js が 404 / 異常ステータス / 混在コンテンツ | 読込失敗 | デプロイ後、Network パネルで meiqia.js を検索；ステータス 200 なら位置が正しく正常読込。 | 200 以外の主因：ページ / CDN キャッシュで保持（公開後未更新）、HTTP ページで読込 / 証明書チェーン不全で混在コンテンツ遮断、コード破損 / コピー不足。ここで失敗すると注入も接続も起きない。 |
| コードの位置ミス（head ブロック / 無効） | 読込失敗 | 美洽公式はページ末尾・</body> タグの前への貼付を推奨；ウィジェットはページ主要コンテンツの読込後に実行。 | ウィジェットは DOM 準備後にコンテナ注入が必要。<head> では描画をブロック（弱回線で先に白画面）、DOM 未準備で実行し注入失敗；一部の非同期 / モジュールスコープ内では読込順が崩れる。 |
| チャットウィンドウ / ボタンのスタイル崩れ | 表示異常 | ウィジェットは自身のスタイルを挿入しサイトに自動適応；サイト全体スタイルと競合すると外観異常の場合あり。 | 美洽は実行時に CSS を挿入；サイト全体スタイル（ユニバーサルセレクタ / 高優先度 / reset）がそのクラスを先に上書きすると、ボタン位置・重なり・フォントが崩れる——「動的注入 + 同一ドキュメントのスタイル空間共有」の副作用。 |
| ボタンが画面外 / 覆われる | 表示異常 | ウィジェットボタンは固定配置のフローティングで出る；他の固定要素に覆われたら重なり / 位置を調整。 | サイトの他の position:fixed 要素（トップへ戻る、フローティング広告、自前サポートバー）が高い z-index で覆う、またはテーマが座標を誤算し、ボタンが「画面外 / 覆われる」。 |
| 他プラグイン / 解析の DOM 競合 | 表示異常 | DOM を変更したりリクエストを横取りする他スクリプトは、ウィジェットの正常な読込 / 表示に影響しうる。 | ヒートマップ / 解析 / コンバージョン系は DOM を書換え、オーバーレイを注入、リクエストを横取りする；美洽と同じドキュメントへ注入するため重なり / イベントが干渉し、コンテナが覆われたり init が中断。 |
| SPA ルート遷移後にウィジェットが消える | フレームワーク | シングルページアプリ（SPA）はフレームワークのルートフックで美洽ウィジェットを読込 / 初期化し、フロントルーティングに適応させる。 | SPA はフロントルーティングでビューを切替え DOM を破棄 / 再構築するが、meiqia.js は既定で初回読込時に一度だけ注入し、ルート遷移で自動再構築しないため「ページを変えるとチャットが消える」。 |
| 手動初期化が必要（manualInit / init） | フレームワーク | 美洽埋め込みコードの後に _MEIQIA('manualInit') を入れると、ダウンロード後の自動初期化を止められる；必要時に _MEIQIA('init') で手動初期化。 | 既定では DL 直後に自動初期化；コンテナ準備 / 顧客情報受渡 / ルート確定の後に表示したい時、その自動タイミングは「早すぎ」——手動初期化に切替え順序を自分で制御。 |
| entId 不一致 / 対話を受けられない | 設定 / 許可 | コード内 entId の後の数字は企業の一意 ID；ワークベンチと不一致だと対話を受けられない；設定-チーム-ID 照会 で企業 ID を確認。 | entId はスニペットを特定企業アカウントに紐付ける。他人 / 別環境のコード、複数アカウント混同だと、フロントは表示するがメッセージが「別企業」へ届き、本ワークベンチには来ない——「表示は正常だが受信ゼロ」の典型。 |
| サイトのドメインが管理画面で未許可 | 設定 / 許可 | 美洽管理画面で「接入サイトを追加」でき、各サイトに個別設定；新サイトは管理画面で設定後に正常接入。 | 美洽は複数サイトを「接入サイト」として管理；ドメインは管理画面で登録 / 許可されて初めて認識される。本番ドメインを未追加だと認識されない / 正しい設定に紐付かない。 |
| 複数サイト / サブチャネル（探頭）の混線 | 設定 / 許可 | 美洽は複数サイトに別々のウィジェットとチャットリンクを設置できる（サブチャネル / 探頭）；既定サイト以外も追加でき、各自個別設定。 | 事業ラインごとに別の対応グループ / 自動メッセージが必要だが、各サイトが既定の同一コードを共用すると出所が分からず設定が混線。サブチャネル（探頭）は「1 企業・複数入口・振り分け」のための設計。 |
| モバイル Web のチャット非表示 / 別途設置が必要 | モバイル / SDK | ウィジェットコードはサイトに自動適応；モバイル / PC は同一コードだが別途設置が必要。 | 多くのチームは PC とモバイルが別ページ / テンプレで、PC テンプレにしか貼っていない。コードは同一で自動適応するが「貼る」工程をモバイルテンプレでも行う必要があり、漏れるとモバイルに無い。 |
| ネイティブアプリ SDK 設置 / AppKey | モバイル / SDK | アプリ内設置は美洽ワークベンチ（設定-接入-SDK の「APP 設定を追加」）で AppKey を取得し、開発者が公式ドキュメント / Demo を参照して iOS / Android SDK を統合。 | アプリでは Web JS でなくネイティブ SDK を使う：まず「APP 設定を追加」で AppKey を取得し、各プラットフォームで SDK を統合してチャット UI、未読、プッシュ等を実装——Web ウィジェットとは全く別経路。 |
| SDK メッセージプッシュが届かない | モバイル / SDK | 美洽 SDK のプッシュは 2 種：「プッシュしない」は対応者のメッセージがアプリ内のみ（アプリを開くと受信）；「カスタムプッシュサーバ」設定で、アプリ終了後もスマホにプッシュ。 | 「オフラインプッシュ」が来ないのは多く、方式が「プッシュしない」、またはカスタムプッシュサーバ / 各プラットフォームのプッシュ証明書が未設定。経路は「美洽 → アプリサーバ → ユーザーのスマホ」で、1 つ欠けるとアプリ内のみ。 |
| 内蔵ボタンを隠す / 自前の入口 | API 呼び出し | _MEIQIA('withoutBtn') で美洽内蔵チャットボタンを非表示にできる；初期化成功後に _MEIQIA('showPanel') でチャットを開く。 | 既定では内蔵フローティングボタンが描画される；自前入口にするには init 前 / 時に「内蔵ボタン不要」を宣言し、「チャットを開く」動作を自前要素に紐付ける——API タイミングの問題で「ボタンの故障」ではない。 |
| 顧客情報の受け渡し / 同期が効かない | API 呼び出し | 美洽ウェブウィジェットは「顧客情報の受け渡し」「顧客同期」「顧客カスタムイベント情報の追加」を提供し、訪問者情報をチャットへ持ち込む。 | これらは正しい init タイミング内で呼ぶ必要：init 成功後（または manualInit + init のタイミング）に設定。早すぎ / 遅すぎ、フィールド形式の誤りで「設定したが無効」。 |
美洽 非表示の原因と設置方式の比較（2026 推計）
以下は美洽公式ヘルプ（接入渠道 / JavaScript ウェブウィジェット API）と公開の設置トラブル対応を総合した 2026 推計（各社の確約値でも一次測定でもなく参考用。版とブラウザポリシーで変動）：
| 項目 | 推計 / 対照 |
|---|---|
| 非表示の原因内訳（コミュニティ / チケット・推計） | 位置 / 未読込 ≈ 35% > 広告ブロック / 拡張 ≈ 25% > 設定 / 許可（entId / ドメイン）≈ 20% > フレームワーク（SPA）≈ 12% > スタイル / 他プラグイン競合 ≈ 8% |
| 設置の本質 | ウェブウィジェット = サードパーティ外部ドメインの非同期 JS が DOM を注入 + クロスオリジン長時間接続（埋め込み静的コンポーネントではない）。ゆえに位置・広告ブロックルール・ページ CSS の重なり・SPA ライフサイクルの影響を受ける |
| 各端の設置方式（推計） | PC / モバイル Web = JS ウィジェット（同一コード・別途設置）；アプリ = ネイティブ SDK（AppKey）；WeChat / 抖音 / 小紅書 = チャネル許可接入 |
| 広告ブロックの影響（推計） | PC で約 30〜40% のユーザーが広告ブロック拡張を導入 → サードパーティの接客スクリプトが広告ルールで遮断（ERR_BLOCKED_BY_CLIENT）、「管理画面は正常、ユーザー側は非表示」の主因 |
| JS ウィジェット反映速度（公式） | 専用 JS をページ末尾に貼ると約 3〜5 分で反映；entId は企業の一意 ID、ワークベンチと不一致だと対話を受けられない |
推計の根拠：出典基線 + 時間外挿（meiqia.com/help 接入渠道 / JavaScript ウェブウィジェット、meiqia.im 設置ガイド、公開の設置トラブル対応 2026 取得）。版とブラウザの遮断ポリシーで変動。美洽の最新公式を基準に。
美洽 5 つの設置方式の比較（コード / 難度 / 機能 / 用途 / 反映速度）
どの設置方式？下の対照は美洽公式情報を総合した横断クイック参照（コード量、機能の充実度、用途、反映速度）。多くのサイトは「ウェブ JS ウィジェット」を選ぶ。
| 設置方式 | コード / 難度 | 機能の充実度 | 用途 | 反映速度 |
|---|---|---|---|---|
| ウェブ JS ウィジェット | 1 つの JS . 低 | 最も充実（フロート / ポップ / 自動挨拶 / 訪問者軌跡） | PC + モバイルサイト（公式推奨） | 約 3〜5 分 |
| チャットリンク | コード無し . 最低 | 基本対話 | 技術無し / チャットリンクを手軽に | 即時 |
| API / WebIM SDK | 開発要 . 高 | 深い customization（独自 UI / システム / 注文連携） | 開発力があり深く融合 | 開発次第 |
| ネイティブ App SDK | SDK 統合 . 高 | アプリ内チャット + メッセージプッシュ | iOS / Android アプリ | 開発次第 |
| CMS 簡易設定 | プラグイン / ワンクリック . 低 | JS ウィジェットと同等 | WordPress / 凡科 / Shopify 等 | 数分 |
チャネル / 場面 → 設置成否マップ
同じ美洽でもチャネル / 場面で設置方式が異なる。下図は主要チャネルの設置成否：緑＝貼ればOK、黄＝設定要（別途設置 / init / ホワイトリスト）、赤＝方式変更（広告ブロック / entId / アプリは SDK）。
よくある質問
美洽のチャットウィンドウ / 吹き出しが全く表示されないはどう直す？
美洽ウェブウィジェットは貼り付けた 1 つの JS でフローティングチャットを読み込む；コードが正しく埋め込まれ、接入サイトが管理画面で設定済みか確認。 ウィジェットは meiqia.js が非同期読込後に DOM へ注入する仕組み。全く出ないのは通常「スクリプトが読み込まれていない」——位置ミス、広告ブロック / キャッシュ、ドメイン / entId 不一致で注入が走っていない。 F12 → Network で meiqia.js：リクエスト無し→コード未反映（位置 / キャッシュ）；200 以外→遮断かパス；全て正常でも非表示→entId / ドメイン許可と下の各分類を確認。
美洽の読込めたがチャットボタンが出ないはどう直す？
ウィジェットコードはサイトに自動適応してチャットボタンを表示する；表示異常ならスタイルで隠れていないか、初期化が中断していないか確認。 読込めたのにボタンが出ないのは多く「表示層」の問題：サイト全体 CSS がボタン位置を上書き / display:none、z-index 負け、他の固定要素が覆う；ページ内の別 JS エラーで初期化が中断する場合も。 F12 → Elements で美洽コンテナの有無 / 非表示 / 画面外を確認；サイトのカスタム CSS / 他スクリプトを一時停止し再確認；コンソールで中断エラーを確認。
美洽のmeiqia.js が広告ブロック拡張に遮断されるはどう直す？
美洽の接客スクリプトはサードパーティドメイン由来；ブロック拡張があると広告 / トラッカーと判定し読込を阻止する場合があり、ブロック解除かホワイトリストを推奨。 ERR_BLOCKED_BY_CLIENT はブラウザ拡張（AdBlock / uBlock / AdGuard）がフィルタリストでリクエストを遮断したもの。美洽は「サードパーティ外部 + リアルタイム通信」で、こうしたルールに広告 / トラッカーと誤判定され「管理画面は正常、ユーザー側は非表示」の偽障害に。 シークレット / 広告ブロック OFF で再確認——表示されれば遮断が原因；ユーザーにサイトのホワイトリスト化を案内；フロントで接客スクリプトを遅延 / 条件読込し一部の自動ルールを回避。
美洽のmeiqia.js が 404 / 異常ステータス / 混在コンテンツはどう直す？
デプロイ後、Network パネルで meiqia.js を検索；ステータス 200 なら位置が正しく正常読込。 200 以外の主因：ページ / CDN キャッシュで保持（公開後未更新）、HTTP ページで読込 / 証明書チェーン不全で混在コンテンツ遮断、コード破損 / コピー不足。ここで失敗すると注入も接続も起きない。 公開後は CDN / ブラウザキャッシュをクリア（またはシークレット）；全サイト HTTPS・証明書チェーン完全・混在コンテンツ無し；コピーしたコードの完全性・未エスケープを確認。
美洽のコードの位置ミス（head ブロック / 無効）はどう直す？
美洽公式はページ末尾・</body> タグの前への貼付を推奨；ウィジェットはページ主要コンテンツの読込後に実行。 ウィジェットは DOM 準備後にコンテナ注入が必要。<head> では描画をブロック（弱回線で先に白画面）、DOM 未準備で実行し注入失敗；一部の非同期 / モジュールスコープ内では読込順が崩れる。 美洽 JS を全ページ共通の末尾・</body> の前へ；SPA は「SPA ルート」項目で manualInit；バンドラの tree-shaking で消えないよう注意。
美洽のチャットウィンドウ / ボタンのスタイル崩れはどう直す？
ウィジェットは自身のスタイルを挿入しサイトに自動適応；サイト全体スタイルと競合すると外観異常の場合あり。 美洽は実行時に CSS を挿入；サイト全体スタイル（ユニバーサルセレクタ / 高優先度 / reset）がそのクラスを先に上書きすると、ボタン位置・重なり・フォントが崩れる——「動的注入 + 同一ドキュメントのスタイル空間共有」の副作用。 F12 でどのサイトルールが美洽コンテナを上書きしたか確認；サイト全体スタイルのスコープを絞り汎用クラスへの影響を低減；必要なら美洽にコンテナの重なり調整を依頼。
美洽のボタンが画面外 / 覆われるはどう直す？
ウィジェットボタンは固定配置のフローティングで出る；他の固定要素に覆われたら重なり / 位置を調整。 サイトの他の position:fixed 要素（トップへ戻る、フローティング広告、自前サポートバー）が高い z-index で覆う、またはテーマが座標を誤算し、ボタンが「画面外 / 覆われる」。 F12 で美洽コンテナの実座標 / z-index を確認；それを上げるか覆う要素を下げる；複数の固定フローティングを同じ隅に重ねない。
美洽の他プラグイン / 解析の DOM 競合はどう直す？
DOM を変更したりリクエストを横取りする他スクリプトは、ウィジェットの正常な読込 / 表示に影響しうる。 ヒートマップ / 解析 / コンバージョン系は DOM を書換え、オーバーレイを注入、リクエストを横取りする；美洽と同じドキュメントへ注入するため重なり / イベントが干渉し、コンテナが覆われたり init が中断。 疑わしいプラグインを 1 つずつ一時停止し競合源を特定；読込順 / コンテナ重なりを調整；ヒートマップ等を美洽コンテナ領域から除外。
美洽のSPA ルート遷移後にウィジェットが消えるはどう直す？
シングルページアプリ（SPA）はフレームワークのルートフックで美洽ウィジェットを読込 / 初期化し、フロントルーティングに適応させる。 SPA はフロントルーティングでビューを切替え DOM を破棄 / 再構築するが、meiqia.js は既定で初回読込時に一度だけ注入し、ルート遷移で自動再構築しないため「ページを変えるとチャットが消える」。 _MEIQIA('manualInit') で自動初期化を止め、ルートフック（React useEffect / Vue mounted / router afterEach）で必要に応じ _MEIQIA('init') して再マウント；複数インスタンス初期化を避ける。
美洽の手動初期化が必要（manualInit / init）はどう直す？
美洽埋め込みコードの後に _MEIQIA('manualInit') を入れると、ダウンロード後の自動初期化を止められる；必要時に _MEIQIA('init') で手動初期化。 既定では DL 直後に自動初期化；コンテナ準備 / 顧客情報受渡 / ルート確定の後に表示したい時、その自動タイミングは「早すぎ」——手動初期化に切替え順序を自分で制御。 埋め込みコード後に _MEIQIA('manualInit')；条件（DOM / ログイン状態 / ルート）が整ってから _MEIQIA('init')；顧客情報等はドキュメント順に init タイミング内で呼ぶ。
設置の詳細は 美洽サイト設置、APP SDK 設置；入門は 美洽ガイド。検索可能な完全版（本ツール含む）は 美洽 設置対処検索（GitHub Pages）。