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 l'état de l'appareil ou du réseau ne s'y prêtait pas. Dans les deux cas, vous n'avez le plus souvent qu'un avertissement dans la console, qu'aucun utilisateur réel ne vous remontera. Les rapports de deprecation et d'intervention transforment ces avertissements silencieux en un flux que vous collectez depuis le trafic réel, de quoi repérer une fonctionnalité qui casse avant qu'une mise en production ne vous l'apprenne.

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 l'avance : vous savez quelles pages utilisent encore l'ancienne API pendant qu'il est encore temps de migrer.

Un rapport d'intervention vous indique que le navigateur a refusé ou remplacé quelque chose que votre code demandait, parce que le faire 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 c'est le rapport d'intervention qui vous l'apprend.

Ce sont des signaux d'observabilité, pas des mécanismes d'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.

Il n'y a donc aucun câblage à faire politique par politique. 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://example.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 date de suppression estimée par le navigateur 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, ne considérez donc rien d'autre que id et message comme garanti.

À 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://example.com/player.js",
    "lineNumber": 17,
    "columnNumber": 4
  }
}

La lecture 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é ne se comporte pas sur le terrain comme 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 va bientôt faire mal. 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 n'est pas garantie, 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 : il suffit de pointer votre endpoint default vers lui pour collecter les deprecations et interventions à côté de vos rapports CSP et autres, groupés par id pour qu'une tendance à la hausse saute aux yeux au lieu de rester enfouie. Vous voyez quelles fonctionnalités disparaissent sur l'ensemble du 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