Cette page a été traduite par l'API Cloud Translation.

Tutoriel: Migrer vers Manifest V2

Manifest version 1 était obsolète dans Chrome 18 et ne sera plus pris en charge selon le calendrier de prise en charge de la version 1 du fichier manifeste. Les changements de la version 1 à la version 2 relèvent de deux grandes catégories: les modifications d'API et les modifications de sécurité.

Ce document fournit des checklists pour la migration de vos extensions Chrome de la version 1 vers la version 2 du fichier manifeste, ainsi que des résumés plus détaillés de la signification de ces modifications et de leur raison d'être.

Checklist des modifications apportées à l'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 (il doit désormais s'agir d'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 (il doit désormais s'agir d'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 en 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 pour les 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 (tels que clickserver, etc.) ?
Supprimez-les du code HTML, déplacez-les dans un fichier JS externe et utilisez addEventListener() à la place.
Votre extension injecte-t-elle des scripts de contenu dans des pages Web qui doivent accéder aux ressources (telles que des images et des scripts) contenues dans le package de l'extension ?
Définissez la propriété web_accessible_resources, puis répertoriez les ressources (et éventuellement une Content Security Policy distincte pour celles-ci).
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(), de nouveaux Function(), innerHTML, setTimeout() ou des chaînes de code JavaScript é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 ?
Vous pouvez télécharger la bibliothèque et l'empaqueter dans votre extension, puis la charger à partir du package local.
Ajoutez à la liste d'autorisation le domaine HTTPS qui diffuse la ressource dans la partie "content_security_policy" de votre fichier manifeste.

Résumé des modifications de l'API

Manifest version 2 apporte quelques modifications aux API d'action du navigateur et d'action sur les pages, et remplace quelques anciennes API par de nouvelles.

Modifications apportées aux actions du navigateur

L'API Browser Actions introduit quelques changements de nom:

Remplacement des propriétés browser_actions et chrome.browserActions par leurs équivalents browser_action et chrome.browserAction.
Sous l'ancienne propriété browser_actions, il y avait les propriétés icons, name et popup. Ils ont été remplacés par:
default_icon pour l'icône du badge d'action du navigateur
default_name pour le texte qui apparaît dans l'info-bulle lorsque vous pointez sur le badge
default_popup pour la page HTML qui représente l'interface utilisateur de l'action du navigateur (il doit désormais s'agir d'une chaîne, et non d'un objet).

Modifications apportées aux actions sur la page

Tout comme les modifications apportées aux actions du navigateur, l'API d'actions sur les pages a également changé:

Remplacement des propriétés page_actions et chrome.pageActions par leurs équivalents page_action et chrome.pageAction.
Sous l'ancienne propriété page_actions, il y avait les propriétés icons, name et popup. Ils ont été remplacés par:
default_icon pour l'icône du badge d'action sur la page
default_name pour le texte qui apparaît dans l'info-bulle lorsque vous pointez sur le badge
default_popup pour la page HTML qui représente l'UI de l'action sur la page (il doit désormais s'agir d'une chaîne et non d'un objet).

API supprimées et modifiées

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

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 apportées à la sécurité

Un certain nombre de modifications liées à la sécurité accompagnent le passage de la version 1 du fichier manifeste à la version 2. La plupart de ces modifications sont dues à l'adoption par Chrome de la Content Security Policy. Nous vous recommandons d'en savoir plus sur cette règle pour en comprendre les implications.

Gestionnaires d'événements et scripts intégrés non autorisés

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

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

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

De même, les gestionnaires d'événements intégrés, qui sont une fonctionnalité pratique et d'occurrence courante utilisée par de nombreux développeurs Web, ne s'exécuteront pas. Prenons des exemples courants, tels que les suivants:

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

Elles ne fonctionnent 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 pour eux. Par exemple, dans votre code JS, utilisez:

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

Il s'agit d'une méthode beaucoup plus claire pour 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 pouvant être utilisé en externe ou provenir d'une source externe.

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

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

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

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

Utiliser l'évaluation de script dynamique

L'un des changements les plus importants du nouveau schéma Manifest V2 est que les extensions ne peuvent plus utiliser de techniques d'évaluation de script dynamiques telles que eval() ou le nouveau Function(), ni transmettre des chaînes de code JavaScript à des fonctions entraînant l'utilisation d'un eval(), comme setTimeout(). En outre, certaines bibliothèques JavaScript couramment utilisées, telles que Google Maps et certaines bibliothèques de modèles, utilisent certaines de ces techniques.

Chrome fournit un bac à sable permettant aux pages de s'exécuter dans leur propre origine, à laquelle l'accès au navigateur est refusé*. API Pour utiliser eval() et les éléments similaires dans la nouvelle Content Security Policy:

Créez une entrée de bac à sable dans le fichier manifeste.
Dans l'entrée du bac à sable, listez les pages que vous souhaitez exécuter dans celui-ci.
Utilisez le message en transmettant via postMessage() pour communiquer avec la page en bac à sable.

Pour savoir comment procéder, consultez la documentation sur l'évaluation de l'environnement de bac à sable.

Complément d'informations

Les modifications apportées à Manifest version 2 sont conçues pour guider les développeurs vers la création d'extensions et d'applications plus sécurisées et robustes. Pour afficher la liste complète des modifications apportées entre la version 1 et la version 2, consultez la documentation sur le fichier manifeste. Pour en savoir plus sur l'utilisation du bac à sable pour isoler le code dangereux, consultez l'article sur l'évaluation du bac à sable. Pour en savoir plus sur Content Security Policy, consultez notre tutoriel sur les extensions et une bonne présentation de HTML5Rocks.