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

Tutoriel: Migrer vers Manifest V2

La version 1 du fichier manifeste a été abandonnée dans Chrome 18. Elle ne sera plus prise en charge progressivement conformément au calendrier de prise en charge de 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 apportées à l'API et les modifications apportées à la sécurité.

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

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 ?
Remplacez par chrome.extension.
Utilisez-vous la propriété Port.tab ?
Remplacez par Port.sender.
Utilisez-vous les API chrome.extension.getTabContentses() ou chrome.extension.getExtensionTabs() ?
Remplacez par chrome.extension.getViews( { "type" : "tab" } ).
Votre extension utilise-t-elle une page de fond ?
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 de fond 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 JavaScript 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 addEventListener() à la place.
Votre extension injecte-t-elle des scripts de contenu dans les pages Web qui doivent accéder aux ressources (comme les images et les scripts) contenues dans le package de l'extension ?
Définissez la propriété web_accessible_resources et listez les ressources (et éventuellement une règle 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 utilise-t-il eval(), le nouveau Function(), innerHTML, setTimeout() ou transmet-il autrement des chaînes de code JS évaluées dynamiquement ?
Utilisez JSON.parse() si vous analysez du code JSON dans un objet.
Utilisez une bibliothèque compatible avec le 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 la empaqueter dans votre extension, puis de la charger à partir du package local.
Ajoutez le domaine HTTPS qui diffuse la ressource à la liste d'autorisation dans la section "content_security_policy" de votre fichier manifeste.

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

La version 2 du fichier manifeste apporte quelques modifications aux API d'action du navigateur et d'action de la page, et remplace quelques anciennes API par de nouvelles.

Modifications apportées aux actions du navigateur

L'API Browser Actions introduit quelques modifications de dénomination:

Les propriétés browser_actions et chrome.browserActions ont été remplacées par leurs homologues singuliers 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 s'affiche dans l'info-bulle lorsque vous pointez sur le badge
default_popup pour la page HTML représentant l'UI de l'action du navigateur (qui doit désormais être une chaîne, et non un objet)

Modifications apportées aux actions sur la page

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.
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 de 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 la 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é

Un certain nombre de modifications liées à la sécurité accompagnent le passage de la version 1 du fichier manifeste à la version 2. De nombreuses modifications découlent de l'adoption par Chrome du Content Security Policy. Nous vous invitons à en savoir plus sur ce règlement pour comprendre ses implications.

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

En raison de l'utilisation de la stratégie de sécurité du contenu, vous ne pouvez plus utiliser de balises <script> intégrées au contenu HTML. Ils doivent être déplacés vers des fichiers JS externes. De plus, les gestionnaires d'événements intégrés ne sont pas non plus acceptés. Par exemple, imaginons que le code suivant figure 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 des balises <script> vers des fichiers externes et référencez-les à l'aide d'un attribut src='path_to_file.js'.

De même, les gestionnaires d'événements intégrés, qui sont un événement courant et une fonctionnalité pratique utilisée par de nombreux développeurs Web, ne s'exécutent pas. Par exemple, considérons des cas courants tels que:

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

Ils 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 les enregistrer à la place. Par exemple, dans votre code JavaScript, utilisez:

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

Il s'agit d'un moyen beaucoup plus propre de séparer le comportement de votre extension de son balisage d'interface utilisateur.

Intégrer du contenu

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

Contenu de l'extension dans les pages Web:si votre extension intègre des ressources (images, scripts, 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 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égration de contenu externe:la stratégie de sécurité du contenu n'autorise que 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 arrive que vous souhaitiez charger des ressources diffusées en externe, telles que jQuery ou le code Google Analytics. Pour cela, vous pouvez procéder de deux façons :

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

Utiliser l'évaluation dynamique des scripts

L'un des plus grands changements du nouveau schéma Manifest V2 est que les extensions ne peuvent plus utiliser de techniques d'évaluation de script dynamique telles que eval() ou le nouveau Function(), ni transmettre des chaînes de code JavaScript à des fonctions qui entraîneront l'utilisation d'un 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 permettant aux pages de s'exécuter dans leur propre origine, à laquelle Chrome n'est pas autorisé à accéder*. API Pour utiliser eval() et d'autres éléments dans la nouvelle stratégie de sécurité du contenu:

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 la transmission de messages via postMessage() pour communiquer avec la page en bac à sable.

Pour en savoir plus, consultez la documentation sur l'évaluation de l'environnement de simulation.

Documentation complémentaire

Les modifications apportées à la version 2 du fichier manifeste sont conçues pour guider les développeurs vers la création d'extensions et d'applications plus sécurisées et à architecture robuste. Pour obtenir la liste complète des modifications apportées de la version 1 du fichier manifeste à la version 2, consultez la documentation sur le fichier manifeste. Pour en savoir plus sur l'utilisation de l'isolation pour isoler le code dangereux, consultez l'article Évaluation de l'isolation. Pour en savoir plus sur le règlement sur la sécurité des contenus, consultez notre tutoriel sur les extensions et une bonne introduction sur HTML5Rocks.