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.URL.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 which uses an inline script and <code>eval()</code>:
 145 </p>
 146
 147 <pre data-filename="sandboxed.html">
 148 &lt;html>
 149   &lt;body>
 150     &lt;h1>Woot&lt;/h1>
 151     &lt;script>
 152       eval('console.log(\'I am an eval-ed inline script.\')');
 153     &lt;/script>
 154   &lt;/body>
 155 &lt;/html>
 156 </pre>
 157
 158 <h3 id="include_sandbox">Include sandbox in manifest</h3>
 159
 160 <p>
 161 You need to include the <code>sandbox</code> field in the manifest
 162 and list the app pages to be served in a sandbox:
 163 </p>
 164
 165 <pre data-filename="manifest.json">
 166 "sandbox": {
 167   "pages": ["sandboxed.html"]
 168 }
 169 </pre>
 170
 171 <h3 id="opening_sandbox">Opening a sandboxed page in a window</h3>
 172
 173 <p>
 174 Just like any other app pages,
 175 you can create a window that the sandboxed page opens in.
 176 Here's a sample that creates two windows,
 177 one for the main app window that isn't sandboxed,
 178 and one for the sandboxed page:
 179 </p>
 180
 181 <p class="warning">
 182 NOTE:
 183 <a href="https://code.google.com/p/chromium/issues/detail?id=154662">issue 154662</a>
 184 is a bug when using sandbox pages to create windows.
 185 The effect is that an error "Uncaught TypeError: Cannot call method
 186 'initializeAppWindow' of undefined" is output to the developer console
 187 and that the app.window.create call does not call the callback function
 188 with a window object. However, the sandbox page is created as a new window.
 189 </p>
 190
 191 <pre data-filename="background.js">
 192 chrome.app.runtime.onLaunched.addListener(function() {
 193   chrome.app.window.create('window.html', {
 194     'bounds': {
 195       'width': 400,
 196       'height': 400,
 197       'left': 0,
 198       'top': 0
 199     }
 200   });
 201
 202   chrome.app.window.create('sandboxed.html', {
 203     'bounds': {
 204       'width': 400,
 205       'height': 400,
 206       'left': 400,
 207       'top': 0
 208     }
 209   });
 210 });
 211 </pre>
 212
 213 <h3 id="embedding_sandbox">Embedding a sandboxed page in an app page</h3>
 214
 215 <p>Sandboxed pages can also be embedded within another app page
 216   using an <code>iframe</code>:</p>
 217
 218 <pre data-filename="window.html">
 219 &lt;!DOCTYPE html>
 220 &lt;html>
 221 &lt;head>
 222 &lt;/head>
 223   &lt;body>
 224     &lt;p>I am normal app window.&lt;/p>
 225
 226     &lt;iframe src="sandboxed.html" width="300" height="200">&lt;/iframe>
 227   &lt;/body>
 228 &lt;/html>
 229 </pre>
 230
 231
 232 <h2 id="postMessage">Sending messages to sandboxed pages</h2>
 233
 234 <p>
 235 There are two parts to sending a message:
 236 you need to post a message from the sender page/window,
 237 and listen for messages on the receiving page/window.
 238 </p>
 239
 240 <h3 id="post_message">Post message</h3>
 241
 242 <p>
 243 You can use <code>postMessage</code> to communicate
 244 between your app and sandboxed content.
 245 Here's a sample background script
 246 that posts a message to the sandboxed page it
 247 opens:
 248 </p>
 249
 250 <pre data-filename="background.js">
 251 var myWin = null;
 252
 253 chrome.app.runtime.onLaunched.addListener(function() {
 254   chrome.app.window.create('sandboxed.html', {
 255     'bounds': {
 256       'width': 400,
 257       'height': 400
 258     }
 259   }, function(win) {
 260        myWin = win;
 261        myWin.contentWindow.postMessage('Just wanted to say hey.', '*');
 262      });
 263 });
 264 </pre>
 265
 266 <p>
 267 Generally speaking on the web,
 268 you want to specify the exact origin
 269 from where the message is sent.
 270 Chrome Apps have no access
 271 to the unique origin of sandboxed content,
 272 so you can only whitelist all origins
 273 as acceptable origins ('*').
 274 On the receiving end,
 275 you generally want to check the origin;
 276 but since Chrome Apps content is contained,
 277 it isn't necessary.
 278 To find out more,
 279 see <a href="https://developer.mozilla.org/en/DOM/window.postMessage">window.postMessage</a>.
 280 </p>
 281
 282 <h3 id="listen_message">Listen for message</h3>
 283
 284 <p>
 285 Here's a sample message receiver
 286 that gets added to your sandboxed page:
 287 </p>
 288
 289 <pre data-filename="sandboxed.html">
 290 var messageHandler = function(e) {
 291   console.log('Background script says hello.', e.data);
 292 };
 293
 294 window.addEventListener('message', messageHandler);
 295 </pre>
 296
 297 <p class="backtotop"><a href="#top">Back to top</a></p>