OLD | NEW |
---|---|
1 <h1>External Content</h1> | 1 <h1>External Content</h1> |
2 | 2 |
3 | 3 |
4 <p> | 4 <p> |
5 The <a href="app_architecture.html#security">Chrome Apps security model</a> disa llows | 5 The <a href="app_architecture#security">Chrome Apps security model</a> disallows |
6 external content in iframes and | 6 external content in iframes and |
7 the use of inline scripting and <code>eval()</code>. | 7 the use of inline scripting and <code>eval()</code>. |
8 You can override these restrictions, | 8 You can override these restrictions, |
9 but your external content must be isolated from the app. | 9 but your external content must be isolated from the app. |
10 </p> | 10 </p> |
11 | 11 |
12 <p> | 12 <p> |
13 Isolated content cannot directly | 13 Isolated content cannot directly |
14 access the app's data or any of the APIs. | 14 access the app's data or any of the APIs. |
15 Use cross-origin XMLHttpRequests | 15 Use cross-origin XMLHttpRequests |
16 and post-messaging to communicate between the event page and sandboxed content | 16 and post-messaging to communicate between the event page and sandboxed content |
17 and indirectly access the APIs. | 17 and indirectly access the APIs. |
18 </p> | 18 </p> |
19 | 19 |
20 <p class="note"> | 20 <p class="note"> |
21 <b>API Sample: </b> | 21 <b>API Sample: </b> |
22 Want to play with the code? | 22 Want to play with the code? |
23 Check out the | 23 Check out the |
24 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/sandbox" >sandbox</a> sample. | 24 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/sandbox" >sandbox</a> sample. |
25 </p> | 25 </p> |
26 | 26 |
27 <h2 id="external">Referencing external resources</h2> | 27 <h2 id="external">Referencing external resources</h2> |
28 | 28 |
29 <p> | 29 <p> |
30 The <a href="contentSecurityPolicy.html">Content Security Policy</a> used by app s disallows | 30 The <a href="contentSecurityPolicy">Content Security Policy</a> used by apps dis allows |
31 the use of many kinds of remote URLs, so you can't directly reference external | 31 the use of many kinds of remote URLs, so you can't directly reference external |
32 images, stylesheets, or fonts from an app page. Instead, you can use use | 32 images, stylesheets, or fonts from an app page. Instead, you can use use |
33 cross-origin XMLHttpRequests to fetch these resources, | 33 cross-origin XMLHttpRequests to fetch these resources, |
34 and then serve them via <code>blob:</code> URLs. | 34 and then serve them via <code>blob:</code> URLs. |
35 </p> | 35 </p> |
36 | 36 |
37 <h3 id="manifest">Manifest requirement</h3> | 37 <h3 id="manifest">Manifest requirement</h3> |
38 | 38 |
39 <p> | 39 <p> |
40 To be able to do cross-origin XMLHttpRequests, you'll need to add a permission | 40 To be able to do cross-origin XMLHttpRequests, you'll need to add a permission |
(...skipping 20 matching lines...) Expand all Loading... | |
61 xhr.responseType = 'blob'; | 61 xhr.responseType = 'blob'; |
62 xhr.onload = function(e) { | 62 xhr.onload = function(e) { |
63 var img = document.createElement('img'); | 63 var img = document.createElement('img'); |
64 img.src = window.URL.createObjectURL(this.response); | 64 img.src = window.URL.createObjectURL(this.response); |
65 document.body.appendChild(img); | 65 document.body.appendChild(img); |
66 }; | 66 }; |
67 | 67 |
68 xhr.send(); | 68 xhr.send(); |
69 </pre> | 69 </pre> |
70 | 70 |
71 <p>You may want to <a href="offline_apps.html#saving-locally">save</a> | 71 <p>You may want to <a href="offline_apps#saving-locally">save</a> |
72 these resources locally, so that they are available offline.</p> | 72 these resources locally, so that they are available offline.</p> |
73 | 73 |
74 <h2 id="webview">Embed external web pages</h2> | 74 <h2 id="webview">Embed external web pages</h2> |
75 | 75 |
76 <p class="note"> | 76 <p class="note"> |
77 <b>API Sample: </b> | 77 <b>API Sample: </b> |
78 Want to play with the code? Check out the | 78 Want to play with the code? Check out the |
79 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/browser" >browser</a> | 79 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/browser" >browser</a> |
80 sample. | 80 sample. |
81 </p> | 81 </p> |
82 | 82 |
83 <p> | 83 <p> |
84 The <code>webview</code> tag allows you to embed external web content in your | 84 The <code>webview</code> tag allows you to embed external web content in your |
85 app, for example, a web page. It replaces iframes that point to remote URLs, | 85 app, for example, a web page. It replaces iframes that point to remote URLs, |
86 which are disabled inside Chrome Apps. Unlike iframes, the | 86 which are disabled inside Chrome Apps. Unlike iframes, the |
87 <code>webview</code> tag runs in a separate process. This means that an exploit | 87 <code>webview</code> tag runs in a separate process. This means that an exploit |
88 inside of it will still be isolated and won't be able to gain elevated | 88 inside of it will still be isolated and won't be able to gain elevated |
89 privileges. Further, since its storage (cookies, etc.) is isolated from the app, | 89 privileges. Further, since its storage (cookies, etc.) is isolated from the app, |
90 there is no way for the web content to access any of the app's data. | 90 there is no way for the web content to access any of the app's data. |
91 </p> | 91 </p> |
92 | 92 |
93 <h3 id="webview_element">Add webview element</h3> | 93 <h3 id="webview_element">Add webview element</h3> |
94 | 94 |
95 <p> | 95 <p> |
96 Your <code>webview</code> element must include the URL to the source content | 96 Your <code>webview</code> element must include the URL to the source content |
97 and specify its dimensions. | 97 and specify its dimensions. |
98 </p> | 98 </p> |
99 | 99 |
100 <pre data-filename="browser.html"> | 100 <pre data-filename="browser"> |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
101 <webview src="http://news.google.com/" width="640" height="480"></webview> | 101 <webview src="http://news.google.com/" width="640" height="480"></webview> |
102 </pre> | 102 </pre> |
103 | 103 |
104 <h3 id="properties">Update properties</h3> | 104 <h3 id="properties">Update properties</h3> |
105 | 105 |
106 <p> | 106 <p> |
107 To dynamically change the <code>src</code>, <code>width</code> and | 107 To dynamically change the <code>src</code>, <code>width</code> and |
108 <code>height</code> properties of a <code>webview</code> tag, you can either | 108 <code>height</code> properties of a <code>webview</code> tag, you can either |
109 set those properties directly on the JavaScript object, or use the | 109 set those properties directly on the JavaScript object, or use the |
110 <code>setAttribute</code> DOM function. | 110 <code>setAttribute</code> DOM function. |
111 </p> | 111 </p> |
112 | 112 |
113 <pre data-filename="browser.js"> | 113 <pre data-filename="browser.js"> |
114 document.querySelector('#mywebview').src = | 114 document.querySelector('#mywebview').src = |
115 'http://blog.chromium.org/'; | 115 'http://blog.chromium.org/'; |
116 // or | 116 // or |
117 document.querySelector('#mywebview').setAttribute( | 117 document.querySelector('#mywebview').setAttribute( |
118 'src', 'http://blog.chromium.org/'); | 118 'src', 'http://blog.chromium.org/'); |
119 </pre> | 119 </pre> |
120 | 120 |
121 <h2 id="sandboxing">Sandbox local content</h2> | 121 <h2 id="sandboxing">Sandbox local content</h2> |
122 | 122 |
123 <p> | 123 <p> |
124 Sandboxing allows specified pages | 124 Sandboxing allows specified pages |
125 to be served in a sandboxed, unique origin. | 125 to be served in a sandboxed, unique origin. |
126 These pages are then exempt from their Content Security Policy. | 126 These pages are then exempt from their Content Security Policy. |
127 Sandboxed pages can use iframes, inline scripting, | 127 Sandboxed pages can use iframes, inline scripting, |
128 and <code>eval()</code>. | 128 and <code>eval()</code>. |
129 Check out the manifest field description for | 129 Check out the manifest field description for |
130 <a href="manifest/sandbox.html">sandbox</a>. | 130 <a href="manifest/sandbox">sandbox</a>. |
131 </p> | 131 </p> |
132 | 132 |
133 <p> | 133 <p> |
134 It's a trade-off though: | 134 It's a trade-off though: |
135 sandboxed pages can't use the chrome.* APIs. | 135 sandboxed pages can't use the chrome.* APIs. |
136 If you need to do things like <code>eval()</code>, | 136 If you need to do things like <code>eval()</code>, |
137 go this route to be exempt from CSP, | 137 go this route to be exempt from CSP, |
138 but you won't be able to use the cool new stuff. | 138 but you won't be able to use the cool new stuff. |
139 </p> | 139 </p> |
140 | 140 |
141 <h3 id="inline_scripts">Use inline scripts in sandbox</h3> | 141 <h3 id="inline_scripts">Use inline scripts in sandbox</h3> |
142 | 142 |
143 <p> | 143 <p> |
144 Here's a sample sandboxed page | 144 Here's a sample sandboxed page |
145 which uses an inline script and <code>eval()</code>: | 145 which uses an inline script and <code>eval()</code>: |
146 </p> | 146 </p> |
147 | 147 |
148 <pre data-filename="sandboxed.html"> | 148 <pre data-filename="sandboxed"> |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
149 <html> | 149 <html> |
150 <body> | 150 <body> |
151 <h1>Woot</h1> | 151 <h1>Woot</h1> |
152 <script> | 152 <script> |
153 document.write('I am an inline script.<br>'); | 153 document.write('I am an inline script.<br>'); |
154 eval('document.write(\'I am an eval-ed inline script.\');'); | 154 eval('document.write(\'I am an eval-ed inline script.\');'); |
155 </script> | 155 </script> |
156 </body> | 156 </body> |
157 </html> | 157 </html> |
158 </pre> | 158 </pre> |
159 | 159 |
160 <h3 id="include_sandbox">Include sandbox in manifest</h3> | 160 <h3 id="include_sandbox">Include sandbox in manifest</h3> |
161 | 161 |
162 <p> | 162 <p> |
163 You need to include the <code>sandbox</code> field in the manifest | 163 You need to include the <code>sandbox</code> field in the manifest |
164 and list the app pages to be served in a sandbox: | 164 and list the app pages to be served in a sandbox: |
165 </p> | 165 </p> |
166 | 166 |
167 <pre data-filename="manifest.json"> | 167 <pre data-filename="manifest.json"> |
168 "sandbox": { | 168 "sandbox": { |
169 "pages": ["sandboxed.html"] | 169 "pages": ["sandboxed"] |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
170 } | 170 } |
171 </pre> | 171 </pre> |
172 | 172 |
173 <h3 id="opening_sandbox">Opening a sandboxed page in a window</h3> | 173 <h3 id="opening_sandbox">Opening a sandboxed page in a window</h3> |
174 | 174 |
175 <p> | 175 <p> |
176 Just like any other app pages, | 176 Just like any other app pages, |
177 you can create a window that the sandboxed page opens in. | 177 you can create a window that the sandboxed page opens in. |
178 Here's a sample that creates two windows, | 178 Here's a sample that creates two windows, |
179 one for the main app window that isn't sandboxed, | 179 one for the main app window that isn't sandboxed, |
180 and one for the sandboxed page: | 180 and one for the sandboxed page: |
181 </p> | 181 </p> |
182 | 182 |
183 <p class="warning"> | 183 <p class="warning"> |
184 NOTE: | 184 NOTE: |
185 <a href="https://code.google.com/p/chromium/issues/detail?id=154662">issue 15466 2</a> | 185 <a href="https://code.google.com/p/chromium/issues/detail?id=154662">issue 15466 2</a> |
186 is a bug when using sandbox pages to create windows. | 186 is a bug when using sandbox pages to create windows. |
187 The effect is that an error "Uncaught TypeError: Cannot call method | 187 The effect is that an error "Uncaught TypeError: Cannot call method |
188 'initializeAppWindow' of undefined" is output to the developer console | 188 'initializeAppWindow' of undefined" is output to the developer console |
189 and that the app.window.create call does not call the callback function | 189 and that the app.window.create call does not call the callback function |
190 with a window object. However, the sandbox page is created as a new window. | 190 with a window object. However, the sandbox page is created as a new window. |
191 </p> | 191 </p> |
192 | 192 |
193 <pre data-filename="background.js"> | 193 <pre data-filename="background.js"> |
194 chrome.app.runtime.onLaunched.addListener(function() { | 194 chrome.app.runtime.onLaunched.addListener(function() { |
195 chrome.app.window.create('window.html', { | 195 chrome.app.window.create('window', { |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
196 'bounds': { | 196 'bounds': { |
197 'width': 400, | 197 'width': 400, |
198 'height': 400, | 198 'height': 400, |
199 'left': 0, | 199 'left': 0, |
200 'top': 0 | 200 'top': 0 |
201 } | 201 } |
202 }); | 202 }); |
203 | 203 |
204 chrome.app.window.create('sandboxed.html', { | 204 chrome.app.window.create('sandboxed', { |
205 'bounds': { | 205 'bounds': { |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
206 'width': 400, | 206 'width': 400, |
207 'height': 400, | 207 'height': 400, |
208 'left': 400, | 208 'left': 400, |
209 'top': 0 | 209 'top': 0 |
210 } | 210 } |
211 }); | 211 }); |
212 }); | 212 }); |
213 </pre> | 213 </pre> |
214 | 214 |
215 <h3 id="embedding_sandbox">Embedding a sandboxed page in an app page</h3> | 215 <h3 id="embedding_sandbox">Embedding a sandboxed page in an app page</h3> |
216 | 216 |
217 <p>Sandboxed pages can also be embedded within another app page | 217 <p>Sandboxed pages can also be embedded within another app page |
218 using an <code>iframe</code>:</p> | 218 using an <code>iframe</code>:</p> |
219 | 219 |
220 <pre data-filename="window.html"> | 220 <pre data-filename="window"> |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
221 <!DOCTYPE html> | 221 <!DOCTYPE html> |
222 <html> | 222 <html> |
223 <head> | 223 <head> |
224 </head> | 224 </head> |
225 <body> | 225 <body> |
226 <p>I am normal app window.</p> | 226 <p>I am normal app window.</p> |
227 | 227 |
228 <iframe src="sandboxed.html" width="300" height="200"></iframe> | 228 <iframe src="sandboxed" width="300" height="200"></iframe> |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
229 </body> | 229 </body> |
230 </html> | 230 </html> |
231 </pre> | 231 </pre> |
232 | 232 |
233 | 233 |
234 <h2 id="postMessage">Sending messages to sandboxed pages</h2> | 234 <h2 id="postMessage">Sending messages to sandboxed pages</h2> |
235 | 235 |
236 <p> | 236 <p> |
237 There are two parts to sending a message: | 237 There are two parts to sending a message: |
238 you need to post a message from the sender page/window, | 238 you need to post a message from the sender page/window, |
239 and listen for messages on the receiving page/window. | 239 and listen for messages on the receiving page/window. |
240 </p> | 240 </p> |
241 | 241 |
242 <h3 id="post_message">Post message</h3> | 242 <h3 id="post_message">Post message</h3> |
243 | 243 |
244 <p> | 244 <p> |
245 You can use <code>postMessage</code> to communicate | 245 You can use <code>postMessage</code> to communicate |
246 between your app and sandboxed content. | 246 between your app and sandboxed content. |
247 Here's a sample background script | 247 Here's a sample background script |
248 that posts a message to the sandboxed page it | 248 that posts a message to the sandboxed page it |
249 opens: | 249 opens: |
250 </p> | 250 </p> |
251 | 251 |
252 <pre data-filename="background.js"> | 252 <pre data-filename="background.js"> |
253 var myWin = null; | 253 var myWin = null; |
254 | 254 |
255 chrome.app.runtime.onLaunched.addListener(function() { | 255 chrome.app.runtime.onLaunched.addListener(function() { |
256 chrome.app.window.create('sandboxed.html', { | 256 chrome.app.window.create('sandboxed', { |
257 'bounds': { | 257 'bounds': { |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
258 'width': 400, | 258 'width': 400, |
259 'height': 400 | 259 'height': 400 |
260 } | 260 } |
261 }, function(win) { | 261 }, function(win) { |
262 myWin = win; | 262 myWin = win; |
263 myWin.contentWindow.postMessage('Just wanted to say hey.', '*'); | 263 myWin.contentWindow.postMessage('Just wanted to say hey.', '*'); |
264 }); | 264 }); |
265 }); | 265 }); |
266 </pre> | 266 </pre> |
267 | 267 |
(...skipping 12 matching lines...) Expand all Loading... | |
280 To find out more, | 280 To find out more, |
281 see <a href="https://developer.mozilla.org/en/DOM/window.postMessage">window.pos tMessage</a>. | 281 see <a href="https://developer.mozilla.org/en/DOM/window.postMessage">window.pos tMessage</a>. |
282 </p> | 282 </p> |
283 | 283 |
284 <h3 id="listen_message">Listen for message</h3> | 284 <h3 id="listen_message">Listen for message</h3> |
285 | 285 |
286 <p> | 286 <p> |
287 Here's a sample message receiver | 287 Here's a sample message receiver |
288 that gets added to your sandboxed page: | 288 that gets added to your sandboxed page: |
289 </p> | 289 </p> |
290 | 290 |
mkearney1
2014/04/09 19:43:30
Keep .html as it refers to a filename.
| |
291 <pre data-filename="sandboxed.html"> | 291 <pre data-filename="sandboxed"> |
292 var messageHandler = function(e) { | 292 var messageHandler = function(e) { |
293 console.log('Background script says hello.', e.data); | 293 console.log('Background script says hello.', e.data); |
294 }; | 294 }; |
295 | 295 |
296 window.addEventListener('message', messageHandler); | 296 window.addEventListener('message', messageHandler); |
297 </pre> | 297 </pre> |
298 | 298 |
299 <p class="backtotop"><a href="#top">Back to top</a></p> | 299 <p class="backtotop"><a href="#top">Back to top</a></p> |
OLD | NEW |