src/chrome/common/extensions/docs/templates/articles/app_external.html

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