The Wayback Machine - https://web.archive.org/web/20130121133228/http://developer.chrome.com:80/stable/extensions/tut_migration_to_manifest_v2.html

Google Chrome Extensions

Tutorial: Migrate to Manifest V2

Manifest version 1 was deprecated in Chrome 18, and support will be phased out according to the manifest version 1 support schedule. The changes from version 1 to version 2 fall under two broad categories: API changes and Security changes.

This document provides checklists for migrating your Chrome extensions from manifest version 1 to version 2, followed by more detailed summaries of what these changes mean and why they were made.

API changes checklist

Security changes checklist

Summary of API changes

Manifest version 2 introduces a few changes to the browser action and page action APIs, and replaces a few old APIs with newer ones.

Changes to browser actions

The browser actions API introduces some naming changes:

Changes to page actions

Similar to the changes for browser actions, the page actions API has also changed:

Removed and changed APIs

A few extension APIs have been removed and replaced with new counterparts:

Summary of security changes

There are a number of security-related changes that accompany the move from manifest version 1 to version 2. Many of these changes stem from Chrome’s adoption of Content Security Policy; you should read more about this policy to understand its implications.

Inline scripts and event handlers disallowed

Due to the use of Content Security Policy, you can no longer use <script> tags that are inline with the HTML content. These must be moved to external JS files. In addition, inline event handlers are also not supported. For example, suppose you had the following code in your extension: 

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

This code would cause an error at runtime. To fix this, move <script> tag contents to external files and reference them with a src=’path_to_file.js’ attribute.

Similarly, inline event handlers, which are a common occurrence and convenience feature used by many Web developers, will not execute. For example, consider common instances such as: 

<body onload=”initialize()”>
<button onclick=”handleClick()” id=”button1”>

These will not work in manifest V2 extensions. Remove the inline event handlers, place them in your external JS file and use addEventListener() to register event handlers for them instead. For example, in your JS code, use: 

window.addEventListener(“load”, initialize);
...
document.getElementById(“button1”).addEventListener(“click”,handleClick);

This is a much cleaner way of separating your extension’s behavior from its user interface markup.

Embedding content

There are some scenarios where your extension might embed content that can be used externally or come from an external source.

Extension content in web pages:
If your extension embeds resources (like images, script, CSS styles, etc) that are used in content scripts that are injected into web pages, you need to use the web_accessible_resources property to whitelist these resources so that external Web pages can use them: 

{ // manifest file
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

Embedding external content:
The Content Security Policy only allows local script and objects to loaded from your package, which prevents external attackers from introducing unknown code to your extension. However, there are times when you want to load externally served resources, such as jQuery or Google Analytics code. There are two ways to do this:

  1. Download the relevant library locally (like jQuery) and package it with your extension.
  2. You can relax the CSP in a limited way by whitelisting HTTPS origins in the “content_security_policy” section of your manifest. To include a library like Google Analytics, this is the approach to take: 
            { // manifest file
          ...,
          "content_security_policy": "script-src 'self'
          https://ssl.google-analytics.com; object-src 'self'",
          ...
        }

Using dynamic script evaluation

Perhaps one of the biggest changes in the new manifest v2 scheme is that extensions can no longer use dynamic script evaluation techniques like eval() or new Function(), or pass strings of JS code to functions that will cause an eval() to be used, like setTimeout(). In addition, certain commonly used JavaScript libraries, such as Google Maps and certain templating libraries, are known to use some of these techniques.

Chrome provides a sandbox for pages to run in their own origin, which are denied access to chrome.* APIs. In order to use eval() and the like under the new Content Security Policy:

  1. Create a sandbox entry in your manifest file.
  2. In the sandbox entry, list the pages you want to run in the sandbox.
  3. Use message passing via postMessage() to communicate with the sandboxed page.

For more details on how to do this, see the Sandboxing Eval documentation.

Further reading

The changes in manifest version 2 are designed to guide developers toward building more secure and robustly-architected extensions and apps. To see a complete list of changes from manifest version 1 to version 2, see the manifest file documentation. For more information about using sandboxing to isolate unsafe code, read the sandboxing eval article. You can learn more about Content Security Policy by visiting our extensions-related tutorial and a good introduction on HTML5Rocks.