Diese Anleitung beschreibt die Installation und Verwendung des SurveyAnalytica Clickstream SDK in Webprojekten. Das SDK wird auf npm veröffentlicht und funktioniert in jeder JavaScript-Umgebung, einschließlich Vanilla JS, Next.js und React. Für mobile Apps siehe die Mobile-SDKs-Anleitung.

Bevor Sie beginnen, führen Sie die Workflow-Einrichtung durch, um Ihren API-Schlüssel und Ihre Endpoint-URL zu erhalten.

Installation

Vanilla JS / HTML-Websites

Binden Sie das UMD-Bundle direkt in Ihre Seite ein. Kein Build-Schritt erforderlich.

<script src="https://cdn.jsdelivr.net/npm/@surveyanalytica/clickstream-web/dist/index.umd.js"></script>
<script>
  SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
    endpoint: 'YOUR_ENDPOINT_URL'
  });
</script>

npm-Projekte (Next.js, React usw.)

npm install @surveyanalytica/clickstream-web

Initialisieren Sie das SDK anschließend einmalig am Einstiegspunkt Ihrer App:

import { SAClickstream } from '@surveyanalytica/clickstream-web';

SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
  endpoint: 'YOUR_ENDPOINT_URL'
});

Rufen Sie bei Next.js init innerhalb einer Client Component oder in _app.js / layout.js auf. Das SDK ist sicher für Server-Side Rendering — jeder Zugriff auf Browser-APIs wird intern abgesichert.

Seitenaufrufe verfolgen

Das SDK verfolgt Seitenaufrufe automatisch. Jedes Mal, wenn sich die URL ändert (auch bei Single-Page-Navigation über die History API), wird ein page_view-Ereignis mit der aktuellen URL, dem Seitentitel und dem Referrer gesendet. Über den init-Aufruf hinaus ist kein weiterer Code erforderlich.

So senden Sie einen Seitenaufruf manuell:

SAClickstream.page('/checkout', { campaign: 'summer-sale' });

Benutzerdefinierte Ereignisse verfolgen

SAClickstream.track('button_clicked', {
  label: 'Buy Now',
  productId: 'sku-9821',
  price: 49.99
});

Eigenschaftswerte können Zeichenketten, Zahlen, boolesche Werte oder verschachtelte Objekte sein. Halten Sie Ereignisnamen kurz und über Ihre gesamte Codebasis hinweg konsistent (verwenden Sie beispielsweise stets button_clicked, statt buttonClick und btn_tap zu mischen).

Benutzer nach der Anmeldung identifizieren

Vor der Anmeldung weist das SDK jedem Besucher eine zufällige anonyme ID zu, die in localStorage gespeichert wird. Rufen Sie nach der Anmeldung identify mit der Kontakt-ID aus Ihrem Backend auf:

// After a successful login
SAClickstream.identify('contact-id-from-your-backend');

Dies sendet ein uid_transition-Ereignis, das die anonyme Sitzung mit dem bekannten Kontakt verknüpft. Ereignisse, die vor der Anmeldung erfasst wurden, werden über die im Kontaktdatensatz gespeicherte anonyme ID dem Kontakt zugeordnet — es gehen keine Daten verloren.

Einwilligungsverwaltung

Wenn Ihre Website ein Cookie-Einwilligungsbanner verwendet, respektieren Sie die Wahl des Nutzers’:

// User accepted tracking
SAClickstream.setConsent(true);

// User declined tracking
SAClickstream.setConsent(false);

Wenn die Einwilligung auf false gesetzt wird, stoppt das Tracking sofort und die Verknüpfung mit der anonymen ID wird gelöscht. Es werden keine weiteren Ereignisse gesendet, bis die Einwilligung erneut erteilt wird.

Wie Ereignisse gesendet werden

Das SDK bündelt Ereignisse und sendet sie alle 500 Millisekunden oder sofort, sobald sich 20 Ereignisse angesammelt haben. Fehlgeschlagene Anfragen werden bis zu dreimal mit zunehmenden Verzögerungen wiederholt. Dies hält die Netzwerknutzung gering, ohne bei vorübergehenden Verbindungsproblemen Ereignisse zu verlieren.

Fehlerbehebung

Ereignisse erscheinen nicht in meinem Workflow

• Bestätigen Sie, dass sich der Workflow im Status Active befindet.
• Prüfen Sie die Browser-Konsole auf Netzwerkfehler bei Anfragen an Ihre Endpoint-URL.
• Überprüfen Sie, ob der API-Schlüssel mit dem im Trigger-Bereich angezeigten KEY übereinstimmt — kopieren Sie ihn, statt ihn einzutippen.
• Stellen Sie sicher, dass init vor jedem track– oder page-Aufruf aufgerufen wird.

Doppelte Seitenaufrufe werden erfasst

Wenn Sie SAClickstream.page() zusätzlich zum automatischen Tracking manuell aufrufen, sehen Sie zwei Ereignisse pro Navigation. Deaktivieren Sie entweder das automatische Tracking (autoPage: false in den Init-Optionen) oder entfernen Sie Ihre manuellen page()-Aufrufe.