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 |