Auf React installieren (Vite, CRA, Remix)

Wie du React einrichtest, hängt vom Build-Tool ab. Vite und Create React App liefern eine statische index.html als Einstiegspunkt, in die das Head-Skript kommt. Remix und React Router 7 nutzen Server-Side Rendering mit app/root.tsx als Dokument-Shell. Beide Muster verhalten sich im Client gleich: Die SPA lädt bei einem Routenwechsel nie die ganze Seite neu. Für das Conversion-Tracking spielt das aber keine Rolle, weil Verkäufe außerhalb der Seite erfasst werden (über deinen Zahlungsanbieter oder einen Server-to-Server-Aufruf), nicht über ein Convert-Ereignis im Browser.

Ein Hinweis zu Create React App: Das React-Team hat CRA Anfang 2025 als veraltet markiert. Neue Projekte sollten Vite nutzen (oder Remix / React Router 7 für SSR). Das Installationsmuster für CRA funktioniert weiterhin, wenn du eine bestehende CRA-App hast, aber plane eine Migration ein.

Vite + CRA: in index.html installieren

In der index.html deines Projekts (im Projektstamm bei Vite, public/index.html bei CRA):

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Your App</title>
    <!-- Rekomi tracking -->
    <script async src="https://api.rekomi.com/api/v1/r/loader.js" data-program-id="YOUR_PROGRAM_ID" data-rkmi-email-capture="auto"></script>
    <noscript>
      <img src="https://api.rekomi.com/api/v1/r/c.gif" width="1" height="1" alt="" referrerpolicy="no-referrer-when-downgrade" />
    </noscript>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Vite und CRA lassen ein externes <script src> in index.html beide unverändert, das Tag wird also genau so ausgeliefert, wie es dasteht.

Kopiere das Snippet mit deiner schon eingesetzten Programm-ID aus dem Installationsrezept deiner Kampagne unter Einrichtung > Installieren im Dashboard.

Rekomi erfasst eine E-Mail-Adresse, die ein vermittelter Besucher auf den Seiten, auf denen das Tag läuft, in ein beliebiges E-Mail- oder Textfeld tippt (Registrierung, Login, Checkout und andere Formulare), damit der Verkauf auch dann gutgeschrieben werden kann, wenn dein Checkout keine Empfehlung übergibt. Ohne Empfehlung wird nichts erfasst. Entferne das Attribut data-rkmi-email-capture, um das auszuschalten; explizite Aufrufe von Rekomi.convert() funktionieren weiterhin.

Remix / React Router 7: in app/root.tsx installieren

Remix (seit der Zusammenlegung als React Router 7 benannt) rendert per SSR und hat keine statische index.html. Die Dokument-Shell liegt in app/root.tsx, und du renderst dasselbe Script-Tag direkt im JSX des Heads:

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";

export default function App() {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
        {/* Rekomi tracking */}
        <script
          async
          src="https://api.rekomi.com/api/v1/r/loader.js"
          data-program-id={import.meta.env.VITE_REKOMI_PROGRAM_ID}
          data-rkmi-email-capture="auto"
        />
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Renderst du das <script>-Element direkt (und nicht über <Scripts /> von Remix, das für das gebündelte JavaScript der App gedacht ist), landet genau dieses Tag im serverseitig gerenderten Dokument.

React Router 7 baut mit Vite, deshalb braucht die Umgebungsvariable das Präfix VITE_ (lege VITE_REKOMI_PROGRAM_ID in .env an) und wird über import.meta.env gelesen. Nutze hier nicht process.env: root.tsx wird bei der Hydration im Client erneut gerendert, und dort ist process nicht definiert, das Rendern bricht also mit einem ReferenceError ab. Weil die Programm-ID eine öffentliche Kennung ist, kannst du sie auch fest eintragen.

Den Verkauf erfassen

Das Browser-Pixel erfasst keine Verkäufe mehr, deshalb gibt es keinen Convert-Aufruf, den du aus einem useEffect auslösen müsstest. Ein Verkauf wird über einen dieser Wege erfasst:

• Dein Zahlungsanbieter. Verbinde ihn einmal im Schritt Zahlungsanbieter verbinden unter /dashboard/setup/connect-sales (Stripe, Paddle, Braintree, Shopify, Wix, BigCommerce, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, Dodo Payments oder Mollie), und Verkäufe, Erstattungen und Kündigungen werden automatisch erfasst.
• Server-to-Server. Sende den Verkauf aus deinem Backend per POST mit HMAC-Signatur an den S2S-Endpunkt von Rekomi. Siehe Server-zu-Server-Tracking.
• Gutscheincodes. Gib jedem Affiliate einen eigenen Rabattcode (Kampagne > Gutscheincodes); ein eingelöster Code schreibt ihm den Verkauf im Checkout gut.

Gib die Empfehlung mit window.Rekomi.getReferral() an den Checkout weiter. Erstellt dein eigenes Backend eine Stripe Checkout Session, leite den zurückgegebenen Slug weiter, damit dein Server ihn als rekomi_affiliate_slug in die Metadaten des Abonnements schreiben kann (genau das liest Rekomi für die Attribution):

async function startCheckout(priceId: string) {
  const referral = window.Rekomi?.getReferral?.();
  const res = await fetch("/api/create-checkout-session", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...(referral ? { "x-rekomi-referral": referral } : {}),
    },
    body: JSON.stringify({ priceId }),
  });
  const { url } = await res.json();
  window.location.href = url;
}

Leads erfassen (optional)

window.Rekomi.convert() ist jetzt ein Aufruf zur LEAD-Erfassung, kein Verkauf. Auf einer Anmelde- oder Wartelistenroute kannst du eine Kunden-E-Mail-Adresse vor der Zahlung mit der Empfehlung verknüpfen, damit ein späterer Verkauf trotzdem gutgeschrieben wird:

import { useEffect } from "react";

export function SignupThanks({ email }: { email: string }) {
  useEffect(() => {
    if (email) window.Rekomi?.ready?.(() => window.Rekomi.convert(email));
  }, [email]);

  return <div>Thanks for signing up!</div>;
}

Die Lead-Erfassung im Browser funktioniert in jedem Plan; der serverseitige Lead-Endpunkt erfordert Starter oder höher. Siehe Leads und Anmeldungen tracken.

Client-Navigation mit React Router 6/7

Navigiert ein Nutzer im Client von deinen Marketing-Seiten zu einer Erfolgsroute (ohne das Dokument neu zu laden, nur über <Link> von React Router), bleibt das Head-Skript erhalten: Es wurde beim ersten Laden des Dokuments geladen und bleibt im Speicher des Browsers. Die beim ersten Laden erfasste Empfehlung steht weiterhin über window.Rekomi.getReferral() bereit. Du musst das Skript bei einem Routenwechsel nicht neu einbinden.

Das ist das entscheidende Verhalten von SPAs: einmal installieren und die Empfehlung überall auslesen, wo du sie brauchst.

Umgebungsvariablen in Vite

Bei Vite stellst du die Programm-ID über VITE_REKOMI_PROGRAM_ID bereit (das Präfix VITE_ ist nötig, damit die Variable im Browser verfügbar ist) und setzt sie dann per Ersetzung beim Build oder über die HTML-Transformation %VITE_*% in index.html ein:

<script async src="https://api.rekomi.com/api/v1/r/loader.js" data-program-id="%VITE_REKOMI_PROGRAM_ID%" data-rkmi-email-capture="auto"></script>

Du kannst die Programm-ID auch fest in index.html eintragen, denn sie ist eine öffentliche Kennung (kein Secret).

Umgebungsvariablen in CRA

CRA stellt Variablen mit dem Präfix REACT_APP_ beim Build bereit, und public/index.html unterstützt die Ersetzung %REACT_APP_*%:

<script async src="https://api.rekomi.com/api/v1/r/loader.js" data-program-id="%REACT_APP_REKOMI_PROGRAM_ID%" data-rkmi-email-capture="auto"></script>

Setze REACT_APP_REKOMI_PROGRAM_ID in .env und in der Umgebung deiner CI oder deines Builds.

Gut zu wissen

Eine SPA lädt zwischen Seiten nicht neu. Anders als eine App mit mehreren Seiten navigiert React Router im Client, ohne das Dokument komplett zu laden. Das Head-Skript lädt einmal beim ersten Besuch; spätere Routenwechsel führen es nicht erneut aus. Das ist in Ordnung: Klickerfassung und getReferral() funktionieren beide mit diesem einen ersten Laden.

CRA ist veraltet. Das React-Team hat Create React App Anfang 2025 eingestellt. Vite ist der empfohlene Nachfolger für SPAs. Bist du auf CRA, funktioniert die Installation, aber plane eine Migration ein.

Remix heißt seit 2024 React Router 7. Die Zusammenlegung der Bibliotheken ist abgeschlossen; was du vielleicht als Remix kennst, erscheint jetzt als React Router 7. Das Muster mit app/root.tsx bleibt gleich, nur der Paketname ändert sich (react-router statt @remix-run/react).

Strict Mode führt Effects in der Entwicklung zweimal aus. <StrictMode> von React ruft useEffect in der Entwicklung zweimal auf, um Fehler sichtbar zu machen. Ein Lead-convert() in einem Effect kann lokal also zweimal ausgelöst werden. Rekomi dedupliziert Leads pro Affiliate und E-Mail-Adresse, der zweite Aufruf bewirkt also nichts, und in Produktions-Builds passiert das gar nicht.

Fehlerbehebung

window.Rekomi ist beim ersten Rendern undefined. Das Skript lädt async, in langsamen Netzen ist es also womöglich noch nicht fertig, wenn deine Komponente gemountet wird. Nutze window.Rekomi?.ready?.(cb), um zu warten, bis der Loader bereit ist, oder sichere den Aufruf mit if (window.Rekomi) ab.

Der Vite-Build enthält das Script-Tag nicht. Ein externes <script src> lässt Vite unverändert; nur Inline-Skripte ohne Modul werden entfernt. Nutze das oben gezeigte Tag mit externem src statt eines Inline-Blocks.

root.tsx in Remix rendert das Skript doppelt. Wahrscheinlich steht es sowohl im JSX des Heads als auch in einem <Scripts />-Block. Rendere es einmal über das JSX des Heads, nicht über <Scripts /> von Remix (das ist für das gebündelte JavaScript der App gedacht).

Die Empfehlung ist erfasst, aber der Verkauf wird nicht zugeordnet. Die Empfehlung ist nicht im Checkout angekommen. Gib window.Rekomi.getReferral() an deinen Endpunkt zum Erstellen der Session weiter und setze sie als subscription_data.metadata.rekomi_affiliate_slug, oder schick sie in deinem S2S-Aufruf mit.

Verwandte Seiten

• Tracking-Skript und Referenz zu window.Rekomi
• Server-zu-Server-Tracking: Verkäufe aus deinem Backend erfassen
• Auf Vue installieren: das Gegenstück für Vue