Skip to Content
API-ReferenzJavaScript-API

JavaScript-API Verfügbar (v1)

Sobald das Tracking-Snippet geladen ist, stellt es eine einzige globale Funktion bereit, visz(...), als Command-Queue. Du rufst sie mit einem Command-Namen und Argumenten auf:

visz("event", "add_to_cart", { sku: "SHOE-42", value_num: 49.9 });

Das Snippet übernimmt Batching, Transport, Consent und PII-Maskierung für dich. Für die meisten Integrationen ist das die richtige Schnittstelle; die REST-API rufst du fast nie direkt auf. Die Commands sind consent, event, tag, identify und shutdown.

Wie die Queue funktioniert

Das Snippet wird mit async geladen. Bis es da ist, gibt es visz noch nicht. Willst du visz(...) schon vorher aufrufen, zum Beispiel oberhalb des Snippet-<script>-Tags, legst du zuerst einen kleinen Puffer an:

window.visz = window.visz || function () { (window.visz.q = window.visz.q || []).push(arguments); };

Beim Start liest das Snippet alle Aufrufe aus visz.q und führt sie der Reihe nach aus.

Consent-Gate. Vor der Einwilligung des Besuchers wird nichts gesendet. Aufrufe von visz('event' | 'tag') vor dem Consent werden stillschweigend verworfen (nicht für später gepuffert). visz('consent', true) öffnet das Gate.

Frequency-Cap. Eigene Ereignisse (event und tag, dazu die im Dashboard ohne Code angelegten) teilen sich ein Limit von 100 Ereignissen je Sitzung und Tag. Darüber hinaus werden weitere Ereignisse stillschweigend verworfen. Das ist eine Kostenkontroll-Schranke, kein Fehler.


visz('consent', granted)

Tracking-Consent erteilen oder widerrufen. Ob du diesen Aufruf brauchst, hängt von der Consent-Einstellung deiner Website ab. Mit Auf Einwilligung warten wird nichts getrackt, bis Consent vorliegt: bis du visz('consent', true) aufrufst, der Besucher im Cookie-Banner von visz.ai zustimmt oder Google Consent Mode v2 analytics_storage freigibt. Mit Keine Einwilligung nötig startet das Tracking ohne diesen Aufruf. Einzelheiten stehen im Consent-Setup.

Parameter

ArgTypBeschreibung
grantedbooleantrue erteilt Consent und startet das Tracking; false widerruft ihn: das Snippet meldet den Widerruf ein letztes Mal, sendet ausstehende Ereignisse und stoppt jede Erfassung.

Beispiel

// In your cookie-banner "Accept" handler: visz("consent", true); // In your "Reject" / withdraw handler: visz("consent", false);

„Do Not Track“ hat Vorrang: Sendet der Browser DNT, bleibt das Snippet unabhängig von diesem Aufruf inaktiv. Das ändert sich nur, wenn deine Seite vor dem Snippet ausdrücklich window.viszConfig = { dntOverride: true } setzt.


visz('event', name, props?)

Ein eigenes Ereignis aufzeichnen, also ein benanntes Ereignis wie add_to_cart, signup_completed oder video_played. Kennt visz.ai den Namen noch nicht, legt es das Ereignis beim ersten Eintreffen an; es erscheint dann unter Ereignisse & Tags im Dashboard.

Parameter

ArgTypBeschreibung
namestringEreignisname. Leere Namen werden verworfen, längere als 128 Zeichen gekürzt.
propsobject (optional)Bis zu 10 Eigenschaften. value_num wird als unmaskierter numerischer Wert übernommen; Zahlen und Wahrheitswerte bleiben unverändert; jeder String-Wert wird im Browser PII-maskiert und auf 200 Zeichen gekürzt.

Beispiel

visz("event", "add_to_cart", { sku: "SHOE-42", // masked + truncated category: "sneakers", // masked + truncated value_num: 49.9 // kept as a raw number (e.g. for revenue) });

PII-Schutz. Eigenschaften werden im Browser maskiert, bevor irgendetwas gesendet wird, und auf dem Server noch einmal. Lange, zufällig wirkende Werte ersetzt der Server durch einen Platzhalter. Trotzdem: Übergib niemals rohe PII (E-Mails, Namen, Kartennummern) in props; nutze value_num für Beträge und stabile, nicht identifizierende Labels für alles andere.


visz('tag', name)

Sendet ein Ereignis mit einem reservierten Merkmal, das es als Tag kennzeichnet.

Parameter

ArgTypBeschreibung
namestringTag-Name. Leere Namen werden verworfen, längere als 128 Zeichen gekürzt.

Beispiel

visz("tag", "vip");

Im Dashboard erscheint ein so gesendetes Tag als Ereignis mit diesem Namen unter Ereignisse & Tags, nicht im Bereich Tags. Du filterst Aufnahmen danach über Ereignis ausgelöst. Tags im Bereich Tags setzt eine automatische Regel, siehe Custom Events & Tags. Ein Tag zählt gegen dasselbe Limit von 100 Ereignissen.


visz('identify', user)

Hängt eine pseudonyme Nutzerkennung an die folgenden eigenen Ereignisse der aktuellen Seite.

Parameter

ArgTypBeschreibung
userstring | objectEin stabiler Identifier, als String oder als Objekt mit id, user_id, userId oder email. Es wird nur ein client-seitiger FNV-1a-Hash davon berechnet und nachfolgenden eigenen Ereignissen als metadata.uid angehängt. Der Rohwert verlässt den Browser nie.

Beispiel

visz("identify", "user_8f31c2");

Pseudonym, keine Verschlüsselung. visz.ai erhält nie den rohen Identifier, nur den Hash. Der Hash ist kurz und nicht kryptografisch: Wer die möglichen Ausgangswerte kennt, kann ihn nachrechnen. Übergib deshalb eine interne Kennung statt einer E-Mail-Adresse. Die Kennung gilt nur für die aktuelle Seite; rufe identify nach jedem Seitenaufruf erneut auf.


visz('shutdown')

Stoppt sofort jedes Tracking für die aktuelle Seite: löst alle Capture-Listener, stoppt Aufnahme, Umfrage- und Feedback-Widgets und das Cookie-Banner und sendet ausstehende Ereignisse. Anders als visz('consent', false) meldet shutdown keinen Widerruf.

Beispiel

visz("shutdown");

Zuletzt aktualisiert: