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 "Recording" 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.

Aufzeichnungen erscheinen im Portal unter "Recordings" wenige Sekunden nach einem Besuch.

Installation, Opt-out und Einwilligung

Kopieren Sie das Snippet aus dem Tab "Installation" der Website: Es nennt das aktuelle Release und enthält dessen Subresource-Integrity-Hash sowie den öffentlichen Schlüssel Ihrer Website.

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

Das Snippet zeichnet ab dem ersten Seitenaufruf auf. 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 "Recording" 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.

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.uk 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.

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. 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.

Aufzeichnungen

Durchsuchen Sie Aufzeichnungen über alle Websites nach Datum, Status, Land, Geräteklasse, Browser, Betriebssystem, IP-Adresse oder Netzwerk in CIDR-Notation, Einstiegspfad und Besucher-ID. Eine Aufzeichnung öffnet sich mit ihrer Wiedergabe und den dazu gespeicherten Besucherdetails, darunter die anderen Aufzeichnungen desselben Browsers.

Eine Aufzeichnung, deren Besucher gerade auf der Website ist, hat den Status Live und öffnet sich live: Sie sehen die Seite ein oder zwei Sekunden nach dem Besucher. Während Sie zusehen, sendet sein Browser das Aufgezeichnete jede Sekunde statt alle zehn Sekunden. 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.

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:readAufzeichnungen durchsuchen und lesen, mit ihren Besucherdetails, und ihre Wiedergabe-Batches abrufen
• analytics:sessions:deleteEine 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.uk/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.
• Der Tarif Free umfasst 1.000 Aufzeichnungen pro Monat und 2 GiB gespeicherte Aufzeichnungen; die bezahlten Tarife finden Sie im Abschnitt Preise.
• Sind die Aufzeichnungen eines Monats aufgebraucht, werden neue Besuche bis zum nächsten Monat nicht aufgezeichnet. 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.uk/analytics. Das OpenAPI-3.1-Dokument unter https://api.ironfang.uk/analytics/openapi.yaml enthält jedes Schema und jeden Fehler, mit stabilen Operation-IDs für generierte Clients.

Maschinenschnittstellen