| OLD | NEW |
| 1 <h1>Tutorial: Migrate to Manifest V2</h1> | 1 <h1>Tutorial: Migrate to Manifest V2</h1> |
| 2 | 2 |
| 3 <p> | 3 <p> |
| 4 Manifest version 1 was deprecated in Chrome 18, | 4 Manifest version 1 was deprecated in Chrome 18, |
| 5 and support will be phased out according to the | 5 and support will be phased out according to the |
| 6 <a href="manifestVersion.html#manifest-v1-support-schedule">manifest version 1 s
upport schedule</a>. | 6 <a href="manifestVersion#manifest-v1-support-schedule">manifest version 1 suppor
t schedule</a>. |
| 7 The changes from version 1 to version 2 | 7 The changes from version 1 to version 2 |
| 8 fall under two broad categories: | 8 fall under two broad categories: |
| 9 API changes and Security changes. | 9 API changes and Security changes. |
| 10 </p> | 10 </p> |
| 11 | 11 |
| 12 <p> | 12 <p> |
| 13 This document provides checklists for migrating your Chrome extensions | 13 This document provides checklists for migrating your Chrome extensions |
| 14 from manifest version 1 to version 2, | 14 from manifest version 1 to version 2, |
| 15 followed by more detailed summaries of what these changes mean and why they were
made. | 15 followed by more detailed summaries of what these changes mean and why they were
made. |
| 16 </p> | 16 </p> |
| (...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 54 <li>Replace with <code>chrome.extension.getViews( { "type" : "tab" } )</co
de>.</li> | 54 <li>Replace with <code>chrome.extension.getViews( { "type" : "tab" } )</co
de>.</li> |
| 55 </ul> | 55 </ul> |
| 56 <li>Does your extension use a background page?</li> | 56 <li>Does your extension use a background page?</li> |
| 57 <ul> | 57 <ul> |
| 58 <li>Replace the <code>background_page</code> property | 58 <li>Replace the <code>background_page</code> property |
| 59 with a <code>background</code> property.</li> | 59 with a <code>background</code> property.</li> |
| 60 <li>Add a <code>scripts</code> or <code>page</code> | 60 <li>Add a <code>scripts</code> or <code>page</code> |
| 61 property that contains the code for the page.</li> | 61 property that contains the code for the page.</li> |
| 62 <li>Add a <code>persistent</code> property and set it | 62 <li>Add a <code>persistent</code> property and set it |
| 63 to <code>false</code> to convert your background page | 63 to <code>false</code> to convert your background page |
| 64 to an <a href="event_pages.html">event page</a></li> | 64 to an <a href="event_pages">event page</a></li> |
| 65 </ul> | 65 </ul> |
| 66 </ul> | 66 </ul> |
| 67 | 67 |
| 68 <h2 id="security-checklist">Security changes checklist</h2> | 68 <h2 id="security-checklist">Security changes checklist</h2> |
| 69 | 69 |
| 70 <ul> | 70 <ul> |
| 71 <li>Are you using inline script blocks in HTML pages?</li> | 71 <li>Are you using inline script blocks in HTML pages?</li> |
| 72 <ul> | 72 <ul> |
| 73 <li>Remove JS code contained within <script> tags | 73 <li>Remove JS code contained within <script> tags |
| 74 and place it within an external JS file.</li> | 74 and place it within an external JS file.</li> |
| 75 </ul> | 75 </ul> |
| 76 <li>Are you using inline event handlers (like onclick, etc)?</li> | 76 <li>Are you using inline event handlers (like onclick, etc)?</li> |
| 77 <ul> | 77 <ul> |
| 78 <li>Remove them from the HTML code, | 78 <li>Remove them from the HTML code, |
| 79 move them into an external JS file and | 79 move them into an external JS file and |
| 80 use <code>addEventListener()</code> instead.</li> | 80 use <code>addEventListener()</code> instead.</li> |
| 81 </ul> | 81 </ul> |
| 82 <li>Does your extension inject content scripts into Web pages | 82 <li>Does your extension inject content scripts into Web pages |
| 83 that need to access resources (like images and scripts) | 83 that need to access resources (like images and scripts) |
| 84 that are contained in the extension’s package?</li> | 84 that are contained in the extension’s package?</li> |
| 85 <ul> | 85 <ul> |
| 86 <li>Define the <a href="manifest/web_accessible_resources.html">web_access
ible_resources</a> | 86 <li>Define the <a href="manifest/web_accessible_resources">web_accessible_
resources</a> |
| 87 property and list the resources | 87 property and list the resources |
| 88 (and optionally a separate Content Security Policy for those resources).
</li> | 88 (and optionally a separate Content Security Policy for those resources).
</li> |
| 89 </ul> | 89 </ul> |
| 90 <li>Does your extension embed external Web pages?</li> | 90 <li>Does your extension embed external Web pages?</li> |
| 91 <ul> | 91 <ul> |
| 92 <li>Define the <a href="manifest/sandbox.html">sandbox</a> property.</li> | 92 <li>Define the <a href="manifest/sandbox">sandbox</a> property.</li> |
| 93 </ul> | 93 </ul> |
| 94 <li>Is your code or library using <code>eval()</code>, new <code>Function()</c
ode>, | 94 <li>Is your code or library using <code>eval()</code>, new <code>Function()</c
ode>, |
| 95 <code>innerHTML</code>, <code>setTimeout()</code>, or otherwise passing stri
ngs | 95 <code>innerHTML</code>, <code>setTimeout()</code>, or otherwise passing stri
ngs |
| 96 of JS code that are dynamically evaluated?</li> | 96 of JS code that are dynamically evaluated?</li> |
| 97 <ul> | 97 <ul> |
| 98 <li>Use <code>JSON.parse()</code> | 98 <li>Use <code>JSON.parse()</code> |
| 99 if you’re parsing JSON code into an object.</li> | 99 if you’re parsing JSON code into an object.</li> |
| 100 <li>Use a CSP-friendly library, | 100 <li>Use a CSP-friendly library, |
| 101 for example, <a href="http://angularjs.org/">AngularJS</a>.</li> | 101 for example, <a href="http://angularjs.org/">AngularJS</a>.</li> |
| 102 <li>Create a sandbox entry in your manifest and | 102 <li>Create a sandbox entry in your manifest and |
| (...skipping 65 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 168 </ul> | 168 </ul> |
| 169 | 169 |
| 170 <h3 id="removed_and_changed">Removed and changed APIs</h3> | 170 <h3 id="removed_and_changed">Removed and changed APIs</h3> |
| 171 | 171 |
| 172 <p> | 172 <p> |
| 173 A few extension APIs have been removed and replaced with new counterparts: | 173 A few extension APIs have been removed and replaced with new counterparts: |
| 174 </p> | 174 </p> |
| 175 | 175 |
| 176 <ul> | 176 <ul> |
| 177 <li>The <code>background_page</code> property has been replaced | 177 <li>The <code>background_page</code> property has been replaced |
| 178 by <a href="background_pages.html">background</a>.</li> | 178 by <a href="background_pages">background</a>.</li> |
| 179 <li>The <code>chrome.self</code> property has been removed, | 179 <li>The <code>chrome.self</code> property has been removed, |
| 180 use <code>chrome.extension</code>.</li> | 180 use <code>chrome.extension</code>.</li> |
| 181 <li>The <code>Port.tab</code> property has been replaced | 181 <li>The <code>Port.tab</code> property has been replaced |
| 182 with <code>Port.sender</code>.</li> | 182 with <code>Port.sender</code>.</li> |
| 183 <li>The <code>chrome.extension.getTabContentses()</code> and the | 183 <li>The <code>chrome.extension.getTabContentses()</code> and the |
| 184 <code>chrome.extension.getExtensionTabs()</code> APIs have been replaced | 184 <code>chrome.extension.getExtensionTabs()</code> APIs have been replaced |
| 185 by <code>chrome.extension.getViews( { "type" : "tab" } )</code>.</li> | 185 by <code>chrome.extension.getViews( { "type" : "tab" } )</code>.</li> |
| 186 </ul> | 186 </ul> |
| 187 | 187 |
| 188 <h2 id="security-summary">Summary of security changes</h2> | 188 <h2 id="security-summary">Summary of security changes</h2> |
| 189 | 189 |
| 190 <p> | 190 <p> |
| 191 There are a number of security-related changes | 191 There are a number of security-related changes |
| 192 that accompany the move from manifest version 1 to version 2. | 192 that accompany the move from manifest version 1 to version 2. |
| 193 Many of these changes stem from Chrome’s adoption of | 193 Many of these changes stem from Chrome’s adoption of |
| 194 <a href="contentSecurityPolicy.html">Content Security Policy</a>; | 194 <a href="contentSecurityPolicy">Content Security Policy</a>; |
| 195 you should read more about this policy to understand its implications. | 195 you should read more about this policy to understand its implications. |
| 196 </p> | 196 </p> |
| 197 | 197 |
| 198 <h3 id="inline_scripts">Inline scripts and event handlers disallowed</h3> | 198 <h3 id="inline_scripts">Inline scripts and event handlers disallowed</h3> |
| 199 | 199 |
| 200 <p> | 200 <p> |
| 201 Due to the use of <a href="contentSecurityPolicy.html">Content Security Policy</
a>, | 201 Due to the use of <a href="contentSecurityPolicy">Content Security Policy</a>, |
| 202 you can no longer use <script> tags that are inline with the HTML content. | 202 you can no longer use <script> tags that are inline with the HTML content. |
| 203 These must be moved to external JS files. | 203 These must be moved to external JS files. |
| 204 In addition, inline event handlers are also not supported. | 204 In addition, inline event handlers are also not supported. |
| 205 For example, suppose you had the following code in your extension: | 205 For example, suppose you had the following code in your extension: |
| 206 </p> | 206 </p> |
| 207 | 207 |
| 208 <pre> | 208 <pre> |
| 209 <html> | 209 <html> |
| 210 <head> | 210 <head> |
| 211 <script> | 211 <script> |
| (...skipping 45 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 257 <p> | 257 <p> |
| 258 There are some scenarios where your extension might embed content | 258 There are some scenarios where your extension might embed content |
| 259 that can be used externally or come from an external source. | 259 that can be used externally or come from an external source. |
| 260 </p> | 260 </p> |
| 261 | 261 |
| 262 <p> | 262 <p> |
| 263 <strong>Extension content in web pages:</strong><br> | 263 <strong>Extension content in web pages:</strong><br> |
| 264 If your extension embeds resources (like images, script, CSS styles, etc) | 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, | 265 that are used in content scripts that are injected into web pages, |
| 266 you need to use the | 266 you need to use the |
| 267 <a href="manifest/web_accessible_resources.html">web_accessible_resources</a> pr
operty | 267 <a href="manifest/web_accessible_resources">web_accessible_resources</a> propert
y |
| 268 to whitelist these resources so that external Web pages can use them: | 268 to whitelist these resources so that external Web pages can use them: |
| 269 </p> | 269 </p> |
| 270 | 270 |
| 271 <pre data-filename="manifest.json"> | 271 <pre data-filename="manifest.json"> |
| 272 { | 272 { |
| 273 ... | 273 ... |
| 274 "<strong>web_accessible_resources</strong>": [ | 274 "<strong>web_accessible_resources</strong>": [ |
| 275 "images/image1.png", | 275 "images/image1.png", |
| 276 "script/myscript.js" | 276 "script/myscript.js" |
| 277 ], | 277 ], |
| (...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 330 <ol> | 330 <ol> |
| 331 <li>Create a sandbox entry in your manifest file.</li> | 331 <li>Create a sandbox entry in your manifest file.</li> |
| 332 <li>In the sandbox entry, | 332 <li>In the sandbox entry, |
| 333 list the pages you want to run in the sandbox.</li> | 333 list the pages you want to run in the sandbox.</li> |
| 334 <li>Use message passing via <code>postMessage()</code> | 334 <li>Use message passing via <code>postMessage()</code> |
| 335 to communicate with the sandboxed page.</li> | 335 to communicate with the sandboxed page.</li> |
| 336 </ol> | 336 </ol> |
| 337 | 337 |
| 338 <p> | 338 <p> |
| 339 For more details on how to do this, | 339 For more details on how to do this, |
| 340 see the <a href="sandboxingEval.html">Sandboxing Eval</a> documentation. | 340 see the <a href="sandboxingEval">Sandboxing Eval</a> documentation. |
| 341 </p> | 341 </p> |
| 342 | 342 |
| 343 <h2 id="further-reading">Further reading</h2> | 343 <h2 id="further-reading">Further reading</h2> |
| 344 | 344 |
| 345 <p> | 345 <p> |
| 346 The changes in manifest version 2 are designed to guide developers | 346 The changes in manifest version 2 are designed to guide developers |
| 347 toward building more secure and robustly-architected extensions and apps. | 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, | 348 To see a complete list of changes from manifest version 1 to version 2, |
| 349 see the <a href="manifestVersion.html">manifest file</a> documentation. | 349 see the <a href="manifestVersion">manifest file</a> documentation. |
| 350 For more information about using sandboxing to isolate unsafe code, | 350 For more information about using sandboxing to isolate unsafe code, |
| 351 read the <a href="sandboxingEval.html">sandboxing eval</a> article. | 351 read the <a href="sandboxingEval">sandboxing eval</a> article. |
| 352 You can learn more about Content Security Policy | 352 You can learn more about Content Security Policy |
| 353 by visiting our extensions-related tutorial and a | 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>. | 354 <a href="http://www.html5rocks.com/en/tutorials/security/content-security-policy
/">good introduction on HTML5Rocks</a>. |
| 355 </p> | 355 </p> |
| 356 | 356 |
| 357 | 357 |
| 358 | 358 |
| 359 | 359 |
| OLD | NEW |