Rapports de deprecation et intervention, anticipez les changements de navigateur qui cassent votre site
CentralCSP Team
CentralCSP ·
Dernière mise à jour:
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. Beaucoup d'interventions, comme 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, ne font qu'écrire un message dans la console. Celle que Chromium
transforme aujourd'hui en rapport intervention est l'intervention sur les publicités
lourdes, qui décharge une iframe publicitaire trop gourmande en réseau ou en CPU.
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": "UnloadHandler",
"message": "Unload event listeners are deprecated and will be removed.",
"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. Dans Chromium, l'id est le nom d'une entrée de sa liste de
deprecations, comme UnloadHandler ou XSLT. Chromium signale chaque id au plus une
fois par page plutôt qu'à chaque appel, un décompte suit donc les pages touchées, pas les appels.
anticipatedRemoval est censé porter une date de suppression, mais Chromium ne le
remplit jamais, le champ est donc absent des rapports qu'il envoie (un
ReportingObserver le voit à null). La version de suppression n'apparaît que dans
le message, quand il y en a une. 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. Ne comptez que sur Chromium pour envoyer
les rapports de deprecation à un endpoint : le Reporting API livré par Firefox 149
couvre les rapports CSP et Integrity-Policy, et n'expose qu'une partie des
deprecations à ReportingObserver dans la page.
À quoi ressemble un rapport d'intervention
Un rapport intervention
a la même forme : un id pour l'intervention, un message lisible, et un
emplacement source quand un script s'exécutait à ce moment-là. L'intervention sur les
publicités lourdes est décidée par le navigateur, son rapport ne porte donc en
général aucun champ d'emplacement.
{
"type": "intervention",
"body": {
"id": "HeavyAdIntervention",
"message": "Ad was removed because its network usage exceeded the limit. See https://www.chromestatus.com/feature/4800491902992384?utm_source=devtools"
}
}Chromium envoie ce rapport à la page qui intègre l'iframe publicitaire, donc une
rafale de HeavyAdIntervention vous signale qu'un partenaire publicitaire diffuse
des créations assez lourdes pour que Chrome les retire. La lecture est simple : le
champ id vous dit quelle intervention du navigateur s'est déclenchée, et le
message vous dit pourquoi. 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
idde 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
idd'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
- Chromium, reporting_service_proxy.cc (les corps deprecation et intervention envoyés à
default) - Chromium, deprecation.cc (corps du rapport construit sans anticipatedRemoval) et deprecation.json5 (les id de deprecation)
- Chromium, ads_page_load_metrics_observer.cc (le rapport
HeavyAdIntervention)