React Integration

Add qvctrs to Create React App, Vite, or any React project using a simple useEffect hook or index.html modification.

Easy2 minutes

Option 1: index.html (Recommended)

The simplest approach — add the snippet directly to your HTML template.

Create React App

Edit public/index.html:

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>My React App</title>

  <!-- qvctrs SDK -->
  <script>
  window.qvctrs=window.qvctrs||{};window.qvctrs.q=window.qvctrs.q||[];
  window.qvctrs.init=window.qvctrs.init||function(){window.qvctrs.q.push(['init'].concat(Array.prototype.slice.call(arguments)))};
  window.qvctrs.init({siteId:'YOUR_SITE_ID'});
  </script>
  <script src="https://www.qvctrs.com/qvctrs-sdk-v2.js" async></script>
</head>
<body>
  <div id="root"></div>
</body>
</html>

Vite

Edit index.html in your project root:

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My Vite App</title>

  <!-- qvctrs SDK -->
  <script>
  window.qvctrs=window.qvctrs||{};window.qvctrs.q=window.qvctrs.q||[];
  window.qvctrs.init=window.qvctrs.init||function(){window.qvctrs.q.push(['init'].concat(Array.prototype.slice.call(arguments)))};
  window.qvctrs.init({siteId:'YOUR_SITE_ID'});
  </script>
  <script src="https://www.qvctrs.com/qvctrs-sdk-v2.js" async></script>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
</body>
</html>

Option 2: React Component

If you need to initialize from within React (e.g., dynamic Site ID), create a component:

// src/components/Qvctrs.tsx
import { useEffect } from 'react';

declare global {
  interface Window {
    qvctrs: {
      init: (options: { siteId: string }) => void;
      q?: unknown[];
      version?: string;
    };
  }
}

export function Qvctrs({ siteId }: { siteId: string }) {
  useEffect(() => {
    // Create shim if needed
    window.qvctrs = window.qvctrs || {};
    window.qvctrs.q = window.qvctrs.q || [];
    window.qvctrs.init = window.qvctrs.init || function(...args) {
      window.qvctrs.q!.push(['init', ...args]);
    };

    // Initialize
    window.qvctrs.init({ siteId });

    // Load SDK
    const script = document.createElement('script');
    script.src = 'https://www.qvctrs.com/qvctrs-sdk-v2.js';
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup on unmount (optional, SDK handles this)
    };
  }, [siteId]);

  return null;
}

// Usage in App.tsx:
// <Qvctrs siteId="qv_your_site_id" />

Use in your App

// src/App.tsx
import { Qvctrs } from './components/Qvctrs';

function App() {
  return (
    <>
      <Qvctrs siteId="qv_your_site_id" />
      {/* Your app content */}
    </>
  );
}

Why index.html is recommended

Adding scripts to index.html ensures they load before React hydrates, capturing events from the very first render. The component approach may miss early interactions.

Environment Variables

Create React App

# .env
REACT_APP_QVCTRS_SITE_ID=qv_your_site_id

Use with: %REACT_APP_QVCTRS_SITE_ID% in index.html (CRA replaces this at build time)

Vite

# .env
VITE_QVCTRS_SITE_ID=qv_your_site_id

Use with: import.meta.env.VITE_QVCTRS_SITE_ID in your component

Verify Installation

Start your dev server (npm start or npm run dev)
Open your app in the browser
Open Developer Tools → Console
Run window.qvctrs.version — should show "2.4.0"

Checklist

✓Snippet added to index.html or component created
✓Site ID replaced with your actual ID
✓Verified in browser console

React Router / SPA Navigation

The qvctrs SDK automatically tracks client-side navigation. You don't need to do anything special for React Router or other SPA routing libraries — page transitions are captured automatically.