Zum Hauptinhalt springen

Snippet-Setup

Diese Seite ist die HTML- / einfache-Script-Installationsanleitung für das Selgeo-Tracking-Snippet (selgeo.js) — eine leichtgewichtige JavaScript-Datei, die auf Ihrer Website läuft, Partner-Empfehlungsklicks registriert und Attributionsdaten im Browser des Besuchers für die spätere Konversionsübereinstimmung speichert. Verwenden Sie diese Anleitung, wenn Sie das rohe HTML Ihrer Website direkt kontrollieren (statische Seiten, Webflow, Shopify Liquid, eigene servergerenderte Seiten oder ein Tag-Manager).

Verwenden Sie ein Framework?
  • Next.js — siehe die Next.js-Anleitung für das next/script-Komponentenmuster.
  • React (Vite) — siehe die React-(Vite)-Anleitung für die Platzierung in index.html und den useEffect-Fallback.
  • WordPress — siehe die WordPress-Anleitung für Platzierung über Site Editor, footer.php und Header-Footer-Plugins.

API-Version: v1

Grundinstallation​

Fügen Sie das folgende <script>-Tag zu jeder Seite Ihrer Website hinzu, kurz vor dem schließenden </body>-Tag:

<script
  async
  src="https://cdn.selgeo.com/v1/selgeo.js"
  data-merchant="pk_test_YOUR_KEY"
></script>

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

Erforderliche Attribute​

AttributBeschreibung
srcCDN-URL für das Snippet. Verwenden Sie immer https://cdn.selgeo.com/v1/selgeo.js.
data-merchantIhr öffentlicher API-Schlüssel (pk_test_* für den Testmodus, pk_live_* für den Live-Modus).
asyncLädt das Snippet asynchron, damit das Seitenrendering nicht blockiert wird.

Optionale Attribute​

AttributBeschreibung
data-debugAktiviert Debug-Logging in der Browser-Konsole. Vor dem Go-Live entfernen.
data-api-urlÜberschreibt die API-Endpunkt-URL. Nur für erweiterter Gebrauch (z. B. benutzerdefinierter Proxy).

Funktionsweise​

Wenn ein Besucher Ihre Website mit einem ?ref=-Parameter in der URL aufruft (z. B. https://ihre-website.com/pricing?ref=abc123), führt das Snippet folgende Schritte aus:

  1. Erkennt den ref-Query-Parameter.
  2. Registriert den Klick bei der Selgeo-API mit Ihrem öffentlichen Schlüssel.
  3. Speichert die click_id, die von der API zurückgegeben wird, im sessionStorage des Browsers.
  4. Entfernt ?ref= aus der URL mittels history.replaceState, um URLs sauber zu halten.
  5. Schreibt Stripe Payment Links auf der Seite um, um client_reference_id=CLICK_ID einzufügen.

Wenn kein ?ref=-Parameter vorhanden ist, tut das Snippet nichts. Es hat keinerlei Overhead auf Seiten, auf denen keine Empfehlung stattfindet.

Speichermechanismus​

Das Snippet speichert Attributionsdaten in sessionStorage, nicht in Cookies:

SchlüsselWertLebensdauer
__selgeo_cidDie click_id (UUID)Bis der Browser-Tab geschlossen wird
__selgeo_vtkEin Besuchertoken (UUID)Bis der Browser-Tab geschlossen wird

Datenschutzimplikationen:

  • sessionStorage ist tab-begrenzt – es wird nicht über Tabs oder Fenster hinweg geteilt.
  • Daten werden automatisch gelöscht, wenn der Tab geschlossen wird.
  • Es werden keine Cookies gesetzt. Für das Selgeo-Tracking ist kein Cookie-Einwilligungsbanner erforderlich.
  • Das Snippet sendet keine Daten an Selgeo, wenn kein ?ref=-Parameter vorhanden ist.

Lesen der Klick-ID​

Ihr Frontend-Code kann die gespeicherte click_id jederzeit lesen:

const clickId = __selgeo.getClickId();
// Gibt einen UUID-String zurück (z. B. "f47ac10b-58cc-4372-a567-0e02b2c3d479")
// Gibt null zurück, wenn kein Empfehlungsklick in dieser Sitzung aufgezeichnet wurde

Dies ist nützlich, wenn Sie die click_id an Ihr Backend übergeben müssen – zum Beispiel beim Erstellen einer Stripe Checkout Session oder beim Aufrufen der Conversion API.

Verfügbare Methoden​

MethodeRückgabewertBeschreibung
__selgeo.getClickId()string | nullDie aktuelle Klick-ID, oder null wenn keine vorhanden
__selgeo.getVisitorToken()string | nullDas aktuelle Besuchertoken, oder null
__selgeo.checkUrl()voidÜberprüft manuell die aktuelle URL auf einen ?ref=-Parameter

Single-Page-Anwendungen (SPAs)​

Das Snippet überwacht URL-Änderungen in Single-Page-Anwendungen automatisch. Es lauscht auf:

  • popstate-Ereignisse (Browser Vor-/Zurücknavigation)
  • history.pushState- und history.replaceState-Aufrufe (programmatische Navigation)

Wenn sich die URL ändert und einen neuen ?ref=-Parameter enthält, erfasst das Snippet den Klick automatisch. Für React, Vue, Angular oder andere SPA-Frameworks ist keine zusätzliche Konfiguration erforderlich.

Wenn Sie URLs mit ?ref=-Parametern dynamisch erstellen und programmatisch navigieren, erkennt das Snippet die Änderung automatisch.

Manuelle URL-Überprüfung​

In seltenen Fällen, in denen die automatische Erkennung nicht ausgelöst wird (z. B. wenn der ?ref=-Parameter nach dem Seitenaufruf über JavaScript ohne history.pushState hinzugefügt wird), können Sie das Snippet manuell zur erneuten Überprüfung auffordern:

__selgeo.checkUrl();

Wenn Ihre Seite Links zu Stripe Payment Links (https://buy.stripe.com/...) enthält, hängt das Snippet automatisch ?client_reference_id=CLICK_ID an, wenn ein Empfehlungsklick aktiv ist.

<!-- Vor dem Snippet -->
<a href="https://buy.stripe.com/test_abc123">Abonnieren</a>

<!-- Nach dem Snippet (wenn eine click_id gespeichert ist) -->
<a href="https://buy.stripe.com/test_abc123?client_reference_id=CLICK_ID">Abonnieren</a>

Das Snippet überwacht auch dynamisch hinzugefügte Payment Links (via MutationObserver) und schreibt sie um, sobald sie erscheinen. Dies funktioniert mit SPAs und lazy geladenem Inhalt.

Schutz vor Händler-Überschreibung: Wenn Sie selbst client_reference_id auf einem Payment Link setzen, überschreibt das Snippet Ihren Wert nicht. Ihr expliziter Wert hat immer Priorität.

Eine detaillierte Anleitung finden Sie unter Stripe Payment Links.

Tag-Manager-Installation​

Wenn Sie Google Tag Manager (GTM) oder einen anderen Tag-Manager verwenden, fügen Sie das Snippet als benutzerdefiniertes HTML-Tag hinzu:

  1. Erstellen Sie in GTM ein neues Custom HTML-Tag.
  2. Fügen Sie das Script-Tag ein: 
    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
    ></script>
  3. Setzen Sie den Trigger auf All Pages.
  4. Veröffentlichen Sie den Container.
Timing beim Tag-Manager

Bei Verwendung eines Tag-Managers kann das Snippet etwas später laden als ein direktes <script>-Tag. Dies ist für die meisten Anwendungsfälle in Ordnung. Wenn Sie die click_id jedoch sofort beim Seitenaufruf benötigen (z. B. um sie an ein server-gerendertes Checkout-Formular zu übergeben), fügen Sie das Snippet direkt in Ihr HTML ein.

Platzierungsempfehlungen​

SzenarioEmpfehlung
Standard-WebsiteFügen Sie es über das globale Layout/Template zu jeder Seite hinzu
SPA (React, Vue, etc.)Einmalig zu index.html hinzufügen – Snippet verwaltet Routenänderungen
Nur LandingpagesNur zu Seiten hinzufügen, auf denen Partner-Traffic landet
Nur Checkout-SeiteNicht empfohlen – das Snippet muss auf der Landingpage sein, um den ?ref=-Parameter zu erfassen
Das Snippet muss auf der Landingpage sein

Der ?ref=-Parameter ist nur in der ursprünglichen URL vorhanden, wenn der Besucher auf einen Partner-Link klickt. Wenn das Snippet auf dieser Seite nicht geladen ist, wird der Klick nicht aufgezeichnet und die click_id steht für die spätere Konversions-Attribution nicht zur Verfügung.

Installation überprüfen​

  1. data-debug hinzufügen zum Script-Tag vorübergehend.
  2. Besuchen Sie Ihre Website mit einem Test-Tracking-Link: https://ihre-website.com/?ref=IHR_TEST_REF
  3. Öffnen Sie die Developer Tools (F12) und prüfen Sie die Konsole auf: 
    [selgeo] ref detected IHR_TEST_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  4. Prüfen Sie sessionStorage im Anwendungs-Tab (Chrome) oder Speicher-Tab (Firefox):
    • __selgeo_cid sollte eine UUID enthalten
    • __selgeo_vtk sollte eine UUID enthalten
  5. Rufen Sie die API in der Konsole auf: 
    __selgeo.getClickId()  // Sollte einen UUID-String zurückgeben
  6. Prüfen Sie das Dashboard – der Klick sollte innerhalb von Sekunden in Analytics erscheinen.

Fehlerbehebung​

Snippet lädt nicht​

  • Überprüfen Sie, ob die src-URL genau https://cdn.selgeo.com/v1/selgeo.js lautet.
  • Prüfen Sie auf Content Security Policy (CSP)-Header, die das Skript blockieren könnten. Fügen Sie cdn.selgeo.com zu Ihrer script-src-Direktive hinzu.
  • Prüfen Sie auf Ad-Blocker, die das Skript blockieren könnten.

click_id ist null​

  • Der Besucher muss mit einem ?ref=-Parameter in der URL ankommen. Direkte Besuche erstellen keine click_id.
  • Prüfen Sie, ob data-merchant einen gültigen öffentlichen Schlüssel enthält (pk_test_* oder pk_live_*).
  • Überprüfen Sie, ob der ref-Wert einem aktiven Tracking-Link in Ihrem Programm entspricht.
  • Der Link-href muss mit https://buy.stripe.com beginnen. Relative URLs oder proxied URLs werden nicht erkannt.
  • Die Umschreibung findet nur statt, wenn eine click_id gespeichert ist. Besuchen Sie die Seite zuerst über einen Tracking-Link.
  • Wenn Sie client_reference_id selbst setzen, überschreibt das Snippet es nicht.

Performance​

Das Snippet ist so konzipiert, dass es minimalen Einfluss auf Ihre Website hat:

MetrikWert
Bundle-Größe< 5 KB gzipped
Initialisierungszeit< 50 ms
Netzwerkanfragen0 (keine Empfehlung) oder 1 (Empfehlungsklick-Registrierung)
Gesetzte CookiesKeine
DOM-ModifikationenKeine (außer URL-Bereinigung via history.replaceState)

Das Snippet läuft vollständig in einem IIFE (Immediately Invoked Function Expression) und verschmutzt den globalen Scope nicht über das __selgeo-API-Objekt hinaus.

Nächste Schritte​