Documentation développeur

Démarrage rapide

1. Dans le portail (en anglais), ajoutez un site avec l'origine de votre site web, par exemple https://www.example.com.
2. Publiez l'enregistrement DNS TXT affiché par le portail, puis choisissez "Verify". La vérification interroge les propres serveurs de noms de votre domaine : elle réussit donc dès que l'enregistrement est publié.
3. Activez l'enregistrement dans l'onglet "Recording" du site.
4. Ajoutez le snippet d'installation de l'onglet "Installation" à chaque page. Pour arrêter d'enregistrer un visiteur, appelez la fonction de refus depuis votre bannière de consentement ou un lien.

Les enregistrements apparaissent sous "Recordings" dans le portail quelques secondes après une visite.

Installation, refus et consentement

Copiez le snippet depuis l'onglet "Installation" du site : il indique la version actuelle et contient son hash Subresource Integrity ainsi que la clé publique de votre site.

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

Le snippet enregistre dès le premier chargement de page. Pour exclure un visiteur de l'enregistrement, appelez ceci depuis votre bannière de consentement ou un lien, avant ou après le chargement du snippet. L'enregistrement s'arrête, tout ce qui n'a pas encore été envoyé est supprimé dans le navigateur, et le navigateur retient ce choix, si bien que les pages suivantes n'enregistrent pas non plus :

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

Si le visiteur change d'avis, setConsent({ replay: true }) relance l'enregistrement.

Lorsque la loi exige un consentement avant l'enregistrement, comme c'est généralement le cas pour les visiteurs au Royaume-Uni et dans l'UE, activez Ask for consent first dans l'onglet "Recording" du site. Le snippet que vous donne alors l'onglet "Installation" contient data-consent="required" : il n'envoie aucune requête et n'enregistre rien tant que votre page n'appelle pas setConsent({ replay: true }), une fois que le visiteur a donné son accord. C'est à vous de déterminer si vos visiteurs doivent être sollicités.

Une visite de plusieurs pages dans le même onglet prolonge un seul enregistrement. Dès qu'un enregistrement commence, le navigateur conserve aussi un identifiant de visiteur aléatoire dans le stockage local et l'envoie avec chaque nouvel enregistrement, afin qu'un deuxième onglet ou une nouvelle visite puisse être retrouvé à côté du premier. Cet identifiant n'est dérivé d'aucune information sur le visiteur, ce n'est pas un cookie, et le refus de l'enregistrement le supprime.

Si votre site utilise une Content Security Policy, autorisez https://analytics.ironfang.uk dans script-src et connect-src.

Ce qui est enregistré

La page telle qu'elle était affichée, ainsi que le défilement, les mouvements du pointeur, les clics et les changements de page. Le masquage a lieu dans le navigateur du visiteur, avant tout envoi :

• Tout ce qui ressemble à un numéro de carte de paiement est masqué partout où il apparaît : dans le texte de la page, dans un champ ou dans un attribut. C'est toujours activé.
• Les champs de numéro de carte, de CVV, de mot de passe et de code à usage unique sont bloqués : ils apparaissent comme des cases vides de même taille. C'est également toujours activé.
• Avec Mask form fields activé, la valeur de chaque champ est remplacée par des caractères de substitution, tout comme le texte saisi dans une zone modifiable (contenteditable). Ce réglage est désactivé pour un nouveau site.
• Avec Mask all text activé, le texte de la page est aussi masqué ; indiquez les sélecteurs dont le texte peut être affiché. Ce réglage est désactivé pour un nouveau site.
• Dans les zones correspondant à vos sélecteurs de masquage permanent, le texte et les champs sont masqués dans tous les cas.
• Les zones correspondant à vos sélecteurs de blocage, ou portant la classe rr-block, ne sont jamais enregistrées.
• Les URL enregistrées ne conservent jamais de fragment. Elles ne conservent que les paramètres de requête que vous indiquez, comme utm_source, ou, avec Record all query parameters activé, tous les paramètres sauf ceux que vous indiquez comme à supprimer, comme token.

Pour exclure vos propres visites de vos enregistrements, indiquez les adresses de votre domicile ou de votre bureau sous Excluded visitors dans les réglages de capture du site : des adresses uniques ou des plages comme 203.0.113.0/24, ou le /64 d'un réseau pour l'IPv6. Une visite provenant de l'une d'elles n'est pas enregistrée du tout, et la page des réglages peut ajouter l'adresse de l'appareil que vous utilisez.

À côté de chaque enregistrement, Ironfang conserve l'adresse IP du visiteur en précisant si Cloudflare l'a signalée, le user agent complet, la taille de la fenêtre et de l'écran, le ratio de pixels, la langue, le fuseau horaire, le pays, la page de provenance sans sa chaîne de requête et l'identifiant de visiteur du navigateur. Tout cela est supprimé avec l'enregistrement. Votre politique de confidentialité doit indiquer que vous enregistrez des sessions et conservez ces détails, et que le navigateur conserve un identifiant de visiteur.

Sites et origines

Un site correspond à un site web : les origines depuis lesquelles son enregistreur peut envoyer des données, une clé de collecte publique et ce qu'il capture. Une origine publique doit être vérifiée avant d'enregistrer : publiez _ironfang-analytics.<host> comme enregistrement TXT avec la valeur affichée par le portail. Les origines en boucle locale comme http://localhost:3000 n'ont besoin d'aucun enregistrement, pour le développement.

La clé publique peut être publiée sans risque : elle permet seulement de demander l'enregistrement pour son propre site. Après une rotation, l'ancienne clé continue de fonctionner pendant 24 heures, afin que les pages en cache continuent d'enregistrer.

Enregistrements

Recherchez des enregistrements sur tous les sites par date, état, pays, catégorie d'appareil, navigateur, système d'exploitation, adresse IP ou réseau en notation CIDR, chemin d'entrée et identifiant de visiteur. Un enregistrement s'ouvre sur son rejeu et les détails du visiteur conservés avec lui, avec en dessous les autres enregistrements du même navigateur.

Un enregistrement dont le visiteur est actuellement sur le site est à l'état Live et s'ouvre en direct : vous voyez la page avec une ou deux secondes de retard sur lui. Pendant que vous regardez, son navigateur envoie ce qu'il enregistre toutes les secondes au lieu de toutes les dix secondes. Rien ne change sur sa page, et rien ne lui indique que quelqu'un regarde. Un enregistrement encore ouvert mais dont rien n'a été reçu depuis 90 secondes est à l'état Inactive : le visiteur est très probablement parti.

Un enregistrement correspond à un onglet de navigateur sur un site. Il se termine quand le visiteur part, après 30 minutes sans rien recevoir, ou lorsqu'il atteint 60 minutes ou 100 MiB, selon ce qui arrive en premier. Supprimer un enregistrement efface immédiatement son rejeu et tous les détails conservés avec lui.

Clés API et portées

Les clés API de la plateforme sont créées dans le portail et commencent par if_live_. Envoyez-en une comme jeton bearer ; elle n'agit que dans l'organisation pour laquelle elle a été créée.

Authorization: Bearer if_live_...

• analytics:sites:readLire les sites, leurs origines, leurs clés, l'historique des paramètres et l'état de l'installation
• analytics:sites:writeCréer et modifier des sites, ajouter et vérifier des origines, effectuer la rotation de la clé publique
• analytics:sessions:readRechercher et lire des enregistrements, avec les détails du visiteur, et récupérer leurs lots de lecture
• analytics:sessions:deleteSupprimer un enregistrement
• analytics:*Toutes les portées d'Ironfang Analytics

Erreurs

Chaque erreur est un objet JSON avec un code stable, un message lisible et l'identifiant de requête à communiquer au support.

{
  "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"
}

Limites et conservation

• Les enregistrements sont conservés 28 jours à compter de leur début, puis supprimés avec tous les détails stockés avec eux.
• L'offre Free comprend 1 000 enregistrements par mois et 2 GiB d'enregistrements stockés ; les offres payantes figurent dans la section tarifs.
• Lorsque les enregistrements du mois sont épuisés, les nouvelles visites ne sont plus enregistrées jusqu'au mois suivant. Les pages continuent de fonctionner et les enregistrements déjà réalisés ne sont pas affectés.
• Jusqu'à 100 sites par organisation. Un enregistrement se termine lorsqu'il atteint 60 minutes ou 100 MiB compressés.
• Les listes se paginent avec cursor et limit, jusqu'à 100 éléments par page.

Référence de l'API

URL de base https://api.ironfang.uk/analytics. Le document OpenAPI 3.1 à l'adresse https://api.ironfang.uk/analytics/openapi.yaml décrit chaque schéma et chaque erreur, avec des identifiants d'opération stables pour les clients générés.

Interfaces pour machines