Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Tutoriel: Migrer vers Manifest V2

La version 1 du fichier manifeste a été abandonnée dans Chrome 18. L'assistance sera progressivement supprimée conformément au calendrier d'assistance pour la version 1 du fichier manifeste. Les modifications apportées entre la version 1 et la version 2 se répartissent en deux grandes catégories : les modifications de l'API et les modifications de sécurité.

Ce document fournit des checklists pour migrer vos extensions Chrome de la version 1 du fichier manifeste vers la version 2. Il contient également des résumés plus détaillés sur la signification de ces modifications et les raisons pour lesquelles elles ont été apportées.

Checklist des modifications apportées aux API

Utilisez-vous la propriété browser_actions ou l'API chrome.browserActions ?
Remplacez browser_actions par la propriété browser_action au singulier.
Remplacez chrome.browserActions par chrome.browserAction.
Remplacez la propriété icons par default_icon.
Remplacez la propriété name par default_title.
Remplacez la propriété popup par default_popup (qui doit désormais être une chaîne).
Utilisez-vous la propriété page_actions ou l'API chrome.pageActions ?
Remplacez page_actions par page_action.
Remplacez chrome.pageActions par chrome.pageAction.
Remplacez la propriété icons par default_icon.
Remplacez la propriété name par default_title.
Remplacez la propriété popup par default_popup (qui doit désormais être une chaîne).
Utilisez-vous la propriété chrome.self ?
Remplacer par chrome.extension.
Utilisez-vous la propriété Port.tab ?
Remplacer par Port.sender.
Utilisez-vous les API chrome.extension.getTabContentses() ou chrome.extension.getExtensionTabs() ?
Remplacer par chrome.extension.getViews( { "type" : "tab" } ).
Votre extension utilise-t-elle une page d'arrière-plan ?
Remplacez la propriété background_page par une propriété background.
Ajoutez une propriété scripts ou page contenant le code de la page.
Ajoutez une propriété persistent et définissez-la sur false pour convertir votre page d'arrière-plan en page d'événement.

Checklist des modifications de sécurité

Utilisez-vous des blocs de script intégrés dans les pages HTML ?
Supprimez le code JS contenu dans les balises <script> et placez-le dans un fichier JS externe.
Utilisez-vous des gestionnaires d'événements intégrés (comme onclick, etc.) ?
Supprimez-les du code HTML, déplacez-les dans un fichier JS externe et utilisez plutôt addEventListener().
Votre extension injecte-t-elle des scripts de contenu dans des pages Web qui doivent accéder à des ressources (comme des images et des scripts) contenues dans le package de l'extension ?
Définissez la propriété web_accessible_resources et listez les ressources (et éventuellement une stratégie de sécurité du contenu distincte pour ces ressources).
Votre extension intègre-t-elle des pages Web externes ?
Définissez la propriété sandbox.
Votre code ou votre bibliothèque utilisent-ils eval(), Function(), innerHTML, setTimeout() ou transmettent-ils des chaînes de code JS qui sont évaluées de manière dynamique ?
Utilisez JSON.parse() si vous analysez du code JSON dans un objet.
Utilisez une bibliothèque compatible avec CSP, par exemple AngularJS.
Créez une entrée de bac à sable dans votre fichier manifeste et exécutez le code concerné dans le bac à sable, en utilisant postMessage() pour communiquer avec la page en bac à sable.
Chargez-vous du code externe, tel que jQuery ou Google Analytics ?
Envisagez de télécharger la bibliothèque et de l'intégrer à votre extension, puis de la charger à partir du package local.
Ajoutez le domaine HTTPS qui diffuse la ressource à la liste d'autorisation dans la partie "content_security_policy" de votre fichier manifeste.

Résumé des modifications apportées à l'API

La version 2 du fichier manifeste introduit quelques modifications dans les API browserAction et pageAction, et remplace certaines anciennes API par de nouvelles.

Modifications apportées aux actions du navigateur

L'API des actions du navigateur introduit des modifications de nommage :

Les propriétés browser_actions et chrome.browserActions ont été remplacées par leurs équivalents au singulier, browser_action et chrome.browserAction.
L'ancienne propriété browser_actions comprenait les propriétés icons, name et popup. Elles ont été remplacées par :
default_icon pour l'icône du badge d'action du navigateur
default_name pour le texte qui s'affiche dans l'info-bulle lorsque vous pointez sur le badge
default_popup pour la page HTML qui représente l'UI de l'action du navigateur (et qui doit désormais être une chaîne, et non un objet)

Modifications apportées aux actions sur les pages

Comme pour les actions du navigateur, l'API Page Actions a également été modifiée :

Les propriétés page_actions et chrome.pageActions ont été remplacées par leurs équivalents au singulier, page_action et chrome.pageAction.
L'ancienne propriété page_actions comprenait les propriétés icons, name et popup. Elles ont été remplacées par :
default_icon pour l'icône de badge d'action sur la page
default_name pour le texte qui s'affiche dans l'info-bulle lorsque vous pointez sur le badge
default_popup pour la page HTML qui représente l'UI de l'action de page (et qui doit désormais être une chaîne, et non un objet)

API supprimées et modifiées

Quelques API d'extension ont été supprimées et remplacées par de nouvelles :

La propriété background_page a été remplacée par background.
La propriété chrome.self a été supprimée. Utilisez chrome.extension.
La propriété Port.tab a été remplacée par Port.sender.
Les API chrome.extension.getTabContentses() et chrome.extension.getExtensionTabs() ont été remplacées par chrome.extension.getViews( { "type" : "tab" } ).

Résumé des modifications de sécurité

Le passage de la version 1 à la version 2 du fichier manifeste s'accompagne de plusieurs modifications liées à la sécurité. La plupart de ces modifications découlent de l'adoption de la Content Security Policy par Chrome. Nous vous invitons à en savoir plus sur cette règle pour comprendre ses implications.

Scripts et gestionnaires d'événements intégrés non autorisés

En raison de l'utilisation de la Content Security Policy, vous ne pouvez plus utiliser les balises <script> intégrées au contenu HTML. Elles doivent être déplacées vers des fichiers JS externes. De plus, les gestionnaires d'événements intégrés ne sont pas non plus pris en charge. Par exemple, supposons que vous ayez le code suivant dans votre extension :

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

Ce code entraînerait une erreur lors de l'exécution. Pour résoudre ce problème, déplacez le contenu de la balise <script> vers des fichiers externes et faites-y référence avec un attribut src='path_to_file.js'.

De même, les gestionnaires d'événements intégrés, qui sont une fonctionnalité courante et pratique utilisée par de nombreux développeurs Web, ne s'exécuteront pas. Par exemple, prenons les cas courants suivants :

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

Elles ne fonctionneront pas dans les extensions Manifest V2. Supprimez les gestionnaires d'événements intégrés, placez-les dans votre fichier JS externe et utilisez addEventListener() pour enregistrer les gestionnaires d'événements à la place. Par exemple, dans votre code JS, utilisez :

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

Il s'agit d'une façon beaucoup plus propre de séparer le comportement de votre extension du balisage de son interface utilisateur.

Intégrer du contenu

Dans certains cas, votre extension peut intégrer du contenu qui peut être utilisé en externe ou provenir d'une source externe.

Contenu d'extension dans les pages Web : Si votre extension intègre des ressources (comme des images, des scripts, des styles CSS, etc.) utilisées dans des scripts de contenu injectés dans des pages Web, vous devez utiliser la propriété web_accessible_resources pour autoriser ces ressources afin que les pages Web externes puissent les utiliser :

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

Intégration de contenu externe : la Content Security Policy autorise uniquement le chargement de scripts et d'objets locaux à partir de votre package, ce qui empêche les pirates informatiques externes d'introduire du code inconnu dans votre extension. Toutefois, il peut arriver que vous souhaitiez charger des ressources diffusées en externe, comme le code jQuery ou Google Analytics. Pour cela, vous pouvez procéder de deux façons :

Téléchargez la bibliothèque concernée en local (comme jQuery) et packagez-la avec votre extension.
Vous pouvez assouplir la CSP de manière limitée en ajoutant des origines HTTPS à la section "content_security_policy" de votre fichier manifeste. Pour inclure une bibliothèque comme Google Analytics, voici l'approche à suivre :
```
{
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}
```

Utiliser l'évaluation dynamique des scripts

L'un des changements les plus importants du nouveau schéma de fichier manifeste V2 est que les extensions ne peuvent plus utiliser de techniques d'évaluation de script dynamique comme eval() ou Function(), ni transmettre de chaînes de code JS à des fonctions qui entraîneront l'utilisation de eval(), comme setTimeout(). De plus, certaines bibliothèques JavaScript couramment utilisées, telles que Google Maps et certaines bibliothèques de modèles, sont connues pour utiliser certaines de ces techniques.

Chrome fournit un bac à sable pour que les pages s'exécutent dans leur propre origine, qui n'ont pas accès à chrome.*. API Pour utiliser eval() et d'autres éléments similaires avec la nouvelle Content Security Policy :

Créez une entrée de bac à sable dans votre fichier manifeste.
Dans l'entrée du bac à sable, listez les pages que vous souhaitez exécuter dans le bac à sable.
Utilisez le transfert de messages via postMessage() pour communiquer avec la page sandboxée.

Pour en savoir plus, consultez la documentation Sandboxing Eval.

Documentation complémentaire

Les modifications apportées à la version 2 du fichier manifeste sont conçues pour aider les développeurs à créer des extensions et des applications plus sécurisées et plus robustes. Pour obtenir la liste complète des modifications apportées à la version 2 du fichier manifeste par rapport à la version 1, consultez la documentation sur le fichier manifeste. Pour en savoir plus sur l'utilisation de l'isolation pour isoler le code non sécurisé, consultez l'article Évaluation de l'isolation. Pour en savoir plus sur la stratégie de sécurité du contenu, consultez notre tutoriel sur les extensions et une bonne introduction sur HTML5Rocks.