<!DOCTYPE html><!-- This page is a placeholder for generated extensions api doc. Note:
1) The <head> information in this page is significant, should be uniform
across api docs and should be edited only with knowledge of the
templating mechanism.
3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
browser, it will be re-generated from the template, json schema and
authored overview content.
4) The <body>.innerHTML is also generated by an offline step so that this
page may easily be indexed by search engines.
--><html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link href="css/ApiRefStyles.css" rel="stylesheet" type="text/css">
<link href="css/print.css" rel="stylesheet" type="text/css" media="print">
<script type="text/javascript" src="../../../third_party/jstemplate/jstemplate_compiled.js">
</script>
<script type="text/javascript" src="js/api_page_generator.js"></script>
<script type="text/javascript" src="js/bootstrap.js"></script>
<script type="text/javascript" src="js/sidebar.js"></script>
<title>Permission Warnings - Google Chrome Extensions - Google Code</title></head>
<body> <div id="gc-container" class="labs">
<div id="devModeWarning">
You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
</div>
<!-- SUBTEMPLATES: DO NOT MOVE FROM THIS LOCATION -->
<!-- In particular, sub-templates that recurse, must be used by allowing
jstemplate to make a copy of the template in this section which
are not operated on by way of the jsskip="true" -->
<div style="display:none">
<!-- VALUE -->
<div id="valueTemplate">
<dt>
<var>paramName</var>
<em>
<!-- TYPE -->
<div style="display:inline">
(
<span class="optional">optional</span>
<span class="enum">enumerated</span>
<span id="typeTemplate">
<span>
<a> Type</a>
</span>
<span>
<span>
array of <span><span></span></span>
</span>
<span>paramType</span>
<span></span>
</span>
</span>
)
</div>
</em>
</dt>
<dd class="todo">
Undocumented.
</dd>
<dd>
Description of this parameter from the json schema.
</dd>
<dd>
This parameter was added in version
<b><span></span></b>.
You must omit this parameter in earlier versions,
and you may omit it in any version. If you require this
parameter, the manifest key
<a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a>
can ensure that your extension won't be run in an earlier browser version.
</dd>
<!-- OBJECT PROPERTIES -->
<dd>
<dl>
<div>
<div>
</div>
</div>
</dl>
</dd>
<!-- OBJECT METHODS -->
<dd>
<div></div>
</dd>
<!-- OBJECT EVENT FIELDS -->
<dd>
<div></div>
</dd>
<!-- FUNCTION PARAMETERS -->
<dd>
<div></div>
</dd>
</div> <!-- /VALUE -->
<div id="functionParametersTemplate">
<h5>Parameters</h5>
<dl>
<div>
<div>
</div>
</div>
</dl>
</div>
</div> <!-- /SUBTEMPLATES -->
<a id="top"></a>
<div id="skipto">
<a href="#gc-pagecontent">Skip to page content</a>
<a href="#gc-toc">Skip to main navigation</a>
</div>
<!-- API HEADER -->
<table id="header" width="100%" cellspacing="0" border="0">
<tbody><tr>
<td valign="middle"><a href="http://code.google.com/"><img src="images/code_labs_logo.gif" height="43" width="161" alt="Google Code Labs" style="border:0; margin:0;"></a></td>
<td valign="middle" width="100%" style="padding-left:0.6em;">
<form action="http://www.google.com/cse" id="cse" style="margin-top:0.5em">
<div id="gsc-search-box">
<input type="hidden" name="cx" value="002967670403910741006:61_cvzfqtno">
<input type="hidden" name="ie" value="UTF-8">
<input type="text" name="q" value="" size="55">
<input class="gsc-search-button" type="submit" name="sa" value="Search">
<br>
<span class="greytext">e.g. "page action" or "tabs"</span>
</div>
</form>
<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript">google.load("elements", "1", {packages: "transliteration"});</script>
<script type="text/javascript" src="http://www.google.com/coop/cse/t13n?form=cse&t13n_langs=en"></script>
<script type="text/javascript" src="http://www.google.com/coop/cse/brand?form=cse&lang=en"></script>
</td>
</tr>
</tbody></table>
<div id="codesiteContent" class="">
<a id="gc-topnav-anchor"></a>
<div id="gc-topnav">
<h1>Google Chrome Extensions (<a href="http://code.google.com/labs/">Labs</a>)</h1>
<ul id="home" class="gc-topnav-tabs">
<li id="home_link">
<a href="index.html" title="Google Chrome Extensions home page">Home</a>
</li>
<li id="docs_link">
<a href="docs.html" title="Official Google Chrome Extensions documentation">Docs</a>
</li>
<li id="faq_link">
<a href="faq.html" title="Answers to frequently asked questions about Google Chrome Extensions">FAQ</a>
</li>
<li id="samples_link">
<a href="samples.html" title="Sample extensions (with source code)">Samples</a>
</li>
<li id="group_link">
<a href="http://groups.google.com/a/chromium.org/group/chromium-extensions" title="Google Chrome Extensions developer forum">Group</a>
</li>
</ul>
</div> <!-- end gc-topnav -->
<div class="g-section g-tpl-170">
<!-- SIDENAV -->
<div class="g-unit g-first" id="gc-toc">
<ul>
<li><a href="getstarted.html">Getting Started</a></li>
<li><a href="overview.html">Overview</a></li>
<li><a href="whats_new.html">What's New?</a></li>
<li><h2><a href="devguide.html">Developer's Guide</a></h2>
<ul>
<li>Browser UI
<ul>
<li><a href="browserAction.html">Browser Actions</a></li>
<li><a href="contextMenus.html">Context Menus</a></li>
<li><a href="notifications.html">Desktop Notifications</a></li>
<li><a href="omnibox.html">Omnibox</a></li>
<li><a href="options.html">Options Pages</a></li>
<li><a href="override.html">Override Pages</a></li>
<li><a href="pageAction.html">Page Actions</a></li>
</ul>
</li>
<li>Browser Interaction
<ul>
<li><a href="bookmarks.html">Bookmarks</a></li>
<li><a href="cookies.html">Cookies</a></li>
<li><a href="events.html">Events</a></li>
<li><a href="history.html">History</a></li>
<li><a href="management.html">Management</a></li>
<li><a href="tabs.html">Tabs</a></li>
<li><a href="windows.html">Windows</a></li>
</ul>
</li>
<li>Implementation
<ul>
<li><a href="a11y.html">Accessibility</a></li>
<li><a href="background_pages.html">Background Pages</a></li>
<li><a href="content_scripts.html">Content Scripts</a></li>
<li><a href="xhr.html">Cross-Origin XHR</a></li>
<li><a href="idle.html">Idle</a></li>
<li><a href="i18n.html">Internationalization</a></li>
<li><a href="messaging.html">Message Passing</a></li>
<li><a href="npapi.html">NPAPI Plugins</a></li>
</ul>
</li>
<li>Finishing
<ul>
<li><a href="hosting.html">Hosting</a></li>
<li><a href="external_extensions.html">Other Deployment Options</a></li>
</ul>
</li>
</ul>
</li>
<li><h2><a href="apps.html">Packaged Apps</a></h2></li>
<li><h2><a href="tutorials.html">Tutorials</a></h2>
<ul>
<li><a href="tut_debugging.html">Debugging</a></li>
<li><a href="tut_analytics.html">Google Analytics</a></li>
<li><a href="tut_oauth.html">OAuth</a></li>
</ul>
</li>
<li><h2>Reference</h2>
<ul>
<li>Formats
<ul>
<li><a href="manifest.html">Manifest Files</a></li>
<li><a href="match_patterns.html">Match Patterns</a></li>
</ul>
</li>
<li class="leftNavSelected">Permission Warnings</li>
<li><a href="api_index.html">chrome.* APIs</a></li>
<li><a href="api_other.html">Other APIs</a></li>
</ul>
</li>
<li><h2><a href="samples.html">Samples</a></h2></li>
<div class="line"> </div>
<li><h2>More</h2>
<ul>
<li><a href="http://code.google.com/chrome/webstore/docs/index.html">Chrome Web Store</a></li>
<li><a href="http://code.google.com/chrome/apps/docs/developers_guide.html">Hosted Apps</a></li>
<li><a href="themes.html">Themes</a></li>
</ul>
</li>
</ul>
</div>
<script>
initToggles();
</script>
<div class="g-unit" id="gc-pagecontent">
<div id="pageTitle">
<h1 class="page_title">Permission Warnings</h1>
</div>
<!-- TABLE OF CONTENTS -->
<div id="toc">
<h2>Contents</h2>
<ol>
<li>
<a href="#examples"> Examples of permission warnings </a>
<ol>
<li style="display: none; ">
<a>h3Name</a>
</li>
</ol>
</li><li>
<a href="#warnings"> Warnings and their triggers </a>
<ol>
<li style="display: none; ">
<a>h3Name</a>
</li>
</ol>
</li><li>
<a href="#nowarning"> Permissions that don't cause warnings </a>
<ol>
<li style="display: none; ">
<a>h3Name</a>
</li>
</ol>
</li><li>
<a href="#test"> Testing permission warnings </a>
<ol>
<li style="display: none; ">
<a>h3Name</a>
</li>
</ol>
</li>
<li style="display: none; ">
<a href="#apiReference">API reference</a>
<ol>
<li>
<a href="#properties">Properties</a>
<ol>
<li>
<a href="#property-anchor">propertyName</a>
</li>
</ol>
</li>
<li>
<a>Methods</a>
<ol>
<li>
<a href="#method-anchor">methodName</a>
</li>
</ol>
</li>
<li>
<a>Events</a>
<ol>
<li>
<a href="#event-anchor">eventName</a>
</li>
</ol>
</li>
<li>
<a href="#types">Types</a>
<ol>
<li>
<a href="#id-anchor">id</a>
</li>
</ol>
</li>
</ol>
</li>
</ol>
</div>
<!-- /TABLE OF CONTENTS -->
<!-- Standard content lead-in for experimental API pages -->
<p id="classSummary" style="display: none; ">
For information on how to use experimental APIs, see the <a href="experimental.html">chrome.experimental.* APIs</a> page.
</p>
<!-- STATIC CONTENT PLACEHOLDER -->
<div id="static"><div id="pageData-name" class="pageData">Permission Warnings</div>
<div id="pageData-showTOC" class="pageData">true</div>
<!--
NOTE: When this doc is updated, the online help should also be updated:
http://www.google.com/support/chrome_webstore/bin/answer.py?hl=en&answer=186213
We should periodically look at
http://src.chromium.org/viewvc/chrome/trunk/src/chrome/app/generated_resources.grd?view=markup
to make sure that we're covering all messages. Search for
IDS_EXTENSION_PROMPT_WARNING
(e.g. IDS_EXTENSION_PROMPT_WARNING_BROWSING_HISTORY).
-->
<p>
To use most chrome.* APIs and extension capabilities,
your extension must declare its intent in the
<a href="manifest.html">manifest</a>,
often in the "permissions" field.
Some of these declarations
result in a warning when
a user installs your extension.
</p>
<p>
When you autoupdate your extension,
the user might see another warning
if the extension requests new permissions.
These new permissions might be new APIs that your extension uses,
or they might be new websites
that your extension needs access to.
</p>
<h2 id="examples"> Examples of permission warnings </h2>
<p>
Here's a typical dialog
that a user might see when installing an extension:
</p>
<img src="images/perms-hw1.png" width="410" height="193" alt="Permission warning: 'It can access: Your data on api.flickr.com'">
<p>
The warning about access to data on api.flickr.com
is caused by the following lines
in the extension's manifest:
</p>
<pre>"permissions": [
<b>"http://api.flickr.com/"</b>
],
</pre>
<p class="note">
<b>Note:</b>
You don't see permission warnings when
you load an unpacked extension.
You get permission warnings only when you install an extension
from a <code>.crx</code> file.
</p>
<p>
If you add a permission to the extension when you autoupdate it,
the user might see a new permission warning.
For example,
assume you add a new site and the "tabs" permission
to the previous example:
</p>
<pre>"permissions": [
"http://api.flickr.com/",
<b>"http://*.flickr.com/",
"tabs"</b>
],
</pre>
<p>
When the extension autoupdates,
the increased permissions
cause the extension to be disabled
until the user re-enables it.
Here's the warning the user sees:
</p>
<img src="images/perms-hw2-disabled.png" width="814" height="30" alt="Warning text: 'The newest version of the extension Hello World requires more permissions, so it has been disabled. [Re-enable].'">
<p>
Clicking the Re-enable button
brings up the following warning:
</p>
<img src="images/perms-hw2.png" width="412" height="220" alt="Permission warning: 'It can access: Your data on api.flickr.com and flickr.com; Your browsing history'">
<h2 id="warnings"> Warnings and their triggers </h2>
<p>
It can be surprising when adding a permission such as "tabs"
results in the seemingly unrelated warning
that the extension can access your browsing activity.
The reason for the warning is that
although the <code>chrome.tabs</code> API
might be used only to open new tabs,
it can also be used to see the URL that's associated
with every newly opened tab
(using their <a href="tabs.html#type-Tab">Tab</a> objects).
</p>
<p class="note">
<b>Note:</b>
As of Google Chrome 7,
you no longer need to specify the "tabs" permission
just to call <code>chrome.tabs.create()</code>
or <code>chrome.tabs.update()</code>.
</p>
<p>
The following table lists the warning messages
that users can see,
along with the manifest entries
that trigger them.
</p>
<p>
</p><table>
<tbody><tr>
<th>Warning message</th> <th>Manifest entry that causes it</th> <th>Notes</th>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_FULL_ACCESS -->
All data on your computer and the websites you visit
</td>
<td>
"plugins"
</td>
<td>
The "plugins" permission is required by
<a href="npapi.html">NPAPI plugins</a>.
</td>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_BOOKMARKS -->
Your bookmarks
</td>
<td>
"bookmarks" permission
</td>
<td>
The "bookmarks" permission is required by the
<a href="bookmarks.html"><code>chrome.bookmarks</code></a> module.
</td>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_BROWSING_HISTORY -->
Your browsing history
</td>
<td>
<!-- HasEffectiveBrowsingHistoryPermission -->
"history" permission
</td>
<td>
<p>
The "history" permission is required by
<a href="history.html"><code>chrome.history</code></a>.
</p>
</td>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_TABS -->
Your tabs and browsing activity
</td>
<td>
<!-- HasEffectiveBrowsingHistoryPermission -->
"tabs" permission
</td>
<td>
<p>
The "tabs" permission is required by the
<a href="tabs.html"><code>chrome.tabs</code></a> and
<a href="windows.html"><code>chrome.windows</code></a> modules.
</p>
</td>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_ALL_HOSTS -->
Your data on all websites
</td>
<td>
<!-- HasEffectiveAccessToAllHosts() -->
Any of the following:
<ul>
<li> "proxy" permission </li>
<li> "debugger" permission </li>
<li> A match pattern in the "permissions" field
that matches all hosts </li>
<li> A "content_scripts" field with a "matches" entry
that matches all hosts </li>
<li> "devtools_page" (experimental) </li>
</ul>
</td>
<td>
<p>
The "proxy" permission is required by the
<a href="experimental.proxy.html">experimental proxy</a> module.
</p>
<p>
The "debugger" permission is required by the
<a href="experimental.debugger.html">experimental debugger</a> module.
</p>
<p>
Any of the following URLs match all hosts:
</p>
<ul>
<li> <code>http://*/*</code> </li>
<li> <code>https://*/*</code> </li>
<li> <code>*://*/*</code> </li>
<li> <code><all_urls></code> </li>
</ul>
</td>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_?_HOST -->
<!-- IDS_EXTENSION_PROMPT_WARNING_4_OR_MORE_HOSTS -->
Your data on <em>{list of websites}</em>
</td>
<td>
A match pattern in the "permissions" field
that specifies one or more hosts,
but not all hosts
</td>
<td>
<p>
Up to 3 sites are listed by name.
Subdomains aren't treated specially.
For example, <code>a.com</code> and <code>b.a.com</code>
are listed as different sites.
</p>
<p>
On autoupdate,
the user sees a permission warning
if the extension adds or changes sites.
For example, going from <code>a.com,b.com</code>
to <code>a.com,b.com,c.com</code>
triggers a warning.
Going from <code>b.a.com</code>
to <code>a.com</code>,
or vice versa,
also triggers a warning.
</p>
</td>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_MANAGEMENT -->
Your list of installed apps, extensions, and themes
<br>
<span style="font-weight:normal; font-style:italic">or</span>
<br>
Manage themes, extensions, and apps
<!-- PENDING: remove "Manage...apps" alternative message
once the fix is out on stable channel -->
<!-- See http://crbug.com/67859 -->
</td>
<td>
"management" permission
</td>
<td>
The "management" permission is required by the
<a href="management.html"><code>chrome.management</code></a> module.
</td>
</tr>
<tr>
<td style="font-weight:bold">
<!-- IDS_EXTENSION_PROMPT_WARNING_GEOLOCATION -->
Your physical location
</td>
<td>
"geolocation" permission
</td>
<td>
Allows the extension to use the proposed HTML5
<a href="http://dev.w3.org/geo/api/spec-source.html">geolocation API</a>
without prompting the user for permission.
</td>
</tr>
</tbody></table>
<p></p>
<h2 id="nowarning"> Permissions that don't cause warnings </h2>
<p>
The following permissions don't result in a warning:
</p>
<ul>
<li>"chrome://favicon/"</li>
<li>"contextMenus"</li>
<li>"cookies"</li>
<li>"experimental"</li>
<li>"idle"</li>
<li>"notifications"</li>
<li>"unlimitedStorage"</li>
</ul>
<h2 id="test"> Testing permission warnings </h2>
<p>
If you'd like to see exactly which warnings your users will get,
<a href="packaging.html">package your extension</a>
into a <code>.crx</code> file,
and install it.
</p>
<p>
To see the warnings users will get when your extension is autoupdated,
you can go to a little more trouble
and set up an autoupdate server.
To do this, first create an update manifest
and point to it from your extension,
using the "update_url" key
(see <a href="autoupdate.html">Autoupdating</a>).
Next, <a href="packaging.html">package the extension</a>
into a new <code>.crx</code> file,
and install the app from this <code>.crx</code> file.
Now, change the extension's manifest to contain the new permissions,
and <a href="packaging.html#update">repackage the extension</a>.
Finally, update the extension
(and all other extensions that have outstanding updates)
by clicking the <b>chrome://extensions</b> page's
<b>Update extensions now</b> button.
</p>
</div>
<!-- API PAGE -->
<div class="apiPage" style="display: none; ">
<a name="apiReference"></a>
<h2>API reference: chrome.apiname </h2>
<!-- PROPERTIES -->
<div class="apiGroup">
<a name="properties"></a>
<h3 id="properties">Properties</h3>
<div>
<a></a>
<h4>getLastError</h4>
<div class="summary">
<!-- Note: intentionally longer 80 columns -->
<span>chrome.extension</span><span>lastError</span>
</div>
<div>
</div>
</div>
</div> <!-- /apiGroup -->
<!-- METHODS -->
<div id="methodsTemplate" class="apiGroup">
<a></a>
<h3>Methods</h3>
<!-- iterates over all functions -->
<div class="apiItem">
<a></a> <!-- method-anchor -->
<h4>method name</h4>
<div class="summary"><span>void</span>
<!-- Note: intentionally longer 80 columns -->
<span>chrome.module.methodName</span>(<span><span>, </span><span></span>
<var><span></span></var></span>)</div>
<div class="description">
<p class="todo">Undocumented.</p>
<p>
A description from the json schema def of the function goes here.
</p>
<!-- PARAMETERS -->
<h4>Parameters</h4>
<dl>
<div>
<div>
</div>
</div>
</dl>
<!-- RETURNS -->
<h4>Returns</h4>
<dl>
<div>
<div>
</div>
</div>
</dl>
<!-- CALLBACK -->
<div>
<div>
<h4>Callback function</h4>
<p>
The callback <em>parameter</em> should specify a function
that looks like this:
</p>
<p>
If you specify the <em>callback</em> parameter, it should
specify a function that looks like this:
</p>
<!-- Note: intentionally longer 80 columns -->
<pre>function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>;</pre>
<dl>
<div>
<div>
</div>
</div>
</dl>
</div>
</div>
<!-- MIN_VERSION -->
<p>
This function was added in version <b><span></span></b>.
If you require this function, the manifest key
<a href="manifest.html#minimum_chrome_version">minimum_chrome_version</a>
can ensure that your extension won't be run in an earlier browser version.
</p>
</div> <!-- /description -->
</div> <!-- /apiItem -->
</div> <!-- /apiGroup -->
<!-- EVENTS -->
<div id="eventsTemplate" class="apiGroup">
<a></a>
<h3>Events</h3>
<!-- iterates over all events -->
<div class="apiItem">
<a></a>
<h4>event name</h4>
<div class="summary">
<!-- Note: intentionally longer 80 columns -->
<span class="subdued">chrome.bookmarks</span><span>onEvent</span><span class="subdued">.addListener</span>(function(<span>Type param1, Type param2</span>) <span class="subdued">{...}</span>);
</div>
<div class="description">
<p class="todo">Undocumented.</p>
<p>
A description from the json schema def of the event goes here.
</p>
<!-- PARAMETERS -->
<div>
<h4>Parameters</h4>
<dl>
<div>
<div>
</div>
</div>
</dl>
</div>
</div> <!-- /decription -->
</div> <!-- /apiItem -->
</div> <!-- /apiGroup -->
<!-- TYPES -->
<div class="apiGroup">
<a name="types"></a>
<h3 id="types">Types</h3>
<!-- iterates over all types -->
<div class="apiItem">
<a></a>
<h4>type name</h4>
<div>
</div>
</div> <!-- /apiItem -->
</div> <!-- /apiGroup -->
</div> <!-- /apiPage -->
</div> <!-- /gc-pagecontent -->
</div> <!-- /g-section -->
</div> <!-- /codesiteContent -->
<div id="gc-footer" --="">
<div class="text">
<p>
Except as otherwise <a href="http://code.google.com/policies.html#restrictions">noted</a>,
the content of this page is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons
Attribution 3.0 License</a>, and code samples are licensed under the
<a rel="license" href="http://code.google.com/google_bsd_license.html">BSD License</a>.
</p>
<p>
©2011 Google
</p>
<!-- begin analytics -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
<script src="http://www.google-analytics.com/ga.js" type="text/javascript"></script>
<script type="text/javascript">
// chrome doc tracking
try {
var engdocs = _gat._getTracker("YT-10763712-2");
engdocs._trackPageview();
} catch(err) {}
// code.google.com site-wide tracking
try {
_uacct="UA-18071-1";
_uanchor=1;
_uff=0;
urchinTracker();
}
catch(e) {/* urchinTracker not available. */}
</script>
<!-- end analytics -->
</div>
</div> <!-- /gc-footer -->
</div> <!-- /gc-container -->
</body></html>