{"id":7102,"date":"2014-04-10T21:07:27","date_gmt":"2014-04-11T04:07:27","guid":{"rendered":"http:\/\/blog.mozilla.org\/addons\/?p=7102"},"modified":"2014-04-11T12:15:07","modified_gmt":"2014-04-11T19:15:07","slug":"changes-to-unsafewindow-for-the-add-on-sdk","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/addons\/2014\/04\/10\/changes-to-unsafewindow-for-the-add-on-sdk\/","title":{"rendered":"Changes to unsafeWindow for the Add-on SDK"},"content":{"rendered":"

In Firefox 30 the Add-on SDK is making a change to the execution environment for content scripts. While this change will not affect most add-ons, some patterns will no longer work. Specifically, content scripts will no longer be able to use unsafeWindow<\/code> or window.wrappedJSObject<\/code> to make JavaScript objects available to content. The more common pattern of accessing objects in the page directly via unsafeWindow<\/code> will continue to work as expected.<\/p>\n

What we’re introducing instead are some new APIs that you can use to share functions and objects with content explicitly. While you’re working on migrating to these new APIs, there’s a mechanism you can use to switch your add-on back to the old behavior as a short-term measure.<\/p>\n

<\/a>Who’s affected?<\/h2>\n

Add-on SDK-based add-ons that use unsafeWindow<\/code> or window.wrappedJSObject<\/code> in content scripts to share JavaScript objects with the scripts loaded by a web page will be broken by this change.<\/em><\/p>\n

By default, content scripts and the scripts loaded into web pages are insulated from each other. They can both see the DOM, but content scripts can’t access objects defined by page scripts, and page scripts can’t access objects defined by content scripts:<\/p>\n

\/\/ content-script.js\r\nvar button = document.getElementById(\"show-page-script-var\");\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access object defined in page script\r\n  console.log(window.pageScriptObject.greeting);        \/\/ undefined\r\n}, false);\r\n\r\nwindow.contentScriptObject = {\"greeting\" : \"hello from add-on\"};<\/pre>\n
\/\/ page-script.js\r\nvar button = document.getElementById(\"show-content-script-var\");\r\n\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access object defined by content script\r\n  console.log(window.contentScriptObject.greeting);     \/\/ undefined\r\n}, false);\r\n\r\n\/\/ define object to be accessed by content script\r\nwindow.pageScriptObject = {\"greeting\" : \"hello from web page\"};<\/pre>\n
Sometimes a content script wants to break through this insulation, and to do that it can use unsafeWindow<\/code> (or window.wrappedJSObject<\/code>, which is identical):<\/p>\n
\/\/ content-script.js\r\nvar button = document.getElementById(\"show-page-script-var\");\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access object defined in page script\r\n  console.log(unsafeWindow.pageScriptObject.greeting);  \/\/ \"hello from web page\"\r\n}, false);\r\n\r\nunsafeWindow.contentScriptObject = {\"greeting\" : \"hello from add-on\"};<\/pre>\n
\/\/ page-script.js\r\nvar button = document.getElementById(\"show-content-script-var\");\r\n\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access object defined by content script\r\n  console.log(window.contentScriptObject.greeting);     \/\/ \"hello from add-on\"\r\n}, false);\r\n\r\nwindow.pageScriptObject = {\"greeting\" : \"hello from web page\"};<\/pre>\n
From Firefox 30 onwards, this mechanism won’t work any more to share objects from the content script to the page script:<\/p>\n
\/\/ content-script.js\r\nvar button = document.getElementById(\"show-page-script-var\");\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access object defined in page script\r\n  console.log(unsafeWindow.pageScriptObject.greeting);  \/\/ \"hello from web page\"\r\n}, false);\r\n\r\nunsafeWindow.contentScriptObject = {\"greeting\" : \"hello from add-on\"};\r\nunsafeWindow.contentScriptPrimitive = 42;<\/pre>\n
\/\/ page-script.js\r\nvar button = document.getElementById(\"show-content-script-var\");\r\n\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access primitive defined by content script\r\n  console.log(window.contentScriptPrimitive);            \/\/ 42\r\n  \/\/ access object defined by content script\r\n  console.log(window.contentScriptObject.greeting);     \/\/ undefined\r\n}, false);\r\n\r\nwindow.pageScriptObject = {\"greeting\" : \"hello from web page\"};<\/pre>\n
Again, the use of unsafeWindow<\/code> to access variables defined in the page script is unaffected, so this change is asymmetric. Content scripts can still access page objects using unsafeWindow<\/code>, but not vice versa.<\/em><\/p>\n
Also note that the content script will still be able to share primitive values with the page using unsafeWindow<\/code>, just not objects.<\/p>\n
If the page script tries to read a variable defined using unsafeWindow<\/code>, it will get the value undefined<\/code>. If it tries to write to such a variable, the browser will throw an exception with this message: “Permission denied to access property [name of the property]”.<\/p>\n
The workaround<\/h2>\n
In the short term, there’s a new option in package.json<\/code> called “unsafe-content-script” under the “permissions” key. By setting it to true<\/code> you can revert to the old behavior:<\/p>\n
\"permissions\": {\r\n  \"unsafe-content-script\": true\r\n}\r\n<\/code><\/pre>\n
However, this is only a temporary fix to enable your add-on to keep working while you update to the new APIs. We will deprecate and eventually remove this flag.<\/p>\n
The real fix<\/h2>\n
The real fix is to use three new APIs to share objects and functions with web content: cloneInto()<\/code><\/a>, exportFunction()<\/code><\/a>, and createObjectIn()<\/code><\/a>. All three of these functions are made available to content scripts as globals.<\/p>\n
<\/a>cloneInto()<\/h3>\n
You can use cloneInto()<\/code> to clone an object from the content script’s context into the page script’s context. cloneInto()<\/code> creates a structured clone<\/a> of the object in the target context, and returns a reference to the clone. You can then assign that to a property of the target window, and the page script can access it:<\/p>\n
\/\/ content-script.js\r\ncontentScriptObject = {\"greeting\" : \"hello from add-on\"};\r\nunsafeWindow.contentScriptObject = cloneInto(contentScriptObject, unsafeWindow);<\/pre>\n
\/\/ page-script.js\r\nvar button = document.getElementById(\"show-content-script-var\");\r\n\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access object defined by content script\r\n  console.log(window.contentScriptObject.greeting);     \/\/ \"hello from add-on\"\r\n}, false);<\/pre>\n
You can also assign the reference to an object you’ve created using createObjectIn()<\/code>:<\/p>\n
var foo = createObjectIn(unsafeWindow, {defineAs: \"foo\"});\r\nvar contentScriptObject = {\"greeting\" : \"hello from add-on\"};\r\nunsafeWindow.foo.contentScriptObject = cloneInto(contentScriptObject, unsafeWindow);<\/pre>\n
\/\/ page-script.js\r\nvar button = document.getElementById(\"show-content-script-var\");\r\n\r\nbutton.addEventListener(\"click\", function() {\r\n  \/\/ access object defined by content script\r\n  console.log(window.foo.contentScriptObject.greeting); \/\/ \"hello from add-on\"\r\n}, false);<\/pre>\n
<\/a>exportFunction()<\/h3>\n
You can use exportFunction()<\/code> to expose a function from a content script to a page script. In this way a function defined in a content script can be called by the page script. Any non-native arguments, and the return value, are cloned<\/a> into the page script’s context.<\/p>\n
You can export the function to the target’s window<\/code> object:<\/p>\n
\/\/ content-script.js\r\nvar salutation = \"hello, \";\r\nfunction greetme(user) {\r\n  return salutation + user;\r\n}\r\n\r\nexportFunction(greetme, unsafeWindow, {defineAs: \"greetme\"});<\/pre>\n
\/\/ page-script.js\r\nvar button = document.getElementById(\"call-content-script-function\");\r\n\r\nbutton.addEventListener(\"click\", function() {\r\n  console.log(window.greetme(\"page script\"));           \/\/ \"hello, page script\"\r\n}, false);<\/pre>\n
You can also export the function to an object you’ve created in the page context using createObjectIn()<\/code>. This code creates a new object in the page’s context called foo<\/code>, and attaches the greetme()<\/code> function to that object:<\/p>\n
\/\/ content-script.js\r\nvar salutation = \"hello, \";\r\nfunction greetme(user) {\r\n  return salutation + user;\r\n}\r\n\r\nvar foo = createObjectIn(unsafeWindow, {defineAs: \"foo\"});\r\nexportFunction(greetme, foo, {defineAs: \"greetme\"});<\/pre>\n
\/\/ page-script.js\r\nvar button = document.getElementById(\"call-content-script-function\");\r\n\r\nbutton.addEventListener(\"click\", function() {\r\n  console.log(window.foo.greetme(\"page script\"));\r\n}, false);<\/pre>\n
<\/a>createObjectIn()<\/h3>\n
You can use createObjectIn()<\/code> to create a new object in the page script’s context. You can then export objects and functions to that object, instead of the target scope’s global window. See the previous sections for some examples of this.<\/p>\n
<\/a>Structured cloning<\/h3>\n
These functions use the structured clone algorithm<\/a> to clone objects into the page context. This is more capable than JSON serialization, but still has some serious limitations. Most notably, you can’t clone functions, so you can’t export functions that take functions as arguments (such as callbacks) and functions that return functions. However, we’re working on adding better support at least for common patterns like callbacks.<\/p>\n
<\/a>More details<\/h2>\n
To learn more about the new APIs see the reference documentation:<\/p>\n