Ga naar hoofdinhoud

React (Vite)

Installeer het Selgeo-trackingsnippet in een met Vite gebouwde React-single-page-applicatie. De aanbevolen route is een eenvoudige <script>-tag in index.html — dezelfde one-liner die het dashboard toont. Een fallback via useEffect-injectie wordt onderaan deze pagina gedocumenteerd voor projecten die index.html niet kunnen bewerken.

API-versie: v1

Als u geen Vite + React gebruikt, raadpleeg dan in plaats daarvan de HTML- / eenvoudige-script-handleiding, de Next.js-handleiding of de WordPress-handleiding.

Waarom index.html?​

In een Vite-SPA is index.html het canonieke startpunt: het wordt naar de browser verzonden voordat enige React-code draait, elke route wordt vanuit hetzelfde bestand bediend, en de browser handelt de deduplicatie van <script>-tags automatisch af. Het snippet hier plaatsen betekent:

  • Het snippet is beschikbaar voordat React hydrateert, zodat een initiële ?ref=… zelfs bij een koude cache wordt vastgelegd.
  • Geen useEffect, geen dubbel-mount-risico, geen verrassingen met React Strict Mode.
  • Eén enkele bron van waarheid — u hoeft niet te onthouden om het snippet in elk layout-component te injecteren.

Omdat het snippet cookieloos en op sessionStorage gebaseerd is, is het veilig om op elke pagina van een Vite-SPA te laden zonder het gedrag van uw React-app te wijzigen.

Installatie — aanbevolen route​

Stap 1: Open index.html​

Vite-projecten houden index.html in de hoofdmap van het project (naast vite.config.ts), niet in public/. Open het in uw editor.

Stap 2: Voeg het snippet toe vóór uw app-module​

Plaats het Selgeo-<script> vóór <script type="module" src="/src/main.tsx"></script>, zodat de async-aanvraag van het snippet al onderweg is voordat de React-app-module begint te evalueren. Dit is wat Selgeo in staat stelt om de initiële ?ref=… bij de eerste paint te zien, voordat React, de router of een client-side rewrite de URL aanraken.

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

Vervang pk_test_YOUR_KEY door uw publieke API-sleutel uit Instellingen > API-sleutels in het Selgeo-dashboard.

index.html geopend in de editor met de Selgeo-script-tag toegevoegd boven het script van de app-module

Stap 3: Herstart de ontwikkelserver​

pnpm dev
# of
npm run dev

Vite pikt index.html-wijzigingen op bij een koude start. Hot-module-reload mist soms HTML-bewerkingen, dus een herstart is de veiligste optie.

Verplichte en optionele attributen​

AttribuutVerplichtBeschrijving
srcJaCDN-URL. Altijd https://cdn.selgeo.com/v1/selgeo.js.
data-merchantJaUw publieke API-sleutel (pk_test_* of pk_live_*).
asyncJaAsynchroon laden; blokkeert de React-hydratatie niet.
data-debugNeeUitgebreide consolelogging. Verwijderen voor go-live.
data-api-urlNeeOverschrijft het API-eindpunt. Alleen aanwezig in staging- / ontwikkelworkspaces — het Selgeo-dashboard voegt dit automatisch in waar nodig.

Single-page-navigatie​

Het snippet luistert naar popstate, history.pushState en history.replaceState. Als u TanStack Router, React Router of een andere client-side router gebruikt, is geen verdere configuratie nodig — een ?ref=…-parameter die op enige route wordt geïntroduceerd, wordt automatisch vastgelegd.

Uw installatie verifiëren​

  1. Start de ontwikkelserver (pnpm dev).
  2. Maak een trackinglink aan in het Selgeo-dashboard onder Programma's > Trackinglinks.
  3. Open de trackinglink in een nieuwe browsertab: 
    http://localhost:5173/?ref=UW_TEST_REF
  4. Open de Developer Tools (F12) en controleer de Console. Met tijdelijk toegevoegde data-debug ziet u: 
    [selgeo] ref detected UW_TEST_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Voer in de console uit: 
    __selgeo.getClickId()
    Dit zou een UUID-string moeten teruggeven.
  6. Open het Selgeo-dashboard. De klik zou binnen enkele seconden onder Analytics moeten verschijnen.

Browser DevTools Console met de debug-regels selgeo ref detected en selgeo click_id stored

Alternatief: injectie via useEffect​

Gebruik deze route alleen als u index.html niet kunt bewerken — bijvoorbeeld als uw index.html wordt gegenereerd door een hoger framework, of als u het snippet inbedt in een micro-frontend waarvan u de HTML-laag niet bezit.

Dit patroon brengt één extra aandachtspunt mee: in React 18+ Strict Mode (standaard in Vite-templates) worden effecten in ontwikkeling twee keer uitgevoerd. Zonder beveiliging zou het snippet twee keer worden geïnjecteerd en kon een dubbele klik worden geregistreerd. Gebruik een stabiel element-id plus een document.getElementById-kortsluiting:

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

Mount <SelgeoSnippet /> één keer in de buurt van de wortel van uw componentenboom (meestal in App.tsx, naast uw router-provider).

Waarom de beveiliging belangrijk is:

  • React 18+ Strict Mode roept effecten in ontwikkeling opzettelijk twee keer aan om side-effect-bugs aan het licht te brengen.
  • Zonder de document.getElementById-kortsluiting zouden twee <script>-elementen worden toegevoegd, beide zouden worden uitgevoerd, en het snippet zou twee klikken registreren voor dezelfde bezoeker.
  • De stabiele id="selgeo-snippet" zorgt ervoor dat de beveiliging werkt over hot-reloads, route-wissels en component-remounts heen.

Dit patroon is ook nuttig wanneer consent management of feature flags het laden van het snippet moeten conditioneren — verpak de body van het effect in uw conditie.

Probleemoplossing​

Snippet niet geladen​

  • Bevestig dat het <script> binnen <body> staat, niet in <head> (de index.html van Vite moet al een <body> hebben).
  • Voer pnpm build uit en inspecteer dist/index.html. Het snippet zou in de gebouwde HTML moeten verschijnen.
  • Als u een aangepaste Vite-plugin gebruikt die index.html herschrijft, zorg ervoor dat deze door de gebruiker toegevoegde <script>-tags behoudt.
  • Controleer in het Network-tabblad van de browser het selgeo.js-verzoek — een CORS- of CSP-fout duidt op een configuratieprobleem (zie hieronder).

Klik niet getraceerd​

  • De bezoeker moet aankomen met ?ref=… bij de initiële paginalading. Herladen verwijdert de parameter (het snippet herschrijft de URL bij het vastleggen) — geef een nieuwe trackinglink uit als u de huidige al hebt verbruikt.
  • Bevestig dat data-merchant een geldige pk_test_*- of pk_live_*-sleutel bevat.
  • Als u de useEffect-alternatief gebruikt, bevestig dan dat de document.getElementById-beveiliging aanwezig is en dat SELGEO_SCRIPT_ID uniek is op de pagina.
  • Controleer de dashboardmodus (test vs. live) — een mismatch verwerpt de klik stilzwijgend.

CSP-blokkering​

Als u een Content-Security-Policy instelt via een Vite-plugin, een meta-tag of de origin-server, sta dan de Selgeo-oorsprongen toe:

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

Voeg voor staging- / dev-workspaces waar data-api-url naar een andere oorsprong wijst, die oorsprong ook toe aan connect-src.

Volgende stappen​