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 (
eventundtag, 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
| Arg | Typ | Beschreibung |
|---|---|---|
granted | boolean | true 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
| Arg | Typ | Beschreibung |
|---|---|---|
name | string | Ereignisname. Leere Namen werden verworfen, längere als 128 Zeichen gekürzt. |
props | object (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; nutzevalue_numfü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
| Arg | Typ | Beschreibung |
|---|---|---|
name | string | Tag-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
| Arg | Typ | Beschreibung |
|---|---|---|
user | string | object | Ein 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
identifynach 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: