Rapports de deprecation et intervention, anticipez les changements de navigateur qui cassent votre site

Les navigateurs changent sous vos pieds. Une API dont vous dépendez est marquée pour suppression, ou le navigateur décide discrètement de ne pas faire ce que votre code demandait parce que les conditions de l'appareil ou du réseau rendaient cela inopportun. Ces deux événements ne remontent généralement que sous la forme d'un avertissement dans la console qu'aucun vrai utilisateur ne vous rapporte. Les rapports de deprecation et d'intervention transforment ces avertissements silencieux en un flux que vous pouvez collecter depuis le trafic réel, pour découvrir qu'une fonctionnalité casse avant qu'une mise en production ne le fasse à votre place.

Deux avertissements que le navigateur connaît déjà

Un rapport de deprecation vous indique que votre page a utilisé une API ou un comportement que le navigateur prévoit de supprimer. C'est la version structurée du message « cette fonctionnalité est obsolète et sera supprimée » que vous avez vu dans la console, envoyé à un serveur au lieu de rester sur la machine de l'utilisateur. L'intérêt, c'est le délai : vous apprenez quelles pages touchent encore l'ancienne API alors qu'il reste du temps pour migrer.

Un rapport d'intervention vous indique que le navigateur a refusé ou remplacé quelque chose que votre code demandait, parce que le respecter aurait nui à l'utilisateur. Les exemples classiques sont le blocage de la lecture automatique avec son, ou le refus d'un appel document.write() qui aurait injecté un script sur une connexion lente. Votre code s'est exécuté, mais le navigateur est intervenu, et le rapport d'intervention est la façon dont vous l'apprenez.

Les deux relèvent de l'observabilité, pas de l'application. Ils ne changent jamais le comportement ; ils vous disent seulement ce qui s'est déjà produit. Ensemble, ils forment un canal d'alerte précoce pour les parties de votre front-end qui dépendent d'un comportement du navigateur que vous ne contrôlez pas.

Comment ils vous parviennent

Les rapports de deprecation et d'intervention circulent sur le même Reporting API du navigateur que vos rapports CSP et réseau, mais ils s'y rattachent différemment. Un rapport CSP est lié à une politique précise, vous pointez donc cette politique vers un endpoint nommé. Un rapport de deprecation ou d'intervention n'est lié à aucune politique, il peut se déclencher depuis n'importe où sur la page, donc le navigateur l'envoie à l'endpoint nommé default.

Cela veut dire qu'il n'y a aucun câblage par politique à faire. Vous déclarez une fois un endpoint default avec le header Reporting-Endpoints, et le navigateur y achemine automatiquement les deux types de rapports.

Reporting-Endpoints: default="https://<Endpoint-ID>.report.centralcsp.com"

Servez ce header sur chaque page que vous voulez couvrir, puisqu'il ne s'applique qu'à la réponse sur laquelle il est envoyé. Aucune directive, aucun paramètre, le nom default est le contrat.

À quoi ressemble un rapport de deprecation

Le navigateur envoie un rapport deprecation dont le corps nomme la fonctionnalité obsolète et, quand le navigateur les fournit, un message et une échéance de suppression, plus l'emplacement source qui l'a déclenché.

{
  "type": "deprecation",
  "body": {
    "id": "WebSQL",
    "message": "Web SQL is deprecated and will be removed.",
    "anticipatedRemoval": "2026-01-01T00:00:00.000Z",
    "sourceFile": "https://api-next.centralcsp.com/app.js",
    "lineNumber": 42,
    "columnNumber": 8
  }
}

Le champ id est un identifiant stable de la fonctionnalité obsolète, vous pouvez donc grouper les rapports par ce champ et suivre combien de pages dépendent encore de chacune. anticipatedRemoval est la meilleure estimation du navigateur pour une date de suppression et peut être absent. Les champs sourceFile, lineNumber et columnNumber pointent vers l'emplacement d'appel exact, ce qui rend ce rapport plus utile qu'un avertissement générique. Un corps de deprecation transporte id, message, anticipatedRemoval, sourceFile, lineNumber et columnNumber, mais l'ensemble exact des champs varie selon le navigateur, donc traitez les champs au-delà de id et message comme fournis au mieux.

À quoi ressemble un rapport d'intervention

Un rapport intervention a la même forme : un id pour l'intervention, un message lisible, et l'emplacement source du code que le navigateur a remplacé.

{
  "type": "intervention",
  "body": {
    "id": "AudioContext",
    "message": "An AudioContext was prevented from starting automatically.",
    "sourceFile": "https://api-next.centralcsp.com/player.js",
    "lineNumber": 17,
    "columnNumber": 4
  }
}

Le lire est simple : le champ id vous dit quelle intervention du navigateur s'est déclenchée, et l'emplacement source vous dit lequel de vos scripts l'a provoquée. Une rafale du même id d'intervention chez de vrais utilisateurs signifie qu'une fonctionnalité se comporte différemment sur le terrain que sur votre machine, souvent sur des appareils ou des réseaux plus lents que vous ne testez pas.

Utilisez-les comme un signal ops

La valeur est dans la tendance, pas dans le rapport isolé. Un filet régulier d'un même id de deprecation est un point de backlog ; un pic soudain, ou un nouvel id qui apparaît juste après une version du navigateur, est le signe qu'un changement est sur le point de mordre. Surveillez :

• Un nouvel id de deprecation qui apparaît sur de nombreuses pages, ce qui signale une dépendance (souvent un script tiers) utilisant une API en fin de vie.
• Un id d'intervention qui n'apparaît que pour une partie des utilisateurs, ce qui signifie en général un comportement de performance ou de lecture automatique qui varie selon l'appareil ou le réseau.
• Un bond de l'un ou l'autre juste après une version de Chromium, qui aligne vos rapports sur le calendrier de suppression du navigateur lui-même.

Comme la livraison est fournie au mieux, lisez-les comme une jauge d'alerte précoce, pas comme un décompte complet. Ils vous disent qu'un problème existe et où regarder, bien avant qu'il ne devienne un ticket de support.

Collectez-les dans un seul flux

Les rapports de deprecation et d'intervention sont exactement le genre de données à faible volume et à fort signal qui se perdent si vous ne surveillez que la console. CentralCSP ingère tous les types de rapports du navigateur, donc pointer votre endpoint default vers lui collecte les deprecations et interventions à côté de vos rapports CSP, NEL et autres, groupés par id pour qu'une tendance à la hausse soit visible au lieu d'être enfouie. Vous voyez quelles fonctionnalités disparaissent à travers le trafic réel, pas seulement les rares qui se déclenchent sur le portable d'un développeur.

Étapes suivantes

• Câblez d'abord les endpoints : comment configurer le Reporting API.
• Lisez la référence du rapport deprecation et la référence du rapport intervention.
• Déclarez l'endpoint fourre-tout avec Reporting-Endpoints.

Anticipez tôt les changements de navigateur qui cassent.

Sources

• Deprecation Reporting sur MDN
• Spécification du Reporting API (W3C)
• Deprecations et interventions sur Chrome for Developers

Articles liés

• Comment configurer le Reporting API du navigateur
• Qu'est-ce que NEL, le network error logging du navigateur
• Report-To vs Reporting-Endpoints