# 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 franchit 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 basés sur 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. Quels points existent est décidé par le navigateur, pas par un registre figé, donc le geste pratique est de définir explicitement ceux qui vous intéressent et de surveiller les reports.
Les points sur lesquels vous pouvez vous fier dépendent entièrement du navigateur. Dans Chromium, deux sont utilisables en navigation normale :
* `js-profiling` active l'API JS Self-Profiling, permettant à une page d'échantillonner son propre JavaScript pour profiler la performance en conditions 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 expérimentaux. Ils n'existent que dans Chromium et ne prennent effet que derrière le flag `chrome://flags/#enable-experimental-web-platform-features`, donc vous ne pouvez pas encore compter dessus pour de vrais utilisateurs :
* `document-write=?0` coupe `document.write`, un danger d'injection de script et de 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 qu'une image sans taille provoque.
* `oversized-images` plafonne à quel point la taille intrinsèque d'une image peut dépasser 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, utilisant le point expérimental `document-write` pour montrer la syntaxe du header :
```http
Document-Policy: document-write=?0
```
Pour le traitement complet et sourcé de comment le header se parse et ce que chaque point signifie, 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 : vous voulez confirmer ce qui se déclenche réellement dans les navigateurs de vos utilisateurs avant de le bloquer.
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 que le flux de reports devient silencieux pour une contrainte, vous pouvez la déplacer du header report-only vers le 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ù, pour que vous trouviez le code derrière.
```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 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, NEL 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 cherchables, sans avoir besoin d'un pipeline séparé pour 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)