Przejdź do głównej zawartości

React (Vite)

Zainstaluj snippet śledzący Selgeo w aplikacji single-page React zbudowanej z Vite. Zalecaną ścieżką jest zwykły tag <script> w index.html — ten sam jednolinijkowiec, który renderuje panel. Alternatywa oparta na useEffect jest udokumentowana na końcu tej strony dla projektów, które nie mogą edytować index.html.

Wersja API: v1

Jeśli nie używasz Vite + React, zobacz przewodnik HTML / zwykłego skryptu, przewodnik Next.js lub przewodnik WordPress.

Dlaczego index.html?​

W SPA Vite index.html jest kanonicznym punktem wejścia: jest dostarczany do przeglądarki przed uruchomieniem jakiegokolwiek kodu React, każda trasa jest serwowana z tego samego pliku, a przeglądarka automatycznie obsługuje deduplikację <script>. Umieszczenie snippeta tutaj oznacza:

  • Snippet jest dostępny przed hydratacją React, więc początkowe ?ref=… jest wychwytywane nawet przy zimnej pamięci podręcznej.
  • Bez useEffect, bez ryzyka podwójnego montowania, bez niespodzianek z React Strict Mode.
  • Jedno źródło prawdy — nie trzeba pamiętać o wstrzykiwaniu snippeta w każdym komponencie layoutu.

Ponieważ snippet jest bez ciasteczek i oparty na sessionStorage, można go bezpiecznie ładować na każdej stronie SPA Vite bez zmiany zachowania aplikacji React.

Instalacja — zalecana ścieżka​

Krok 1: Otwórz index.html​

Projekty Vite trzymają index.html w katalogu głównym projektu (obok vite.config.ts), nie wewnątrz public/. Otwórz go w swoim edytorze.

Krok 2: Dodaj snippet przed modułem aplikacji​

Umieść <script> Selgeo przed <script type="module" src="/src/main.tsx"></script>, aby żądanie async snippetu było już w drodze, zanim moduł aplikacji React rozpocznie ewaluację. Dzięki temu Selgeo widzi początkowe ?ref=… przy pierwszym paint, zanim React, router lub jakiekolwiek przepisanie po stronie klienta dotkną adresu URL.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Your App</title>
  </head>
  <body>
    <div id="root"></div>

    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
    ></script>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Zastąp pk_test_YOUR_KEY swoim publicznym kluczem API z Ustawienia > Klucze API w panelu Selgeo.

index.html otwarty w edytorze z tagiem script Selgeo dodanym nad script modułu aplikacji

Krok 3: Zrestartuj serwer deweloperski​

pnpm dev
# lub
npm run dev

Vite odbiera zmiany index.html przy zimnym starcie. Hot-module-reload czasami pomija edycje HTML, więc restart jest najbezpieczniejszą opcją.

Atrybuty wymagane i opcjonalne​

AtrybutWymaganyOpis
srcTakURL CDN. Zawsze https://cdn.selgeo.com/v1/selgeo.js.
data-merchantTakTwój publiczny klucz API (pk_test_* lub pk_live_*).
asyncTakAsynchroniczne ładowanie; nie blokuje hydratacji React.
data-debugNieObszerne logowanie w konsoli. Usuń przed wdrożeniem produkcyjnym.
data-api-urlNieNadpisuje endpoint API. Obecny tylko w workspace'ach staging / dev — panel Selgeo wstrzykuje go automatycznie, gdy jest potrzebny.

Nawigacja single-page​

Snippet nasłuchuje na zdarzenia popstate, history.pushState i history.replaceState. Jeśli używasz TanStack Routera, React Routera lub dowolnego innego routera po stronie klienta, dalsza konfiguracja nie jest potrzebna — parametr ?ref=… wprowadzony na dowolnej trasie jest wychwytywany automatycznie.

Weryfikacja instalacji​

  1. Uruchom serwer deweloperski (pnpm dev).
  2. Utwórz link śledzący w panelu Selgeo w Programy > Linki śledzące.
  3. Otwórz link śledzący w nowej karcie przeglądarki: 
    http://localhost:5173/?ref=TWOJ_TESTOWY_REF
  4. Otwórz Narzędzia deweloperskie (F12) i sprawdź konsolę. Z tymczasowo dodanym data-debug zobaczysz: 
    [selgeo] ref detected TWOJ_TESTOWY_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Wykonaj w konsoli: 
    __selgeo.getClickId()
    Powinno to zwrócić ciąg UUID.
  6. Otwórz panel Selgeo. Kliknięcie powinno pojawić się w Analytics w ciągu kilku sekund.

Konsola DevTools przeglądarki pokazująca linie debugu selgeo ref detected i selgeo click_id stored

Alternatywa: wstrzyknięcie przez useEffect​

Korzystaj z tej ścieżki tylko, jeśli nie możesz edytować index.html — na przykład, gdy index.html jest generowany przez framework wyższego poziomu lub osadzasz snippet w mikrofrontendzie, którego warstwy HTML nie posiadasz.

Ten wzorzec niesie ze sobą jedną dodatkową kwestię: w React 18+ Strict Mode (domyślnie w szablonach Vite) efekty wykonują się dwukrotnie w trybie deweloperskim. Bez zabezpieczenia snippet zostałby wstrzyknięty dwukrotnie i mogłoby zostać zarejestrowane zduplikowane kliknięcie. Użyj stabilnego id elementu plus zwarcia z document.getElementById:

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

const SELGEO_SCRIPT_ID = 'selgeo-snippet';

export function SelgeoSnippet() {
  useEffect(() => {
    if (document.getElementById(SELGEO_SCRIPT_ID)) {
      return;
    }

    const script = document.createElement('script');
    script.id = SELGEO_SCRIPT_ID;
    script.async = true;
    script.src = 'https://cdn.selgeo.com/v1/selgeo.js';
    script.setAttribute('data-merchant', 'pk_test_YOUR_KEY');
    document.body.appendChild(script);
  }, []);

  return null;
}

Zamontuj <SelgeoSnippet /> raz blisko korzenia drzewa komponentów (typowo w App.tsx, obok providera routera).

Dlaczego zabezpieczenie ma znaczenie:

  • React 18+ Strict Mode celowo wywołuje efekty dwukrotnie w trybie deweloperskim, aby ujawnić błędy efektów ubocznych.
  • Bez zwarcia z document.getElementById zostałyby dołączone dwa elementy <script>, oba zostałyby wykonane, a snippet zarejestrowałby dwa kliknięcia dla tego samego odwiedzającego.
  • Stabilny id="selgeo-snippet" pozwala zabezpieczeniu działać przez hot-reloady, zmiany tras i ponowne montowanie komponentów.

Ten wzorzec jest także użyteczny, gdy zarządzanie zgodami lub feature flagi muszą warunkować ładowanie snippeta — owiń ciało efektu w swój warunek.

Rozwiązywanie problemów​

Snippet nie został załadowany​

  • Potwierdź, że <script> znajduje się wewnątrz <body>, nie w <head> (index.html Vite powinien już mieć <body>).
  • Uruchom pnpm build i obejrzyj dist/index.html. Snippet powinien pojawić się w zbudowanym HTML-u.
  • Jeśli używasz niestandardowej wtyczki Vite, która przepisuje index.html, upewnij się, że zachowuje dodane przez użytkownika tagi <script>.
  • Sprawdź żądanie selgeo.js w karcie Network przeglądarki — błąd CORS lub CSP wskazuje na problem konfiguracji (zobacz poniżej).

Kliknięcie nie zostało zarejestrowane​

  • Odwiedzający musi przybyć z ?ref=… przy początkowym ładowaniu strony. Przeładowania usuwają parametr (snippet przepisuje URL przy przechwyceniu) — wydaj nowy link śledzący, jeśli aktualny został już użyty.
  • Potwierdź, że data-merchant zawiera prawidłowy klucz pk_test_* lub pk_live_*.
  • Jeśli używasz alternatywy z useEffect, potwierdź, że zabezpieczenie document.getElementById jest na miejscu, a SELGEO_SCRIPT_ID jest unikalne na stronie.
  • Sprawdź tryb panelu (test vs. live) — niezgodność po cichu odrzuca kliknięcie.

Blokowanie przez CSP​

Jeśli ustawiasz Content-Security-Policy przez wtyczkę Vite, meta-tag lub serwer pochodzenia, zezwól na pochodzenia Selgeo:

script-src 'self' https://cdn.selgeo.com;
connect-src 'self' https://api.selgeo.com;

Dla workspace'ów staging / dev, gdzie data-api-url wskazuje gdzie indziej, dodaj również to pochodzenie do connect-src.

Następne kroki​