chrome/common/extensions/docs/templates/articles/tut_migration_to_manifest_v2.html

   1 <h1>Tutorial: Migrate to Manifest V2</h1>
   2
   3 <p>
   4 Manifest version 1 was deprecated in Chrome 18,
   5 and support will be phased out according to the
   6 <a href="manifestVersion#manifest-v1-support-schedule">manifest version 1 support schedule</a>.
   7 The changes from version 1 to version 2
   8 fall under two broad categories:
   9 API changes and Security changes.
  10 </p>
  11
  12 <p>
  13 This document provides checklists for migrating your Chrome extensions
  14 from manifest version 1 to version 2,
  15 followed by more detailed summaries of what these changes mean and why they were made.
  16 </p>
  17
  18 <h2 id="api-checklist">API changes checklist</h2>
  19
  20 <ul>
  21   <li>Are you using the <code>browser_actions</code> property
  22     or the <code>chrome.browserActions</code> API?</li>
  23     <ul>
  24       <li>Replace <code>browser_actions</code>
  25         with the singular <code>browser_action</code> property.</li>
  26       <li>Replace <code>chrome.browserActions</code> with
  27         <code>chrome.browserAction</code>.</li>
  28       <li>Replace the <code>icons</code> property with <code>default_icon</code>.</li>
  29       <li>Replace the <code>name</code> property with <code>default_title</code>.</li>
  30       <li>Replace the <code>popup</code> property with
  31         <code>default_popup</code> (and it now must be a string).</li>
  32     </ul>
  33   <li>Are you using the <code>page_actions</code> property
  34     or the <code>chrome.pageActions</code> API?</li>
  35     <ul>
  36       <li>Replace <code>page_actions</code> with <code>page_action</code>.</li>
  37       <li>Replace <code>chrome.pageActions</code> with <code>chrome.pageAction</code>.</li>
  38       <li>Replace the <code>icons</code> property with <code>default_icon</code>.</li>
  39       <li>Replace the <code>name</code> property with <code>default_title</code>.</li>
  40       <li>Replace the <code>popup</code> property with
  41         <code>default_popup </code>(and it now must be a string).</li>
  42     </ul>
  43   <li>Are you using the <code>chrome.self</code> property?</li>
  44     <ul>
  45       <li>Replace with <code>chrome.extension</code>.</li>
  46     </ul>
  47   <li>Are you using the <code>Port.tab</code> property?</li>
  48     <ul>
  49       <li>Replace with <code>Port.sender</code>.</li>
  50     </ul>
  51   <li>Are you using the <code>chrome.extension.getTabContentses()</code>
  52     or the <code>chrome.extension.getExtensionTabs()</code> APIs?</li>
  53     <ul>
  54       <li>Replace with <code>chrome.extension.getViews( { "type" : "tab" } )</code>.</li>
  55     </ul>
  56   <li>Does your extension use a background page?</li>
  57     <ul>
  58       <li>Replace the <code>background_page</code> property
  59         with a <code>background</code> property.</li>
  60       <li>Add a <code>scripts</code> or <code>page</code>
  61         property that contains the code for the page.</li>
  62       <li>Add a <code>persistent</code> property and set it
  63         to <code>false</code> to convert your background page
  64         to an <a href="event_pages">event page</a></li>
  65     </ul>
  66 </ul>
  67
  68 <h2 id="security-checklist">Security changes checklist</h2>
  69
  70 <ul>
  71   <li>Are you using inline script blocks in HTML pages?</li>
  72     <ul>
  73       <li>Remove JS code contained within &lt;script> tags
  74         and place it within an external JS file.</li>
  75     </ul>
  76   <li>Are you using inline event handlers (like onclick, etc)?</li>
  77     <ul>
  78       <li>Remove them from the HTML code,
  79         move them into an external JS file and
  80         use <code>addEventListener()</code> instead.</li>
  81     </ul>
  82   <li>Does your extension inject content scripts into Web pages
  83     that need to access resources (like images and scripts)
  84     that are contained in the extension’s package?</li>
  85     <ul>
  86       <li>Define the <a href="manifest/web_accessible_resources">web_accessible_resources</a>
  87         property and list the resources
  88         (and optionally a separate Content Security Policy for those resources).</li>
  89     </ul>
  90   <li>Does your extension embed external Web pages?</li>
  91     <ul>
  92       <li>Define the <a href="manifest/sandbox">sandbox</a> property.</li>
  93     </ul>
  94   <li>Is your code or library using <code>eval()</code>, new <code>Function()</code>,
  95     <code>innerHTML</code>, <code>setTimeout()</code>, or otherwise passing strings
  96     of JS code that are dynamically evaluated?</li>
  97     <ul>
  98       <li>Use <code>JSON.parse()</code>
  99         if you’re parsing JSON code into an object.</li>
 100       <li>Use a CSP-friendly library,
 101         for example, <a href="http://angularjs.org/">AngularJS</a>.</li>
 102       <li>Create a sandbox entry in your manifest and
 103         run the affected code in the sandbox,
 104         using <code>postMessage()</code> to communicate
 105         with the sandboxed page.</li>
 106     </ul>
 107   <li>Are you loading external code,
 108     such as jQuery or Google Analytics?</li>
 109     <ul>
 110       <li>Consider downloading the library and
 111         packaging it in your extension,
 112         then loading it from the local package.</li>
 113       <li>Whitelist the HTTPS domain that serves the resource
 114         in the "content_security_policy" part of your manifest.</li>
 115     </ul>
 116 </ul>
 117
 118 <h2 id="api-summary">Summary of API changes</h2>
 119
 120 <p>
 121 Manifest version 2 introduces a few changes
 122 to the browser action and page action APIs,
 123 and replaces a few old APIs with newer ones.
 124 </p>
 125
 126 <h3 id="browser_actions">Changes to browser actions</h3>
 127
 128 <p>
 129 The browser actions API introduces some naming changes:</p>
 130
 131 <ul>
 132   <li>The <code>browser_actions</code> and
 133     <code>chrome.browserActions</code> properties have been replaced
 134     with their singular counterparts <code>browser_action</code>
 135     and <code>chrome.browserAction</code>.</li>
 136   <li>Under the old <code>browser_actions</code> property,
 137     there were <code>icons</code>, <code>name</code>, and
 138     <code>popup</code> properties.
 139     These have been replaced with:</li>
 140   <ul>
 141     <li><code>default_icon</code> for the browser action badge icon</li>
 142     <li><code>default_name</code> for the text that appears in the tooltip when you hover over the badge</li>
 143     <li><code>default_popup</code> for the HTML page that represents the UI
 144       for the browser action (and this must now be a string, it cannot be an object)</li>
 145   </ul>
 146 </ul>
 147
 148 <h3 id="page_actions">Changes to page actions</h3>
 149
 150 <p>Similar to the changes for browser actions,
 151   the page actions API has also changed:</p>
 152 <ul>
 153   <li>The <code>page_actions</code> and <code>chrome.pageActions</code> properties
 154     have been replaced with their singular counterparts
 155     <code>page_action</code> and <code>chrome.pageAction</code>.</li>
 156   <li>Under the old <code>page_actions</code> property,
 157     there were <code>icons</code>, <code>name</code>,
 158     and <code>popup</code> properties.
 159     These have been replaced with:</li>
 160   <ul>
 161     <li><code>default_icon</code> for the page action badge icon</li>
 162     <li><code>default_name</code> for the text
 163       that appears in the tooltip when you hover over the badge</li>
 164     <li><code>default_popup</code> for the HTML page
 165       that represents the UI for the page action
 166       (and this must now be a string, it cannot be an object)</li>
 167   </ul>
 168 </ul>
 169
 170 <h3 id="removed_and_changed">Removed and changed APIs</h3>
 171
 172 <p>
 173 A few extension APIs have been removed and replaced with new counterparts:
 174 </p>
 175
 176 <ul>
 177   <li>The <code>background_page</code> property has been replaced
 178     by <a href="background_pages">background</a>.</li>
 179   <li>The <code>chrome.self</code> property has been removed,
 180     use <code>chrome.extension</code>.</li>
 181   <li>The <code>Port.tab</code> property has been replaced
 182     with <code>Port.sender</code>.</li>
 183   <li>The <code>chrome.extension.getTabContentses()</code> and the
 184     <code>chrome.extension.getExtensionTabs()</code> APIs have been replaced
 185     by <code>chrome.extension.getViews( { "type" : "tab" } )</code>.</li>
 186 </ul>
 187
 188 <h2 id="security-summary">Summary of security changes</h2>
 189
 190 <p>
 191 There are a number of security-related changes
 192 that accompany the move from manifest version 1 to version 2.
 193 Many of these changes stem from Chrome’s adoption of
 194 <a href="contentSecurityPolicy">Content Security Policy</a>;
 195 you should read more about this policy to understand its implications.
 196 </p>
 197
 198 <h3 id="inline_scripts">Inline scripts and event handlers disallowed</h3>
 199
 200 <p>
 201 Due to the use of <a href="contentSecurityPolicy">Content Security Policy</a>,
 202 you can no longer use &lt;script> tags that are inline with the HTML content.
 203 These must be moved to external JS files.
 204 In addition, inline event handlers are also not supported.
 205 For example, suppose you had the following code in your extension:
 206 </p>
 207
 208 <pre>
 209 &lt;html>
 210 &lt;head>
 211   &lt;script>
 212     function myFunc() { ... }
 213   &lt;/script>
 214 &lt;/head>
 215 &lt;/html>
 216 </pre>
 217
 218 <p>
 219 This code would cause an error at runtime.
 220 To fix this, move &lt;script> tag contents to external files
 221 and reference them with a <code>src=’path_to_file.js’</code> attribute.
 222 </p>
 223
 224 <p>
 225 Similarly, inline event handlers,
 226 which are a common occurrence and convenience feature
 227 used by many Web developers, will not execute.
 228 For example, consider common instances such as:
 229 </p>
 230
 231 <pre>
 232 &lt;body onload="initialize()">
 233 &lt;button onclick="handleClick()" id="button1">
 234 </pre>
 235
 236 <p>
 237 These will not work in manifest V2 extensions.
 238 Remove the inline event handlers,
 239 place them in your external JS file and use <code>addEventListener()</code>
 240 to register event handlers for them instead.
 241 For example, in your JS code, use:
 242 </p>
 243
 244 <pre>
 245 window.addEventListener("load", initialize);
 246 ...
 247 document.getElementById("button1").addEventListener("click",handleClick);
 248 </pre>
 249
 250 <p>
 251 This is a much cleaner way of separating
 252 your extension’s behavior from its user interface markup.
 253 </p>
 254
 255 <h3 id="embedding">Embedding content</h3>
 256
 257 <p>
 258 There are some scenarios where your extension might embed content
 259 that can be used externally or come from an external source.
 260 </p>
 261
 262 <p>
 263 <strong>Extension content in web pages:</strong><br>
 264 If your extension embeds resources (like images, script, CSS styles, etc)
 265 that are used in content scripts that are injected into web pages,
 266 you need to use the
 267 <a href="manifest/web_accessible_resources">web_accessible_resources</a> property
 268 to whitelist these resources so that external Web pages can use them:
 269 </p>
 270
 271 <pre data-filename="manifest.json">
 272 {
 273 ...
 274   "<strong>web_accessible_resources</strong>": [
 275     "images/image1.png",
 276     "script/myscript.js"
 277   ],
 278 ...
 279 }
 280 </pre>
 281
 282 <p>
 283 <strong>Embedding external content:</strong><br>
 284 The Content Security Policy only allows local script
 285 and objects to loaded from your package,
 286 which prevents external attackers from introducing unknown code to your extension.
 287 However, there are times when you want to load externally served resources,
 288 such as jQuery or Google Analytics code.
 289 There are two ways to do this:
 290 </p>
 291
 292 <ol>
 293   <li>Download the relevant library locally (like jQuery)
 294     and package it with your extension.</li>
 295     <li>You can relax the CSP in a limited way by whitelisting HTTPS origins
 296       in the “content_security_policy” section of your manifest.
 297       To include a library like Google Analytics, this is the approach to take:
 298       <pre data-filename="manifest.json">
 299 {
 300   ...,
 301   "content_security_policy": "script-src 'self'
 302   <strong>https://ssl.google-analytics.com</strong>; object-src 'self'",
 303   ...
 304 }
 305 </pre>
 306     </li>
 307 </ol>
 308
 309 <h3 id="using">Using dynamic script evaluation</h3>
 310
 311 <p>
 312 Perhaps one of the biggest changes in the new manifest v2 scheme is
 313 that extensions can no longer use dynamic script evaluation techniques like
 314 <code>eval()</code> or new <code>Function()</code>,
 315 or pass strings of JS code to functions
 316 that will cause an <code>eval()</code> to be used,
 317 like <code>setTimeout()</code>.
 318 In addition, certain commonly used JavaScript libraries,
 319 such as Google Maps and certain templating libraries,
 320 are known to use some of these techniques.
 321 </p>
 322
 323 <p>
 324 Chrome provides a sandbox for pages to run in their own origin,
 325 which are denied access to chrome.* APIs.
 326 In order to use <code>eval()</code>
 327 and the like under the new Content Security Policy:
 328 </p>
 329
 330 <ol>
 331   <li>Create a sandbox entry in your manifest file.</li>
 332   <li>In the sandbox entry,
 333     list the pages you want to run in the sandbox.</li>
 334   <li>Use message passing via <code>postMessage()</code>
 335     to communicate with the sandboxed page.</li>
 336 </ol>
 337
 338 <p>
 339 For more details on how to do this,
 340 see the <a href="sandboxingEval">Sandboxing Eval</a> documentation.
 341 </p>
 342
 343 <h2 id="further-reading">Further reading</h2>
 344
 345 <p>
 346 The changes in manifest version 2 are designed to guide developers
 347 toward building more secure and robustly-architected extensions and apps.
 348 To see a complete list of changes from manifest version 1 to version 2,
 349 see the <a href="manifestVersion">manifest file</a> documentation.
 350 For more information about using sandboxing to isolate unsafe code,
 351 read the <a href="sandboxingEval">sandboxing eval</a> article.
 352 You can learn more about Content Security Policy
 353 by visiting our extensions-related tutorial and a
 354 <a href="http://www.html5rocks.com/en/tutorials/security/content-security-policy/">good introduction on HTML5Rocks</a>.
 355 </p>
 356
 357
 358
 359