シングルページアプリとページ変更

React、Vue、Angular、Next.js、Turbo、htmxでウィジェットがページ変更を自動検出する仕組み、サーバーに通知する内容、シングルページアプリでの注意点を説明します。

シングルページアプリでは、ブラウザーは最初に1回だけページを読み込み、その後はフレームワークがコンテンツを入れ替え、history.pushStateでアドレスを変更します。ウィジェットは、これらの変更を自動で検出します。通知や再起動は不要です。

埋め込みは1回だけ

ローダーは、ルート変更のたびに再描画するコンポーネントではなく、アプリのシェル（index.html、ルートレイアウト、_document）に1回だけ置きます。2回目の埋め込みは問題ありませんが（2つ目のローダーは何もしません。scriptタグ参照）、タグを削除して再挿入しても、ウィジェットは再起動しません。

// Next.js (App Router), app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://cdn.reactive.chat/loader.js"
                data-rc-site-key="SITE_KEY"
                strategy="afterInteractive" />
      </body>
    </html>
  );
}

フレームワークのヘルパーがdata-*属性を生成した<script>に引き渡すかは、要素インスペクターで確認するのが簡単です。そこにdata-rc-site-keyがなければ、何も起動しません。

ページ変更を検出する仕組み

ウィジェットはhistory.pushStateにフックしません。次を監視するだけです。

対応している場合は、ブラウザーのNavigation API（navigation.currententrychange）。
それ以外では、popstateとhashchange。
加えて、イベントなしのアドレス変更を検出するタイマー（毎秒、Navigation APIがある場合は5秒ごと）。
戻る／進むキャッシュから復帰したときのpageshow。

ページ変更と見なすもの： 新しいアドレス（パスまたはクエリ）と、#/…、#!/…形式のハッシュルート。 ページ変更と見なさないもの： 単なるアンカーへの移動（#section）と、同じアドレスへのreplaceState。

通知する内容

変更から400 ms後（リダイレクトの途中の状態を数えないため）、ウィジェットはサーバーに状況情報のフレームを送信します。同意がある場合だけです。

url、path、title、referrer – urlとreferrerからは、先に機密性の高いクエリパラメーター（email、password、token、key、cardなど）を除去します。
locale、tz、viewport、screen、ua_hint。
アドレス内のutm_source、utm_medium、utm_campaign、gclid、msclkid、fbclid。
nav – 変更の種類：load、push、replace、reload、back、forward、traverse。

アプリが変更後にタイトルを設定する場合、ウィジェットは2秒後に修正を送ります。これにより、オペレーター画面で訪問者の現在のページが分かり、アシスタントはそのページに沿って回答します。

ウィジェットは、表示中のページテキストも再読み取りします（現在のページについての回答と「見せてください」用）。最後の変更から早くても1.2秒後、最大5秒に1回です。アカウント、購入手続き、カートなどのページや、フォームのフィールドからは読み取りません。読ませたくない領域にはdata-rc-privateを付けます（scriptタグ）。

ページ別に独自の状況情報を渡す

ページ変更を通知する専用メソッドはなく、必要もありません。表示中の商品など、現在のページに関する追加情報を渡したい場合は、ルート変更後にtrackを使用します。

// React Router
const location = useLocation();
useEffect(() => {
  if (produkt) {
    window.ReactiveChat('track', 'produktseite', {
      page_type: 'product', product_id: produkt.sku, price: produkt.preis,
      currency: 'EUR', in_stock: produkt.lieferbar
    });
  }
}, [location.pathname, produkt]);

届くフィールドの一覧は、訪問者の本人確認と状況情報の受け渡しにあります。

Turbo、htmx、Livewire

<body>全体を入れ替えるフレームワークは、その際にウィジェットの要素も削除します。ウィジェットは自分で再配置します（毎分最大10回）。会話は続行します。

SPAのログイン済みユーザー

再読み込みなしでログインした場合は、その後、サーバーから新しく取得したハッシュでidentifyを呼び出します。ユーザーが変わると、ウィジェットは入力中の下書きを前のユーザーのものと分離します。詳しくは訪問者の本人確認をご覧ください。

SPAのプライバシーテキスト

アプリが読み込み後にプライバシーポリシーを挿入しても、ウィジェットはドキュメントを監視するため、data-rc-privacy要素を見つけます。プライバシーの連携を参照してください。

次：セキュリティとCSP

最終更新: 2026-10-25