단일 페이지 앱과 페이지 변경

위젯이 React, Vue, Angular, Next.js, Turbo 또는 htmx에서 페이지 변경을 자동 감지하는 방법, 서버에 보고하는 내용과 단일 페이지 앱에서 유의할 사항입니다.

단일 페이지 앱에서는 브라우저가 페이지를 한 번만 로드합니다. 그 후에는 프레임워크가 콘텐츠를 바꾸고 history.pushState로 주소를 변경합니다. 위젯은 이 변경을 자동으로 감지합니다. 따로 알리거나 다시 시작할 필요가 없습니다.

삽입: 정확히 한 번

로더를 앱 셸(index.html, 루트 레이아웃, _document)에 한 번 넣습니다. 경로가 바뀔 때마다 다시 렌더링하는 컴포넌트에 넣지 않습니다. 두 번 삽입해도 문제는 없습니다(두 번째 로더는 아무것도 하지 않음. 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>
  );
}

프레임워크 도우미가 생성한 <script>에 data-* 속성을 전달하는지 확인하는 가장 쉬운 방법은 요소 검사기입니다. 거기에 data-rc-site-key가 없으면 아무것도 시작하지 않습니다.

페이지 변경 감지 방식

위젯은 history.pushState를 가로채지 않으며 다음만 관찰합니다.

지원되는 경우 브라우저의 Navigation API(navigation.currententrychange),
그 외에는 popstate와 hashchange,
추가로 이벤트 없는 주소 변경을 찾는 타이머(1초마다, 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초에 한 번입니다. 계정, 결제나 장바구니 같은 페이지와 양식 필드는 읽지 않습니다. 어시스턴트가 읽으면 안 되는 영역은 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