Dokumentation für Entwickler

Schnellstart

1. Legen Sie im Portal (auf Englisch) eine Website mit dem Origin Ihres Webauftritts an, etwa https://www.example.com.
2. Veröffentlichen Sie den DNS-TXT-Eintrag, den das Portal anzeigt, und wählen Sie dann "Verify". Die Verifizierung fragt die eigenen Nameserver Ihrer Domain ab und gelingt daher, sobald der Eintrag veröffentlicht ist.
3. Schalten Sie die Aufzeichnung im Tab "Settings" der Website ein.
4. Fügen Sie das Installations-Snippet aus dem Tab "Installation" in jede Seite ein. Um die Aufzeichnung eines Besuchers zu beenden, rufen Sie die Opt-out-Funktion aus Ihrem Einwilligungsbanner oder über einen Link auf.

Sitzungen erscheinen im Portal im Tab "Sessions" der Website wenige Sekunden nach einem Besuch, mit ihren Aufzeichnungen darin.

Installation, Opt-out und Einwilligung

Kopieren Sie das Snippet aus dem Tab "Installation" der Website und fügen Sie es einmal ein: Es lädt immer das neueste Release, Sie müssen es also nie ändern, um eines zu bekommen. Es enthält den öffentlichen Schlüssel Ihrer Website.

<script async
  src="https://analytics.ironfang.com/sdk/loader.js"
  crossorigin="anonymous"
  referrerpolicy="no-referrer"
  data-site-key="ifa_site_..."
></script>

Das Snippet zeichnet ab dem ersten Seitenaufruf auf, und eine Aufzeichnung wird behalten, sobald der Besucher mit der Seite interagiert: Für einen Besucher, der das nie tut, wird nichts gesendet, Crawler werden nie aufgezeichnet, und ein Besuch unter fünf Sekunden wird weder behalten noch gezählt. Um einen Besucher von der Aufzeichnung auszunehmen, rufen Sie Folgendes aus Ihrem Einwilligungsbanner oder über einen Link auf, vor oder nach dem Laden des Snippets. Die Aufzeichnung endet, alles noch nicht Gesendete wird im Browser verworfen, und der Browser merkt sich die Entscheidung, sodass auch spätere Seiten nicht aufzeichnen:

window.ironfangAnalytics = window.ironfangAnalytics || [];
ironfangAnalytics.push(['setConsent', { replay: false }]);

Ändert der Besucher seine Meinung, startet setConsent({ replay: true }) die Aufzeichnung erneut.

Wo das Recht eine Einwilligung vor der Aufzeichnung verlangt, wie es für Besucher im Vereinigten Königreich und in der EU in der Regel der Fall ist, schalten Sie im Tab "Settings" der Website Ask for consent first ein. Das Snippet, das Ihnen der Tab "Installation" dann gibt, enthält data-consent="required": Es stellt keine Anfrage und zeichnet nichts auf, bis Ihre Seite setConsent({ replay: true }) aufruft, sobald der Besucher zustimmt. Ob Ihre Besucher gefragt werden müssen, müssen Sie selbst beurteilen.

Ab Version 0.6.0 verfolgt das Snippet außerdem jeden Besuch als Sitzung (siehe Sitzungen). Sitzungen sind die Grundlage: Eine Aufzeichnung gehört zu ihrer Sitzung, daher wird ein Besucher ab Version 0.6.1 nur aufgezeichnet, solange seine Sitzung verfolgt wird. Sitzungen folgen derselben Einwilligung wie die Aufzeichnung: Wo die Website aufzeichnet, sofern der Besucher nicht widerspricht, wird eine Sitzung verfolgt, solange er nicht widerspricht; wo die Website zuerst fragt, beginnt sie, sobald Ihre Seite eines von beiden erlaubt. setConsent({ analytics: false }) lehnt Sitzungen ab und damit auch die Aufzeichnung; setConsent({ analytics: true, replay: false }) verfolgt Sitzungen, ohne den Besucher aufzuzeichnen.

Eine Seite, die überhaupt nicht verfolgt werden darf, etwa eine, in die Besucher ihre eigenen Dokumente einfügen, ruft beim Öffnen pauseSession() auf (ab Version 0.6.1): Die vorherige Seite endet, und weder ihre Adresse noch etwas auf ihr wird gemeldet oder aufgezeichnet. resumeSession() auf der nächsten Seite verfolgt den Besuch wieder und zeichnet ihn wieder auf. Die Sitzung läuft dazwischen weiter, und die Entscheidungen des Besuchers bleiben unberührt.

Um einen Moment des Besuchs zu markieren, etwa eine begonnene Registrierung oder einen Schritt im Checkout, erfassen Sie ihn, während die Sitzung verfolgt wird: Er erscheint in der Zeitleiste der Sitzung. Ein Name hat bis zu 64 Buchstaben, Ziffern, Leerzeichen und _ . : / -; dazu gehören bis zu zehn Eigenschaften, jede mit einem kleingeschriebenen Namen und einem Text von bis zu 128 Zeichen, einer Zahl oder true oder false. Alles andere wird verworfen. Senden Sie nichts, was den Besucher identifiziert.

ironfangAnalytics.push(['track', 'checkout started', { plan: 'pro', seats: 5 }]);

Ein Besuch über mehrere Seiten im selben Tab setzt eine einzige Aufzeichnung fort. Sobald eine Aufzeichnung beginnt, speichert der Browser außerdem eine zufällige Besucher-ID im Local Storage und sendet sie mit jeder neuen Aufzeichnung, sodass ein zweiter Tab oder ein erneuter Besuch neben dem ersten zu finden ist. Sie wird aus keinerlei Angaben über den Besucher gebildet, sie ist kein Cookie, und ein Opt-out löscht sie.

Wenn Ihre Website eine Content Security Policy verwendet, erlauben Sie https://analytics.ironfang.com in script-src und connect-src.

Was aufgezeichnet wird

Die Seite, wie sie angezeigt wurde, und das Scrollen, die Zeigerbewegungen, Klicks und Seitenwechsel darauf. Die Maskierung geschieht im Browser des Besuchers, bevor irgendetwas gesendet wird:

• Alles, was wie eine Zahlungskartennummer aussieht, wird maskiert, wo immer es erscheint: im Seitentext, in einem Feld oder in einem Attribut. Das ist immer eingeschaltet.
• Felder für Kartennummer, CVV, Passwort und Einmalcode werden blockiert: Sie erscheinen als leere Kästen derselben Größe. Auch das ist immer eingeschaltet.
• Mit eingeschaltetem Mask form fields wird der Wert jedes Feldes durch Platzhalter ersetzt, ebenso Text, der in einen bearbeitbaren Bereich (contenteditable) eingegeben wird. Für eine neue Website ist diese Einstellung ausgeschaltet.
• Mit eingeschaltetem Mask all text wird auch der Seitentext maskiert; nennen Sie Selektoren, deren Text angezeigt werden darf. Für eine neue Website ist diese Einstellung ausgeschaltet.
• In Bereichen, auf die Ihre Selektoren zum dauerhaften Maskieren passen, werden Text und Felder in jedem Fall maskiert.
• Bereiche, auf die Ihre Block-Selektoren passen oder die die Klasse rr-block tragen, werden nie aufgezeichnet.
• Aufgezeichnete URLs behalten nie ein Fragment. Sie behalten nur die Query-Parameter, die Sie auflisten, etwa utm_source, oder, mit eingeschaltetem Record all query parameters, jeden Parameter außer denen, die Sie zum Entfernen auflisten, etwa token.

Um Ihre eigenen Besuche aus Ihren Aufzeichnungen herauszuhalten, tragen Sie Ihre Adressen von zu Hause oder aus dem Büro in den Erfassungseinstellungen der Website unter Excluded visitors ein: einzelne Adressen oder Bereiche wie 203.0.113.0/24, oder für IPv6 das /64 eines Netzwerks. Ein Besuch von einer dieser Adressen wird überhaupt nicht aufgezeichnet, und die Einstellungsseite kann die Adresse des Geräts hinzufügen, das Sie gerade verwenden.

Eine Sitzung speichert die Adresse jeder Seite, nach denselben Query-Regeln, wann sie geöffnet wurde und wie lange sie sichtbar war, wann der Tab verborgen und wieder gezeigt wurde, und die Ereignisse, die Ihre Seite erfasst. Ihre Diagnosen sind jeweils ein eigener Schalter. Errors speichert nicht abgefangene Fehler und nicht behandelte Rejections: ihren Namen, eine Meldung ohne E-Mail-Adressen, Kartennummern und lange Zahlen, die Adresse und Zeile des Skripts und den Stack, gekürzt auf 12 Frames, deren Adressen ihre Query verlieren. Console errors speichert, was Ihre Seite an console.error übergibt, sicher ausgeschrieben und genauso bereinigt. Failed and slow requests speichert Anfragen, die mit 400 oder höher antworten, keine Antwort erhalten, in ein Timeout laufen oder abgebrochen werden, Ressourcen, die nicht laden, und alles, was 5 Sekunden oder länger dauert; Successful requests speichert die übrigen, oder den Anteil, den Sie wählen. Eine Anfrage behält Methode, Adresse, Ergebnis, Status, wo der Browser einen liefert, und Dauer, und ein Query-Wert, der wie Zugangsdaten benannt ist, etwa ein Token oder eine Signatur, wird ersetzt. Inhalte, Header und Cookies von Anfragen und Antworten werden nie gelesen, und dem Inhalt der Seite wird nichts entnommen.

Neben jeder Aufzeichnung speichert Ironfang die IP-Adresse des Besuchers und ob Cloudflare sie gemeldet hat, den vollständigen User-Agent, Fenster- und Bildschirmgröße, Pixelverhältnis, Sprache, Zeitzone, Land, die Seite, von der er kam, ohne deren Query, und die Besucher-ID des Browsers. All das wird mit der Aufzeichnung gelöscht, und eine Sitzung behält dieselben Details so lange wie ihre Aufzeichnungen. Ihre Datenschutzhinweise sollten angeben, dass Sie Sitzungen aufzeichnen und diese Details speichern und dass der Browser eine Besucher-ID speichert.

Websites und Origins

Eine Website steht hier für einen Webauftritt: die Origins, von denen ihr Recorder senden darf, einen öffentlichen Erfassungsschlüssel und das, was sie erfasst. Ein öffentlicher Origin muss verifiziert sein, bevor er aufzeichnet: Veröffentlichen Sie _ironfang-analytics.<host> als TXT-Eintrag mit dem Wert, den das Portal anzeigt. Loopback-Origins wie http://localhost:3000 brauchen für die Entwicklung keinen Eintrag.

Der öffentliche Schlüssel darf veröffentlicht werden: Er kann nur darum bitten, für seine eigene Website aufzuzeichnen. Nach einer Rotation funktioniert der alte Schlüssel noch 24 Stunden weiter, damit zwischengespeicherte Seiten weiter aufzeichnen.

Sitzungen

Eine Sitzung ist ein Besuch: ein Browser auf Ihrer Website, über alle Tabs, die er öffnet, von seiner ersten Seite, bis 30 Minuten vergehen, ohne dass der Besucher etwas tut, oder 12 Stunden nach ihrem Beginn. Ihre Seiten, Tab-Aktivität, Fehler, Anfragen und erfassten Ereignisse gehören zu ihr, ebenso die Aufzeichnungen ihrer Tabs.

Mit eingeschaltetem Follow every visit im Tab "Settings" der Website wird eine Sitzung ab der ersten Seite gemeldet, ob der Besuch aufgezeichnet wird oder nicht: Ein Besucher, der nie interagiert, ein Besuch über Ihr Kontingent hinaus und eine Website mit ausgeschalteter Aufzeichnung haben trotzdem ihren Seitenverlauf. Die Aufzeichnung setzt sie voraus: Eine Aufzeichnung gehört zu ihrer Sitzung, daher schaltet das Ausschalten dieser Einstellung auch die Aufzeichnung aus, und die API lehnt eine Aufzeichnung ohne sie ab. Eine neue Website hat sie eingeschaltet, zusammen mit Errors und Failed and slow requests; eine vor Version 0.6.0 angelegte Website, die aufzeichnet, verfolgt Sitzungen bereits und schaltet unter Settings Errors und Failed and slow requests ein und stellt ihr Snippet auf die aktuelle Version um.

Der Tab "Sessions" der Website listet Sitzungen nach Beginn, Dauer, Einstiegsseite, Seiten und Ereignissen, Fehlern und fehlgeschlagenen Anfragen, was sich abspielen lässt und ob der Besucher gerade auf der Website ist, mit Filtern für jedes davon. Eine Sitzung öffnet sich mit ihrem Seitenverlauf: ihre Seiten der Reihe nach, mit dem Tab, in dem jede war, und wie lange sie sichtbar war, jede mit diesem Moment der Wiedergabe verknüpft, wenn sie aufgezeichnet wurde. Ihre Ereignisse sind nach Seite gruppiert und nach Art filterbar; ihre Ansicht Network listet ihre Anfragen mit ihrem Ergebnis und ihre Ansicht Errors ihre Fehler, jeden einmal pro Seite mit der Zahl seiner Wiederholungen, beide filterbar und mit diesem Moment der Wiedergabe verknüpft; ihre Aufzeichnungen spielen an Ort und Stelle ab, und ihre Heatmap zeigt die eigenen Klicks und das Scrollen der Sitzung auf jeder Seite, die sie aufgezeichnet hat.

Seiten und Ereignisse werden nach der eigenen Uhr des Browsers geordnet, die alle Tabs einer Sitzung teilen, nicht danach, wann sie eingingen. Ein doppelt gesendeter Batch wird einmal behalten, und einer, der bis zu 2 Minuten nach dem Ende der Sitzung eintrifft, gehört noch zu ihr; danach beginnt der Browser eine neue Sitzung. Eine Sitzung behält bis zu 300 Seiten und 1.500 Ereignisse.

Eine abgelaufene oder gelöschte Aufzeichnung lässt ihre Sitzung bestehen: Seitenverlauf und Ereignisse bleiben, und die Wiedergabe sagt, dass die Aufzeichnung nicht mehr da ist.

Ab Version 0.7.0 sagt eine Anfrage, was über ihr Ende bekannt ist: eine Antwort mit ihrem Status; keine Antwort, wobei der Browser nicht sagt, warum (offline, ein Name, der sich nicht auflösen ließ, eine abgelehnte Verbindung oder eine blockierte Cross-Origin-Anfrage); ein Timeout; ein Abbruch durch Ihre Seite, der nicht als Fehlschlag zählt; eine Cross-Origin-Antwort, deren Status der Browser verbirgt; oder ein Skript, Bild oder Stylesheet, das nicht geladen hat, wobei der Browser nicht sagt, ob ein Server geantwortet hat. Wo der Browser keinen Status liefert, wird keiner gezeigt.

Pro Seite behält das Snippet höchstens 25 Fehler, 25 Konsolenfehler, 50 fehlgeschlagene oder langsame Anfragen und 50 erfolgreiche, und ein Fehler, der erneut auftritt, wird gezählt statt erneut gesendet. Was diese Grenzen, die eigenen Grenzen der Sitzung und die Stichprobe auslassen, wird gezählt, und die Ansichten Network und Errors sagen, wie viel, sodass eine unvollständige Liste nie als vollständig erscheint.

Aufzeichnungen

Jede Aufzeichnung gehört zu einer Sitzung, eine Aufzeichnung für jeden aufgezeichneten Tab, und im Portal finden Sie Aufzeichnungen in ihren Sitzungen. Über die API durchsuchen Sie Aufzeichnungen über alle Websites nach Datum, Status, Land, Geräteklasse, Browser, Betriebssystem, IP-Adresse oder Netzwerk in CIDR-Notation, Einstiegspfad, jeder besuchten Seite und Besucher-ID.

Eine Aufzeichnung, deren Besucher gerade auf der Website ist, hat den Status Live und öffnet sich live: Sie sehen die Seite einen Moment nach dem Besucher, und die Ansicht sagt, um wie viel, etwa "~2.4s behind": Seine Seite sah vor etwa 2,4 Sekunden so aus wie Ihr Bildschirm jetzt. Gemessen wird von seinem Browser bis zu Ihrem, die beiden Uhren werden über unsere verglichen, und die Angabe ist nie genauer, als dieser Vergleich es erlaubt. Die Ansicht sagt auch, wenn sie aufholt, angehalten ist, die Verbindung wiederherstellt oder veraltet ist, und Sie können sie anhalten und wieder live schalten. Während Sie zusehen, sendet sein Browser das Aufgezeichnete jede Sekunde statt alle zehn Sekunden, und eine ruhige Seite meldet alle zwei Sekunden, dass sich nichts geändert hat, sodass sie aktuell bleibt; eine, von der zehn Sekunden lang nichts kommt, wird als veraltet markiert. Auf seiner Seite ändert sich nichts, und nichts verrät ihm, dass jemand zusieht. Eine Aufzeichnung, die noch offen ist, von der aber seit 90 Sekunden nichts mehr eingegangen ist, hat den Status Inactive: Der Besucher hat die Website höchstwahrscheinlich verlassen.

Eine Aufzeichnung ist ein Browser-Tab auf einer Website. Sie endet, wenn der Besucher die Website verlässt, nach 30 Minuten ohne eingehende Daten oder wenn sie 60 Minuten oder 100 MiB erreicht, je nachdem, was zuerst eintritt. Das Löschen einer Aufzeichnung entfernt ihre Wiedergabe und alle dazu gespeicherten Details sofort.

Heatmaps

Eine Heatmap fasst die behaltenen Aufzeichnungen einer Seite auf einer Bildschirmart über einen Zeitraum zusammen. Die Seiten einer Website erscheinen im Portal auf ihrem Tab Heatmaps kurz nachdem eine Aufzeichnung endet, die sie gezeigt hat, die meistbesuchten zuerst.

• Clicks: wo Besucher geklickt oder getippt haben. Hat der Recorder gemeldet, wo auf einem Link oder Button ein Klick landete (ab Version 0.5.0), wird er dort auf diesem Ziel in der gezeigten Seite eingezeichnet, gleich wie breit der Bildschirm war, von dem er kam; andere Klicks werden nach ihrer Position eingezeichnet.
• Attention: wie lange jeder 50-px-Streifen der Seite zu sehen war, als Anteil an der Zeit jedes Besuchs auf der Seite. Inaktive Zeit zählt nicht, ebenso wenig Zeit mit verborgenem Tab, wo der Recorder sie meldet (ab Version 0.5.0).
• Scroll: der Anteil der Besuche, die jeden Punkt der Seite erreicht haben, mit Linien dort, wo 75 %, 50 % und 25 % von ihnen aufgehört hatten.
• Movement: wo der Zeiger verweilte. Telefone und die meisten Tablets haben keinen Zeiger.

Bildschirme werden nach Breite getrennt betrachtet, weil eine Seite, die für einen gestaltet ist, nicht mit einem anderen übereinstimmt: Mobil unter 768 px, Tablet ab 768 px und Desktop ab 1.280 px.

Wählen Sie die letzten 7, 30 oder 90 Tage und vergleichen Sie mit dem gleich langen Zeitraum davor. Eine Heatmap umfasst die noch aufbewahrten Aufzeichnungen, standardmäßig 28 Tage, und höchstens 20.000 Besuche eines Zeitraums: jedes Mal dieselbe Stichprobe.

Die Seite unter der Heatmap ist ein echter Besuch, so wie sie in ihren ersten Momenten war, vor jedem Klick und jeder Eingabe, mit der Maskierung Ihrer Website: einer von bis zu 5 Besuchen mit dem häufigsten Layout des Zeitraums, zwischen denen Sie wechseln können. Die ganze Seite wird in der Breite dieses Besuchers gezeigt, und Sie scrollen sie wie jede Seite. Ein Abschnitt, der erst beim Scrollen erscheint, ist so weit zu sehen, wie dieser Besucher gekommen war.

Heatmaps umfassen nur aufgezeichnete Besuche: Besucher mit Opt-out, Besuche unter fünf Sekunden oder ohne Interaktion und Besuche über Ihr Kontingent hinaus sind nicht enthalten. Der Zeiger ist nicht dort, wo Menschen hinsehen. Scrollen innerhalb eines Bereichs, Frames anderer Websites und Canvas-Inhalte werden nicht erfasst.

Heatmaps zeigen Summen über Besuche hinweg. Sie entstehen aus den Aufzeichnungen und werden mit ihnen gelöscht; ein Klick speichert keinen Text, und die Adresse einer Seite keinen Query-String. Dafür ergänzt der Recorder nur, wann der Tab verborgen ist, und die Höhe der Seite, und speichert nichts weiter im Browser des Besuchers.

API-Schlüssel und Berechtigungen

Plattform-API-Schlüssel werden im Portal erstellt und beginnen mit if_live_. Senden Sie einen als Bearer-Token; er wirkt nur in der Organisation, für die er erstellt wurde.

Authorization: Bearer if_live_...

• analytics:sites:readWebsites lesen, mit ihren Origins, Schlüsseln, ihrem Einstellungsverlauf und Installationsstatus
• analytics:sites:writeWebsites anlegen und ändern, Origins hinzufügen und verifizieren, den öffentlichen Schlüssel rotieren
• analytics:sessions:readSitzungen mit ihren Seiten und Ereignissen sowie Aufzeichnungen mit ihren Besucherdetails und Wiedergabe-Batches durchsuchen und lesen, und Heatmaps lesen
• analytics:sessions:deleteEine Sitzung oder eine Aufzeichnung löschen
• analytics:*Alle Berechtigungen von Ironfang Analytics

Fehler

Jeder Fehler ist ein JSON-Objekt mit einem stabilen Code, einer Meldung für Menschen und der Request-ID, die Sie dem Support nennen.

{
  "error": {
    "code": "not_found",
    "message": "no such object in this organisation",
    "docs": "https://ironfang.com/analytics/docs#errors"
  },
  "request_id": "01a0c375-7bae-7f02-a3d4-91e6b8c25f70"
}

Limits und Aufbewahrung

• Aufzeichnungen werden ab ihrem Beginn 28 Tage aufbewahrt und dann mit allen dazu gespeicherten Details gelöscht.
• Eine Sitzung wird so lange aufbewahrt, wie es der Sitzungsverlauf ihrer Website vorsieht: bis zu 90 Tage und nie kürzer als ihre Aufzeichnungen; eine neue Website behält 90 Tage, und eine früher angelegte Website behält Sitzungen so lange wie ihre Aufzeichnungen, bis Sie es ändern. Ist die Zeit der Aufzeichnungen abgelaufen, werden IP-Adresse, User-Agent, Besucher-ID, Fehlermeldungen und die Eigenschaften erfasster Ereignisse aus der Sitzung entfernt; ihre Seiten und Ereignisse bleiben für den Rest ihrer Zeit.
• Jedes Konto kann 5.000 Aufzeichnungen pro Monat kostenlos behalten. Mit eingeschaltetem Pay as you go werden Aufzeichnungen darüber hinaus zu den veröffentlichten Preisen berechnet, innerhalb des monatlichen Nutzungslimits, das Sie festlegen.
• Ist das kostenlose Kontingent ohne Pay as you go aufgebraucht oder ein Nutzungslimit erreicht, werden neue Besuche erst wieder aufgezeichnet, wenn sich das Kontingent im nächsten Monat erneuert oder das Limit geändert wird. Seiten funktionieren weiter, und bereits erstellte Aufzeichnungen bleiben unberührt.
• Bis zu 100 Websites pro Organisation. Eine Aufzeichnung endet nach 60 Minuten oder bei 100 MiB komprimierter Größe.
• Listen werden mit cursor und limit seitenweise abgerufen, bis zu 100 Einträge pro Seite.

API-Referenz

Basis-URL https://api.ironfang.com/analytics. Das OpenAPI-3.1-Dokument unter https://api.ironfang.com/analytics/openapi.yaml enthält jedes Schema und jeden Fehler, mit stabilen Operation-IDs für generierte Clients.

Maschinenschnittstellen