# Configurer les fonctionnalités par document avec Document-Policy (/fr/blog/document-policy-explained)
Le header `Document-Policy` vous permet d'activer ou de désactiver des fonctionnalités et des contraintes au niveau du document pour une seule page, par exemple couper `document.write`, exiger que les images déclarent leurs dimensions, ou bloquer les XHR synchrones. Le navigateur applique la contrainte et, si vous le lui demandez, envoie un report `document-policy-violation` quand la page en enfreint une. Cet article couvre ce que le header configure, la variante report-only pour mesurer avant d'imposer, et comment les reports de violation vous parviennent via la [Reporting API](/fr/blog/how-to-set-up-the-reporting-api).
Document-Policy est un brouillon de Community Group WICG, pas un standard W3C finalisé. Seuls les navigateurs Chromium l'implémentent ; Firefox et Safari n'implémentent pas du tout Document-Policy. Même dans Chromium, la plupart des points de configuration sont expérimentaux. Traitez les listes ci-dessous comme spécifiques à Chromium et confirmez qu'un point est réellement utilisable avant de vous y fier.
## Ce que Document-Policy configure [#ce-que-document-policy-configure]
Le header est une liste de points de configuration, chacun régissant un seul comportement du document. Un point prend une valeur typée : un booléen (`?0` pour off, `?1` pour on), un entier, un flottant ou un enum. C'est le navigateur, et non un registre figé, qui décide des points disponibles : en pratique, définissez explicitement ceux qui vous intéressent et surveillez les reports.
Les points sur lesquels vous pouvez compter dépendent entièrement du navigateur. Dans Chromium, deux sont utilisables en navigation normale :
* `js-profiling` active l'API JS Self-Profiling, qui permet à une page d'échantillonner son propre JavaScript pour mesurer ses performances réelles en production.
* `include-js-call-stacks-in-crash-reports=?1` enrichit un [report de crash du navigateur](/fr/blog/browser-crash-reports) avec une pile d'appels JavaScript, pour qu'un crash pointe vers le code qui l'a causé.
Plusieurs autres points sont définis dans le brouillon mais restent expérimentaux. Ils n'existent que dans Chromium et ne prennent effet que derrière le flag `chrome://flags/#enable-experimental-web-platform-features`, vous ne pouvez donc pas encore compter dessus face à de vrais utilisateurs :
* `document-write=?0` coupe `document.write`, à la fois un risque d'injection de script et un rendu qui bloque le parseur.
* `unsized-media=?0` exige que les éléments média déclarent une taille, ce qui évite le décalage de mise en page provoqué par une image sans dimensions.
* `oversized-images` limite l'écart entre la taille intrinsèque d'une image et sa taille affichée, pour qu'une page ne puisse pas livrer une image de plusieurs mégaoctets réduite en CSS.
* `sync-xhr=?0` bloque `XMLHttpRequest` synchrone, qui gèle le thread principal.
Un exemple minimal, avec le point expérimental `document-write`, pour montrer la syntaxe du header :
```http
Document-Policy: document-write=?0
```
Pour le détail complet et sourcé du parsing du header et du sens de chaque point, voyez la [référence Document-Policy](/fr/docs/web-security/policies/document-policy).
## La variante report-only [#la-variante-report-only]
`Document-Policy-Report-Only` évalue les mêmes contraintes et signale ce qui casserait, sans rien imposer réellement. Cela compte ici plus que pour la plupart des headers, parce que l'ensemble des points de configuration dépend de l'implémentation : mieux vaut confirmer ce qui se déclenche réellement dans les navigateurs de vos utilisateurs avant de bloquer quoi que ce soit.
Utilisez-le comme vous utiliseriez le header imposant, mais pointez chaque point contraint vers un endpoint de reporting. Déclarez d'abord l'endpoint avec [`Reporting-Endpoints`](/fr/docs/web-security/reporting-api/headers/reporting-endpoints) :
```http
Reporting-Endpoints: doc-endpoint="https://.report.centralcsp.com"
```
Puis définissez la politique report-only et routez le point vers cet endpoint :
```http
Document-Policy-Report-Only: document-write=?0;report-to=doc-endpoint
```
Chaque point peut porter son propre paramètre `report-to`. Un `*;report-to=endpoint` en tête définit un endpoint par défaut pour chaque point, et `report-to=none` désactive le reporting pour un point précis. Une fois qu'une contrainte ne génère plus aucun report, vous pouvez la faire passer du header report-only au header `Document-Policy` imposant.
## Le report document-policy-violation [#le-report-document-policy-violation]
Quand la page fait quelque chose qu'une contrainte interdit, le navigateur envoie un report `document-policy-violation` à l'endpoint que vous avez nommé. Il vous dit quel point a été violé et où, de quoi remonter au code responsable.
```json
{
"type": "document-policy-violation",
"age": 420,
"url": "https://example.com/",
"user_agent": "Mozilla/5.0 ...",
"body": {
"policyId": "document-write",
"disposition": "report",
"message": "Document policy violation: document-write is not allowed.",
"sourceFile": "https://example.com/script.js",
"lineNumber": 11,
"columnNumber": 12
}
}
```
Le `policyId` nomme le point de configuration, `disposition` vaut `report` en mode report-only et `enforce` une fois que vous imposez, et `sourceFile` avec la ligne et la colonne pointe directement vers le code fautif. Un piège à prévoir : le report reçu à votre endpoint nomme le champ `policyId`, mais l'interface JS ReportingObserver dans le navigateur expose la même valeur sous `featureId`, donc attendez-vous à ce que le nom de l'API JS diffère du champ transmis. La charge utile complète et la référence des champs sont sur la [page du report document-policy-violation](/fr/docs/web-security/reporting-api/reports/document-policy-violation).
## Collectez les reports sans backend [#collectez-les-reports-sans-backend]
Un report `document-policy-violation` utilise le même chemin de livraison que vos autres reports de navigateur, donc il arrive dans le même flux que vos reports CSP et de crash. Pointez l'endpoint `report-to` vers [CentralCSP](/platform/csp-builder) et les reports document-policy atterrissent à côté du reste, mis en graphiques et interrogeables, sans pipeline dédié à une fonctionnalité expérimentale. C'est aussi là que le signal report-only devient utile : vous pouvez mesurer ce qu'une contrainte casserait sur du trafic réel avant de l'imposer.
## Étapes suivantes [#étapes-suivantes]
* Mettez d'abord en place le reporting de bout en bout : [comment mettre en place la Reporting API](/fr/blog/how-to-set-up-the-reporting-api).
* Lisez la [référence Document-Policy](/fr/docs/web-security/policies/document-policy) et le [report document-policy-violation](/fr/docs/web-security/reporting-api/reports/document-policy-violation).
* Voyez comment le point de pile d'appels alimente les [reports de crash du navigateur](/fr/blog/browser-crash-reports).
* Déclarez votre endpoint avec le [header Reporting-Endpoints](/fr/docs/web-security/reporting-api/headers/reporting-endpoints).
[Collectez les reports Document-Policy depuis de vrais navigateurs](/register).
## Sources [#sources]
* [MDN, header Document-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Document-Policy)
* [WICG, spécification Document Policy](https://wicg.github.io/document-policy/)
## Articles liés [#articles-liés]
* [Qu'est-ce que NEL, le network error logging depuis le navigateur](/fr/blog/what-is-nel-network-error-logging)
* [Reports de crash et de page qui ne répond plus](/fr/blog/browser-crash-reports)
* [Comment mettre en place la Reporting API](/fr/blog/how-to-set-up-the-reporting-api)