Zum Hauptinhalt springen

React (Vite)

Installieren Sie das Selgeo-Tracking-Snippet in einer mit Vite gebauten React-Single-Page-Anwendung. Der empfohlene Weg ist ein einfaches <script>-Tag in index.html — derselbe Einzeiler, den das Dashboard rendert. Ein Fallback per useEffect-Injektion ist am Ende dieser Seite dokumentiert für Projekte, die index.html nicht bearbeiten können.

API-Version: v1

Wenn Sie nicht Vite + React verwenden, lesen Sie stattdessen die HTML- / einfache-Script-Anleitung, die Next.js-Anleitung oder die WordPress-Anleitung.

Warum index.html?​

In einer Vite-SPA ist index.html der kanonische Einstiegspunkt: Es wird an den Browser ausgeliefert, bevor irgendein React-Code läuft, jede Route wird aus derselben Datei bedient, und der Browser kümmert sich automatisch um die Deduplizierung von <script>-Tags. Das Snippet hier zu platzieren bedeutet:

  • Das Snippet ist verfügbar, bevor React hydratisiert, sodass ein initialer ?ref=… auch bei kaltem Cache erfasst wird.
  • Kein useEffect, kein Double-Mount-Risiko, keine Überraschungen mit React Strict Mode.
  • Eine einzige Quelle der Wahrheit — Sie müssen nicht daran denken, das Snippet in jeder Layout-Komponente einzufügen.

Da das Snippet cookielos und sessionStorage-basiert ist, kann es problemlos auf jeder Seite einer Vite-SPA geladen werden, ohne das Verhalten Ihrer React-App zu verändern.

Installation — Empfohlener Weg​

Schritt 1: index.html öffnen​

Vite-Projekte halten index.html im Projekt-Stammverzeichnis (neben vite.config.ts), nicht in public/. Öffnen Sie es in Ihrem Editor.

Schritt 2: Snippet vor dem App-Modul einfügen​

Platzieren Sie das Selgeo-<script> vor <script type="module" src="/src/main.tsx"></script>, damit die async-Anfrage des Snippets bereits unterwegs ist, bevor das React-App-Modul mit der Auswertung beginnt. So kann Selgeo den initialen ?ref=… beim ersten Paint erfassen, bevor React, der Router oder ein clientseitiges URL-Rewrite die URL berühren.

<!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>

Ersetzen Sie pk_test_YOUR_KEY durch Ihren öffentlichen API-Schlüssel aus Einstellungen > API-Schlüssel im Selgeo-Dashboard.

index.html im Editor geöffnet, mit dem Selgeo-script-Tag oberhalb des App-Modul-script

Schritt 3: Dev-Server neu starten​

pnpm dev
# oder
npm run dev

Vite übernimmt index.html-Änderungen beim Kaltstart. Hot-Module-Reload verpasst gelegentlich HTML-Änderungen, daher ist ein Neustart die sicherste Option.

Erforderliche und optionale Attribute​

AttributErforderlichBeschreibung
srcJaCDN-URL. Immer https://cdn.selgeo.com/v1/selgeo.js.
data-merchantJaIhr öffentlicher API-Schlüssel (pk_test_* oder pk_live_*).
asyncJaAsynchrones Laden; blockiert die React-Hydration nicht.
data-debugNeinAusführliches Konsolen-Logging. Vor dem Go-Live entfernen.
data-api-urlNeinÜberschreibt den API-Endpunkt. Nur in Staging- / Entwicklungs-Workspaces vorhanden — das Selgeo-Dashboard fügt ihn bei Bedarf automatisch ein.

Single-Page-Navigation​

Das Snippet lauscht auf popstate, history.pushState und history.replaceState. Wenn Sie TanStack Router, React Router oder einen anderen clientseitigen Router verwenden, ist keine weitere Konfiguration nötig — ein ?ref=…-Parameter, der auf irgendeiner Route eingeführt wird, wird automatisch erfasst.

Installation überprüfen​

  1. Starten Sie den Dev-Server (pnpm dev).
  2. Erstellen Sie einen Tracking-Link im Selgeo-Dashboard unter Programme > Tracking-Links.
  3. Öffnen Sie den Tracking-Link in einem frischen Browser-Tab: 
    http://localhost:5173/?ref=IHR_TEST_REF
  4. Öffnen Sie die Developer Tools (F12) und prüfen Sie die Konsole. Mit temporär hinzugefügtem data-debug sehen Sie: 
    [selgeo] ref detected IHR_TEST_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Führen Sie in der Konsole aus: 
    __selgeo.getClickId()
    Dies sollte einen UUID-String zurückgeben.
  6. Öffnen Sie das Selgeo-Dashboard. Der Klick sollte innerhalb weniger Sekunden unter Analytics erscheinen.

Browser-DevTools-Konsole mit den Debug-Zeilen selgeo ref detected und selgeo click_id stored

Alternative: Injektion per useEffect​

Verwenden Sie diesen Weg nur, wenn Sie index.html nicht bearbeiten können — zum Beispiel, wenn Ihr index.html von einem übergeordneten Framework erzeugt wird oder Sie das Snippet in eine Mikro-Frontend einbetten, dessen HTML-Schicht Sie nicht besitzen.

Dieses Muster bringt eine zusätzliche Sorge mit sich: In React 18+ Strict Mode (Standard in Vite-Templates) werden Effekte in der Entwicklung zweimal ausgeführt. Ohne einen Schutzmechanismus würde das Snippet zweimal injiziert und ein doppelter Klick könnte registriert werden. Verwenden Sie eine stabile Element-ID plus eine document.getElementById-Kurzschlussprüfung:

// 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;
}

Montieren Sie <SelgeoSnippet /> einmal nahe der Wurzel Ihres Komponentenbaums (typischerweise in App.tsx, neben Ihrem Router-Provider).

Warum der Schutzmechanismus wichtig ist:

  • React 18+ Strict Mode ruft Effekte in der Entwicklung absichtlich doppelt auf, um Nebeneffekt-Bugs sichtbar zu machen.
  • Ohne die document.getElementById-Kurzschlussprüfung würden zwei <script>-Elemente angefügt, beide ausgeführt, und das Snippet würde zwei Klicks für denselben Besucher registrieren.
  • Die stabile id="selgeo-snippet" lässt den Schutz über Hot-Reloads, Routenwechsel und Komponenten-Remounts hinweg funktionieren.

Dieses Muster ist auch nützlich, wenn ein Consent-Manager oder Feature-Flags das Snippet-Laden steuern müssen — verpacken Sie den Effekt-Body in Ihre Bedingung.

Fehlerbehebung​

Snippet wird nicht geladen​

  • Stellen Sie sicher, dass das <script> innerhalb von <body> steht, nicht in <head> (Vites index.html sollte bereits ein <body> haben).
  • Führen Sie pnpm build aus und prüfen Sie dist/index.html. Das Snippet sollte im gebauten HTML erscheinen.
  • Wenn Sie ein benutzerdefiniertes Vite-Plugin verwenden, das index.html umschreibt, stellen Sie sicher, dass es benutzerseitig hinzugefügte <script>-Tags erhält.
  • Prüfen Sie im Browser-Netzwerk-Tab den selgeo.js-Request — ein CORS- oder CSP-Fehler weist auf ein Konfigurationsproblem hin (siehe unten).

Klick wird nicht verfolgt​

  • Der Besucher muss mit ?ref=… auf der ersten Seitenansicht ankommen. Nachladevorgänge entfernen den Parameter (das Snippet schreibt die URL beim Erfassen um) — geben Sie einen frischen Tracking-Link aus, wenn Sie den aktuellen bereits verwendet haben.
  • Stellen Sie sicher, dass data-merchant einen gültigen pk_test_*- oder pk_live_*-Schlüssel enthält.
  • Wenn Sie die useEffect-Alternative verwenden, prüfen Sie, dass der document.getElementById-Schutz vorhanden und SELGEO_SCRIPT_ID auf der Seite eindeutig ist.
  • Überprüfen Sie den Dashboard-Modus (Test vs. Live) — eine Diskrepanz verwirft den Klick stillschweigend.

CSP-Blockierung​

Wenn Sie eine Content-Security-Policy über ein Vite-Plugin, ein Meta-Tag oder Ihren Origin-Server setzen, erlauben Sie die Selgeo-Ursprünge:

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

Bei Staging- / Dev-Workspaces, in denen data-api-url auf einen anderen Ursprung zeigt, fügen Sie diesen Ursprung ebenfalls zu connect-src hinzu.

Nächste Schritte​