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 "Settings" 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 sessions apparaissent dans l'onglet "Sessions" du site dans le portail quelques secondes après une visite, avec leurs enregistrements.

Installation, refus et consentement

Copiez le snippet depuis l'onglet "Installation" du site et ajoutez-le une fois : il charge toujours la version la plus récente, vous n'avez donc jamais à le modifier pour en profiter. Il contient la clé publique de votre site.

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

Le snippet enregistre dès le premier chargement de page, et un enregistrement est conservé dès que le visiteur interagit avec la page : rien n'est envoyé pour un visiteur qui ne le fait jamais, les robots d'indexation ne sont jamais enregistrés, et une visite de moins de cinq secondes n'est ni conservée ni comptée. 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 "Settings" 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.

À partir de la version 0.6.0, le snippet suit aussi chaque visite comme une session (voir Sessions). Les sessions sont la base : un enregistrement appartient à sa session, donc à partir de la version 0.6.1 un visiteur n'est enregistré que tant que sa session est suivie. Les sessions suivent le même consentement que l'enregistrement : lorsque le site enregistre sauf refus du visiteur, une session est suivie tant qu'il ne refuse pas ; lorsque le site demande d'abord, elle commence dès que votre page autorise l'un ou l'autre. setConsent({ analytics: false }) refuse les sessions, et l'enregistrement avec elles ; setConsent({ analytics: true, replay: false }) suit les sessions sans enregistrer le visiteur.

Une page qui ne doit pas du tout être suivie, comme une page où les visiteurs collent leurs propres documents, appelle pauseSession() à son ouverture (version 0.6.1) : la page précédente se termine, et ni son adresse ni rien de ce qu'elle contient n'est signalé ou enregistré. resumeSession() sur la page suivante suit de nouveau la visite et l'enregistre de nouveau. La session continue entre-temps, et les choix du visiteur restent inchangés.

Pour marquer un moment de la visite, comme une inscription commencée ou une étape du paiement, suivez-le pendant que la session est suivie : il apparaît dans la chronologie de la session. Un nom compte jusqu'à 64 lettres, chiffres, espaces et _ . : / - ; jusqu'à dix propriétés l'accompagnent, chacune avec un nom en minuscules et un texte de 128 caractères au plus, un nombre, ou true ou false. Tout le reste est ignoré. N'envoyez rien qui identifie le visiteur.

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

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

Une session conserve l'adresse de chaque page, selon les mêmes règles de chaîne de requête, quand elle s'est ouverte et combien de temps elle a été visible, quand l'onglet a été masqué puis affiché, et les événements que votre page suit. Ses diagnostics ont chacun leur interrupteur. Errors conserve les erreurs non interceptées et les rejets non gérés : leur nom, un message dont les adresses e-mail, les numéros de carte et les longs nombres sont retirés, l'adresse et la ligne du script, et la pile, réduite à 12 frames dont les adresses perdent leur chaîne de requête. Console errors conserve ce que votre page passe à console.error, écrit de façon sûre et nettoyé de la même manière. Failed and slow requests conserve les requêtes qui répondent 400 ou plus, n'obtiennent pas de réponse, expirent ou sont annulées, les ressources qui ne se chargent pas, et tout ce qui prend 5 secondes ou plus ; Successful requests conserve les autres, ou la part que vous choisissez. Une requête garde sa méthode, son adresse, son issue, son statut quand le navigateur en donne un, et sa durée, et une valeur de chaîne de requête nommée comme un identifiant, par exemple un jeton ou une signature, est remplacée. Le corps, les en-têtes et les cookies des requêtes et des réponses ne sont jamais lus, et rien n'est tiré du contenu de la page.

À 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, et une session garde les mêmes détails aussi longtemps que ses enregistrements. 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.

Sessions

Une session est une visite : un navigateur sur votre site, dans tous les onglets qu'il ouvre, de sa première page jusqu'à ce que 30 minutes passent sans que le visiteur fasse quoi que ce soit, ou 12 heures après son début. Ses pages, l'activité de ses onglets, ses erreurs, ses requêtes et ses événements suivis lui appartiennent, tout comme les enregistrements de ses onglets.

Avec Follow every visit activé dans l'onglet "Settings" du site, une session est signalée dès la première page, que la visite soit enregistrée ou non : un visiteur qui n'interagit jamais, une visite au-delà de votre quota et un site dont l'enregistrement est désactivé ont tout de même leur parcours. L'enregistrement en dépend : un enregistrement appartient à sa session, donc désactiver ce réglage désactive aussi l'enregistrement, et l'API refuse un enregistrement sans lui. Un nouveau site l'a activé, avec Errors et Failed and slow requests ; un site créé avant la version 0.6.0 qui enregistre suit déjà les sessions, active Errors et Failed and slow requests dans Settings et passe son snippet à la version actuelle.

L'onglet "Sessions" du site liste les sessions par début, durée, page d'entrée, pages et événements, erreurs et requêtes en échec, ce qui peut être rejoué et si le visiteur est sur le site en ce moment, avec un filtre pour chacun. Une session s'ouvre sur son parcours : ses pages dans l'ordre, avec l'onglet de chacune et la durée pendant laquelle elle a été visible, chacune liée à ce moment du rejeu lorsqu'elle a été enregistrée. Ses événements sont regroupés par page et filtrés par type ; sa vue Network liste ses requêtes avec leur issue, et sa vue Errors ses erreurs, chacune une fois par page avec le nombre de fois où elle s'est produite, toutes deux filtrables et liées à ce moment du rejeu ; ses enregistrements se rejouent sur place, et sa carte de chaleur montre les clics et le défilement propres à la session sur chaque page qu'elle a enregistrée.

Les pages et les événements sont classés selon l'horloge du navigateur, que partagent tous les onglets d'une session, et non selon leur arrivée. Un lot envoyé deux fois est conservé une seule fois, et un lot qui arrive jusqu'à 2 minutes après la fin de la session la rejoint encore ; au-delà, le navigateur commence une nouvelle session. Une session conserve jusqu'à 300 pages et 1 500 événements.

Un enregistrement expiré ou supprimé laisse sa session en place : le parcours et les événements restent, et le rejeu indique que l'enregistrement n'est plus disponible.

À partir de la version 0.7.0, une requête dit ce que l'on sait de sa fin : une réponse, avec son statut ; aucune réponse, sans que le navigateur dise pourquoi (hors ligne, un nom qui ne s'est pas résolu, une connexion refusée ou une requête cross-origin bloquée) ; un délai dépassé ; une annulation par votre page, qui ne compte pas comme un échec ; une réponse cross-origin dont le navigateur cache le statut ; ou un script, une image ou une feuille de style qui ne s'est pas chargé, sans que le navigateur dise si un serveur a répondu. Quand le navigateur ne donne pas de statut, aucun n'est affiché.

Par page, le snippet conserve au plus 25 erreurs, 25 erreurs de console, 50 requêtes en échec ou lentes et 50 requêtes réussies, et une erreur qui se reproduit est comptée plutôt que renvoyée. Ce que ces limites, celles de la session et l'échantillonnage laissent de côté est compté, et les vues Network et Errors disent combien, pour qu'une liste partielle ne passe jamais pour complète.

Enregistrements

Chaque enregistrement appartient à une session, un enregistrement par onglet enregistré, et dans le portail les enregistrements se trouvent dans leur session. Via l'API, 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, toute page visitée et identifiant de visiteur.

Un enregistrement dont le visiteur est actuellement sur le site est à l'état Live et s'ouvre en direct : vous voyez la page avec un léger retard sur lui, et la vue indique lequel, par exemple "~2.4s behind" : sa page ressemblait à votre écran il y a environ 2,4 secondes. Le retard est mesuré de son navigateur au vôtre, les deux horloges étant comparées à la nôtre, et n'est jamais affiché plus précisément que cette comparaison ne le permet. La vue indique aussi quand elle rattrape son retard, est en pause, se reconnecte ou n'est plus à jour, et vous pouvez la mettre en pause puis revenir au direct. Pendant que vous regardez, son navigateur envoie ce qu'il enregistre toutes les secondes au lieu de toutes les dix secondes, et une page calme signale toutes les deux secondes que rien n'a changé, si bien qu'elle reste à jour ; une page dont rien n'arrive pendant dix secondes est signalée comme n'étant plus à jour. 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.

Cartes de chaleur

Une carte de chaleur additionne les enregistrements conservés d'une page, sur un type d'écran, sur une période. Les pages d'un site apparaissent dans son onglet Heatmaps du portail peu après la fin d'un enregistrement qui les a affichées, les plus visitées en premier.

• Clicks : où les visiteurs ont cliqué ou touché l'écran. Quand l'enregistreur a indiqué où un clic est tombé sur un lien ou un bouton (à partir de la version 0.5.0), il est dessiné à cet endroit de la cible dans la page affichée, quelle que soit la largeur de l'écran d'origine ; les autres clics sont dessinés selon leur position.
• Attention : combien de temps chaque bande de 50 px de la page était à l'écran, en part du temps de chaque visite sur la page. Le temps d'inactivité ne compte pas, ni le temps où l'onglet était masqué quand l'enregistreur le signale (à partir de la version 0.5.0).
• Scroll : la part des visites qui ont atteint chaque point de la page, avec des lignes là où 75 %, 50 % et 25 % d'entre elles s'étaient arrêtées.
• Movement : là où le pointeur s'est arrêté. Les téléphones et la plupart des tablettes n'ont pas de pointeur.

Les écrans sont traités séparément selon leur largeur, car une page mise en forme pour l'un ne se superpose pas à un autre : mobile en dessous de 768 px, tablette à partir de 768 px et ordinateur à partir de 1 280 px.

Choisissez les 7, 30 ou 90 derniers jours, et comparez avec la période de même durée qui la précède. Une carte de chaleur couvre les enregistrements encore conservés, 28 jours en standard, et au plus 20 000 visites d'une période : le même échantillon à chaque fois.

La page sous la chaleur est une vraie visite, telle qu'elle était dans ses premiers instants, avant tout clic ou toute saisie, avec le masquage de votre site appliqué : l'une des 5 visites au plus de la mise en page la plus courante de la période, que vous pouvez parcourir. La page entière est affichée à la largeur de ce visiteur, et vous la faites défiler comme n'importe quelle page. Une section qui n'apparaît qu'au défilement s'affiche jusqu'où ce visiteur était arrivé.

Les cartes de chaleur ne comprennent que les visites enregistrées : les visiteurs qui ont refusé l'enregistrement, les visites de moins de cinq secondes ou sans interaction et les visites au-delà de votre quota n'y figurent pas. Le pointeur n'est pas là où l'on regarde. Le défilement à l'intérieur d'un panneau, les cadres provenant d'autres sites et le contenu des canvas ne sont pas couverts.

Les cartes de chaleur montrent des totaux sur l'ensemble des visites. Elles sont produites à partir des enregistrements et supprimées avec eux ; un clic ne conserve aucun texte, et l'adresse d'une page ne conserve aucune chaîne de requête. Pour elles, l'enregistreur ajoute seulement le moment où l'onglet est masqué et la hauteur de la page, et ne stocke rien de plus dans le navigateur du visiteur.

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 les sessions avec leurs pages et leurs événements, et les enregistrements avec les détails du visiteur et leurs lots de lecture, et lire les cartes de chaleur
• analytics:sessions:deleteSupprimer une session ou 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.com/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.
• Une session est conservée selon l'historique des sessions de son site : jusqu'à 90 jours, et jamais moins longtemps que ses enregistrements ; un nouveau site conserve 90 jours, et un site créé auparavant conserve les sessions aussi longtemps que ses enregistrements, jusqu'à ce que vous le changiez. Quand le délai des enregistrements est écoulé, l'adresse IP, le user agent, l'identifiant de visiteur, les messages d'erreur et les propriétés des événements suivis sont retirés de la session ; ses pages et ses événements restent jusqu'à la fin de son délai.
• Chaque compte peut conserver gratuitement 5 000 enregistrements par mois. Avec Pay as you go activé, les enregistrements au-delà sont facturés aux tarifs publiés, dans la limite d'utilisation mensuelle que vous fixez.
• Lorsque le quota gratuit est épuisé sans Pay as you go, ou qu'une limite d'utilisation est atteinte, les nouvelles visites ne sont plus enregistrées jusqu'au renouvellement du quota le mois suivant, ou jusqu'à ce que la limite change. 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.com/analytics. Le document OpenAPI 3.1 à l'adresse https://api.ironfang.com/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